Metadata-Version: 2.4
Name: OOPAO
Version: 1.0.0
Summary: Object Oriented Python Adaptive Optics
Home-page: https://github.com/cheritier/OOPAO
Author: cheritier
Author-email: ctheritier@gmail.com
License: GPL-3.0-or-later
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: astropy
Requires-Dist: joblib
Requires-Dist: jsonpickle
Requires-Dist: matplotlib
Requires-Dist: mpmath
Requires-Dist: numba
Requires-Dist: numexpr
Requires-Dist: psutil
Requires-Dist: pyFFTW
Requires-Dist: scikit-image
Requires-Dist: scipy
Requires-Dist: tqdm
Provides-Extra: cuda
Requires-Dist: cupy; extra == "cuda"
Dynamic: license-file

# OOPAO

Object-Oriented Python Adaptive Optics (OOPAO) is a project under development to propose a python-based tool to perform end-to-end AO simulations.
This code is inspired from the OOMAO architecture: https://github.com/cmcorreia/LAM-Public developped by C. Correia and R. Conan (https://doi.org/10.1117/12.2054470). 
The project was initially intended for personal use in the frame of an ESO project. It is now open to any interested user. 

## DOCUMENTATION 

The OOPAO documentation is here:  https://cheritier.github.io/OOPAO/index.html

## FUNCTIONALITIES

	_ Atmosphere: 		Multi-layers with infinitely and non-stationary phase screens, conditions can be updated on the fly if required, scintillation can be simulated
	_ Telescope: 		Default circular pupil or user defined, with/without spiders
	_ Deformable Mirror:	Gaussian Influence Functions (default) or user defined, cartesian coordinates (default) or user defined
	_ WFS: 			Pyramid, SH-WFS (diffractive and geometric), Bi-O Edge
	_ Source: 		NGS or LGS
	_ Control Basis: 	KL modal basis, Zernike Polynomials

## MODULES REQUIRED
The code is written for Python 3 (version 3.8.8) and requires the following modules:
```
joblib          => paralleling computing
scikit-image    => 2D interpolations
astropy         => handling of fits files
pyFFTW          => optimization of the FFT  
mpmath          => arithmetic with arbitrary precision
jsonpickle      => json files encoding
aotools         => zernike modes and functionalities for atmosphere computation
numba           => required in aotools
numexpr 	=> optimized maths operations
psutil		=> access system info
mpmath		=> real and complex floating-point arithmetic with arbitrary precision
tqdm 		=> loading bar
```
If GPU computation is available:
```
cupy => GPU computation of the PWFS and SH code (Not required)
```

### Runtime backend and precision

`OOPAO_BACKEND=auto` (the default) uses CuPy when a CUDA device is usable and
otherwise uses NumPy. Set `OOPAO_BACKEND=cpu` to force NumPy, or
`OOPAO_BACKEND=cuda` to require a CUDA device and fail clearly when one is not
available. CuPy is optional for CPU use.

`OOPAO_PRECISION=32` or `64` selects the simulation precision for classes
using the runtime setting. When unset, OOPAO retains its legacy precision file.
Set these variables before importing OOPAO.

`OOPAO_GPU_RESIDENT=1` enables device-resident optical arrays on CUDA. This is
currently intended for the geometric atmosphere, DM, and unmodulated Pyramid
path. Source OPD and intensity, atmosphere layers, DM OPD, and the Pyramid raw
frame remain CuPy arrays between operations. Detector camera frames remain
NumPy arrays for existing consumers. The default (`0`) preserves the existing
public NumPy arrays. Off-axis/cone interpolation, modulated Pyramid paths, and
noise models can still use the CPU. On a CPU backend, the residency flag has no
effect.

## INSTALLATION 

### (Recommended) Creating a virtual environment

It is always recommended that you use a virtual environment. First create it:

```
python -m venv venv

# or

python3 -m venv venv

```

And finally activate it:

```
# Unix
source ./venv/bin/activate

# or

# Windows PowerShell
.\venv\Scripts\activate
```

After the environment is set up and activated, this package can then be easily installed. Anytime you wish to use this
package, you should activate the respective environment.

### Using `pip`

First clone the repository:

```
https://github.com/cheritier/OOPAO.git
```

And then install the package using `pip`:

```
python -m pip install -e OOPAO

# or 

python3 -m pip install -e OOPAO
```

To include CUDA acceleration, just specify the `[CUDA]` branch:

```
python -m pip install -e OOPAO[CUDA]

# or 

python3 -m pip install -e OOPAO[CUDA]
```

If you experience errors during the installation of one of the required scientific packages (e.g. `numpy`, `cupy`), 
please consider using a `conda` environment and installing these using `conda install`.


## CONTRIBUTORS
Main developer and maintainer: Cédric Taïssir Héritier

Main contributors: 
 - João Aveiro
 - Byron Engler
 - Arseniy Kuznetsov
 - Rafael Machado Salgueiro
 - Arnaud Striffling
 - Christophe Vérinaud
 - Jonathan Dray
 - João Monteiro
 - Matteo Pasinetti
 - Francisco Oyarzùn
 - Sylvain Cêtre

## CITING OOPAO
If you use OOPAO for your own research, we kindly ask you to cite the OOPAO AO4ELT7 proceeding (Heritier et al. 2023).
See https://hal.science/AO4ELT7/hal-04402878v1.

## ACKNOWLEDGEMENTS
This tool has been developped during the Engineering & Research Technology Fellowship of C. Héritier funded by ESO. 
Some functionalities of the code make use of the aotools package developped by M. J. Townson et al (2019). See https://doi.org/10.1364/OE.27.031316.


## LICENSE
This project is licensed under the terms of the GPL license.
