Metadata-Version: 2.5
Name: aocore
Version: 0.1.3
Summary: Shared conventions, conformance checks and optics primitives for the AO simulation stack.
Project-URL: Homepage, https://github.com/jacotay7/aocore
Project-URL: Repository, https://github.com/jacotay7/aocore
Project-URL: Issues, https://github.com/jacotay7/aocore/issues
Project-URL: Changelog, https://github.com/jacotay7/aocore/blob/main/CHANGELOG.md
Author-email: Jacob Taylor <jacobataylor7@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: adaptive-optics,conventions,fourier-optics,gpu,optics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: threadpoolctl>=3.0
Provides-Extra: cuda12
Requires-Dist: cupy-cuda12x[ctk]>=13.0; extra == 'cuda12'
Provides-Extra: cuda13
Requires-Dist: cupy-cuda13x[ctk]>=13.6; extra == 'cuda13'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# aocore

[![CI](https://github.com/jacotay7/aocore/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/aocore/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Shared conventions, conformance checks and optics primitives for the
adaptive-optics simulation stack**: aobasis, pyturb, getframes, makewfs,
solvephase, shmpipeline-ao and pyRTC.

The packages of the stack hand each other OPD maps, images, wind vectors and
slopes. aocore makes sure they mean the same thing by them:

- **[CONVENTIONS.md](https://github.com/jacotay7/aocore/blob/main/CONVENTIONS.md)** is the contract: array axes, pixel
  centres, units, propagation sign and normalization, RMS and Strehl
  definitions, Zernike orientation, wind and slope conventions, and who owns
  which primitive.
- **`aocore.conformance`** holds executable checks of the contract that every
  package runs against its own implementation in its test suite.
- **The primitives themselves**, implemented once:
  - a NumPy/CuPy array backend;
  - anti-aliased and segmented pupils with telescope presets;
  - FFT, matrix-Fourier, focal-plane and angular-spectrum propagators with
    exact adjoints;
  - wavefront metrics (`rms`, `rms_unweighted`, `rms_tiptilt_removed`),
    least-squares phase unwrapping, fast pixel binning (`block_sum`,
    `block_mean`), coordinate grids built on either device, and unit
    constants.

```bash
pip install aocore              # CPU
pip install "aocore[cuda12]"    # + CuPy for CUDA 12.x
```

```python
import aocore as ac

pupil = ac.Pupil.vlt(128)
prop = ac.FocalPlanePropagator(pupil.shape, pupil.pitch, 1.6e-6, 1.6e-6 / 8 / 2, (64, 64))
print(ac.rms(opd, pupil))  # CONVENTIONS 4.1: weighted, piston removed
print(ac.rms_unweighted(opd, pupil.mask))  # plain quadratic mean, piston included
print(ac.rms_tiptilt_removed(opd, pupil))  # weighted, piston/tip/tilt removed
y, x = ac.coordinate_grid(pupil.shape, pupil.pitch, backend="auto", dtype="float32")

# In any package's tests:
from aocore import conformance

conformance.check_tilt_direction(
    my_image_from_opd, pupil_shape=(64, 64), pitch=..., pixel_scale=...
)
```

aocore depends only on NumPy, SciPy and threadpoolctl. CuPy is optional.

## License

MIT. Every package in the stack except pyRTC (GPL-3.0-or-later) is MIT, and none
of them may copy GPL code (see CONVENTIONS 8.4).
