Metadata-Version: 2.4
Name: oreonspy
Version: 4.4.4
Summary: Optical resonator numerical simulation in python.
Project-URL: Homepage, https://git.ligo.org/mateusz.bawaj/oreonspy
Project-URL: Issues, https://git.ligo.org/mateusz.bawaj/oreonspy/issues
Author-email: Andrea Svizzeretto <andrea.svizzeretto@studenti.unipg.it>, Mateusz Bawaj <mateusz.bawaj@unipg.it>
Maintainer-email: Andrea Svizzeretto <andrea.svizzeretto@studenti.unipg.it>, Mateusz Bawaj <mateusz.bawaj@unipg.it>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: batch,optics,real-time,simulation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.23
Provides-Extra: numba
Requires-Dist: numba>=0.60; extra == 'numba'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# OreoNSpy

Optical resonator numerical simulation in Python.

Current package version: 4.4.4

## Requirements

- Python >= 3.10
- numpy >= 1.23
- matplotlib >= 3.5
- Optional acceleration: numba >= 0.60

## Installation

```bash
git clone https://github.com/matib12/oreonspy.git
cd oreonspy
```

### Inside conda evironment

```bash
conda env create --file=environment.yml --name=oreonspy
```

Activate the environment:

```bash
conda activate oreonspy
```

### Using pip

Install from this repository:

```bash
pip install .
```

or Install in editable mode for development:

```bash
pip install -e .
```

or Install optional numba support:

```bash
pip install .[numba]
```

or Build a wheel:

```bash
python -m build
```

## Quick Start

```python
import numpy as np
import oreonspy as op

# Build a cavity
cavity = op.Cavity(t_a=0.1, r_a=0.9, r_b=0.9, cavity_length=3000.0)

# Initialize simulation
lambd = 1064e-9
requested_sampling_frequency = 1450e3
initial_input_electric_field = 1.0 + 0.0j
cavity.simulation(
	lambd,
	requested_sampling_frequency,
	initial_input_electric_field,
	backend="auto",  # "auto" | "pure" | "numba"
)

cavity.print_sim_params()

# One simulation step
intracavity_field, reflected_field = cavity.sim_step(
	input_electric_field=1.0 + 0.0j,
	input_mirror_displacement=0.0,
	output_mirror_displacement=0.0,
)
```

## Loading a Cavity from XML

```python
cavity = op.Cavity.xml_load("path/to/cavity_config.xml")
cavity.simulation(lambd, requested_sampling_frequency, initial_input_electric_field)
cavity.sim_step(input_electric_field=1.0 + 0.0j)
```

## Examples

The repository includes practical notebook examples in the `nb` folder.

- Main tutorial: `nb/example.ipynb`
- Sampling and simulator checks: `nb/Resampling test.ipynb`
- Notebook for accompanying paper: `nb/Reproduce figure 2 from Lee at al 1999.ipynb`
- Notebook for accompanying paper: `nb/Reproduce figure 2 from Xue et al 2026.ipynb`

We suggest to start from the `nb/example.ipynb`

## Simulation Results

The following image shows a linear scan of the optical cavity with constant mirror velocity, demonstrating the cavity's response characteristics:


<img src="nb/Linear_scan_of_the_cavity_with_constant_velocity.png" width="600">

## Public API

- Cavity
- HAS_NUMBA

## Repository Structure

- nb: Jupyter notebooks
- src: Python package source code
- tests: optical cavity configuration files used in the accompanying paper

## Citation

If you use **OreoNSpy** in your research, please cite the accompanying paper:

```bibtex
 @article{Svizzeretto_2026, 
	title={Adaptive Time-Domain Simulation of Optical Cavities with Arbitrary Dynamics}, 
	volume={13}, 
	ISSN={2304-6732}, 
	url={http://dx.doi.org/10.3390/photonics13070605}, 
	DOI={10.3390/photonics13070605}, 
	number={7}, 
	journal={Photonics}, 
	publisher={MDPI AG}, 
	author={Svizzeretto, Andrea and Diaz, Julia Casanueva and Swinkels, Bas L. and Bawaj, Mateusz}, 
	year={2026}, 
	month=June, 
	pages={605} 
}
```

If you directly use the software implementation, please also cite the software release:

```bibtex
@software{oreonspy,
	author  = {Mateusz Bawaj and Andrea Svizzeretto},
	title   = {OreoNSpy: Optical Resonator Numerical Simulation in Python},
	version = {4.4.4},
	year    = {2026},
	doi     = {10.5281/zenodo.19567205},
	url     = {https://github.com/matib12/oreonspy}
}
```

## Project Links

- **GitHub repository:** https://github.com/matib12/oreonspy
- **Documentation / preprint:** https://doi.org/10.48550/arXiv.2605.13599

[![DOI](https://zenodo.org/badge/1209379537.svg)](https://doi.org/10.5281/zenodo.19567205)