Metadata-Version: 2.4
Name: opticalib
Version: 2.2.0
Summary: This package is a python interface for laboratory adaptive optics systems, with a focus on the calibration of deformable mirrors (DMs) and the acquisition of wavefront data using wavefront sensors.
Author-email: Adaptive Optics Group - INAF - Osservatorio Astrofisico di Arcetri <pietro.ferraiuolo@inaf.it>
Maintainer-email: Pietro Ferraiuolo <pietro.ferraiuolo@inaf.it>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ArcetriAdaptiveOptics/opticalib
Project-URL: Repository, https://github.com/ArcetriAdaptiveOptics/opticalib
Project-URL: Issues, https://github.com/ArcetriAdaptiveOptics/opticalib/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: arte
Requires-Dist: astropy
Requires-Dist: scikit-image
Requires-Dist: scikit-learn
Requires-Dist: vmbpy
Requires-Dist: pipython
Requires-Dist: photutils
Requires-Dist: scipy
Requires-Dist: ruamel.yaml
Requires-Dist: PyYAML
Requires-Dist: Pyro4
Requires-Dist: h5py
Requires-Dist: jdcal
Requires-Dist: tqdm
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: rbfgpu
Requires-Dist: xupy>=2.0
Requires-Dist: ipython
Provides-Extra: gui
Requires-Dist: PySide6-Essentials; extra == "gui"
Requires-Dist: QtPy; extra == "gui"
Requires-Dist: qtconsole; extra == "gui"
Requires-Dist: ipykernel; extra == "gui"
Requires-Dist: jupyter_client; extra == "gui"
Requires-Dist: pyqtgraph; extra == "gui"
Requires-Dist: qtawesome; extra == "gui"
Requires-Dist: psutil; extra == "gui"
Provides-Extra: cuda12
Requires-Dist: xupy[cuda12]>=2.0; extra == "cuda12"
Provides-Extra: cuda13
Requires-Dist: xupy[cuda13]>=2.0; extra == "cuda13"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: dev
Requires-Dist: opticalib[gui,test]; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# OptiCalib : python framework for OPTical CALibration of deformable mirrors and AO experimentation

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ArcetriAdaptiveOptics/opticalib/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/opticalib.svg)](https://pypi.org/project/opticalib/)
[![Python versions](https://img.shields.io/pypi/pyversions/opticalib.svg)](https://pypi.org/project/opticalib/)
[![License: MIT](https://img.shields.io/pypi/l/opticalib.svg)](LICENSE)

`Adaptive Optics Group, INAF - Osservatorio Astrofisico di Arcetri`

- [Pietro Ferraiuolo](mailto:pietro.ferraiuolo@inaf.it)

- [Marco Xompero](mailto:marco.xompero@inaf.it)

- [Runa Briguglio](mailto:runa.briguglio@inaf.it)

- [Matteo Menessini](mailto:matteo.menessini@inaf.it)

OptiCalib is a python package which first goal is to make easy deformable mirror's calibration in the laboratory (and not only).

It was born as a general extrapolation of the software built for the control and calibration of the `ELT @ M4` adaptive mirror and it's calibration tower, `OTT` (`Optical Test Tower`).

__Note__: to cite this package check [CITATION.bib](CITATION.bib)

## Description

The `OPTICALIB` package serves two main purposes:

- Making connection to the hardware (interferometers, DMs, ...) easy;

- Providing routines for Deformable Mirrors calibrations.

The latests, stable, version can be installed from pypi:

```bash
pip install opticalib
```

The base install contains everything needed to talk to the hardware, run the simulators and the calibration routines, and use the `calpy` shell. Two optional extras add the rest:

```bash
pip install "opticalib[gui]"      # the graphical interface (calpy --gui / OptiCalib)
pip install "opticalib[cuda13]"   # GPU backend (CuPy, via xupy); use cuda12 for CUDA 12.x
pip install "opticalib[gui,cuda13]"  # extras can be combined
```

The in-development version can be installed directly from this repository:

```bash
pip install git+"https://github.com/ArcetriAdaptiveOptics/opticalib.git"
```

**But do expect some bugs!**

Upon installation, the software will create an entry point script called `calpy`, which is usefull to set up a specific experiment's environment. Let's say we have an optical bench composed of an interferometer 4D PhaseCam6110 and an Alpao Deformable mirror, say DM820. We can create the experiment's environment just like:

```bash
calpy -f ~/alpao_experiment --create
```

This will create, in the `~/alpao_experiment` folder, the package's data folder tree, together with a configuration file in the `SysConfig` folder. The [configuration file](./opticalib/core/_configurations/configuration.yaml), documented in [configuration documentation](./opticalib/core/_configurations/DOCS.md), is where all devices must be specified.

### Example usage

Once done with the configuration, we can then start using out instruments:

```bash
calpy -f ~/alpao_experiment
```

```python
# The `calpy` function will automatically import opticalib (with `opt` 
# as alias), as well as the `opticalib.dmutils` as dmutils

interf = opt.PhaseCam(6110) # set in the configuration file
dm = opt.AlpaoDm(820)       # set in the configuration file

# Having the bench set up and the configuration file set, we can acquire
# an Influence Function by just doing

tn = dmutils.iff_module.iffDataAcquisition(dm, interf) # Optional paramenters
# are `modeslist, modesAmplitude, template`, which if not specified are 
# read from the configuration file
```

## Documentation

For the API references, check [Opticalib API PDF](docs/opticalib.pdf)
(work in progress...), while for configuration details check
[configuration documentation](./opticalib/core/_configurations/DOCS.md).

## Simulator data

Simulator data is no longer shipped inside the repository or Python package.
All files used by the simulator are fetched on demand and cached locally.

You can pre-download all known simulator files:

```python
from opticalib.simulator import prefetch_simdata

prefetch_simdata()
```

This avoids runtime downloads when simulators are instantiated.

The repository intentionally does not include the `opticalib/simulator/_API/SimData`
payload anymore.
