Metadata-Version: 2.2
Name: mirage-optics-engine
Version: 1.0.2
Summary: Optics engine for coupled gradient-index light transport simulations.
Author-Email: Marwan Aarab <99marwan.a@gmail.com>
License: PolyForm Noncommercial License 1.0.0
Classifier: License :: Other/Proprietary License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
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 :: C++
Classifier: Topic :: Scientific/Engineering
Project-URL: Homepage, https://marwanaarab.com/software.html
Requires-Python: <3.13,>=3.10
Requires-Dist: numpy>=1.23
Description-Content-Type: text/markdown

<!--
Image hosting placeholders for PyPI/TestPyPI rendering.
Replace these with public HTTPS URLs when you host the images.

PYPI_IMAGE_VAM_SUMMARY_URL=https://marwanaarab.com/assets/images/tvamshowcase.png
PYPI_IMAGE_COUPLING_SCHEME_URL=https://marwanaarab.com/assets/images/coupling_scheme.png
-->

<img src="https://marwanaarab.com/assets/images/tvamshowcase.png" alt="VAM cone process summary and striation prediction" width="300" style="max-width: 100%; height: auto;" />


# Mirage Coupled Optics Engine (Python)

[![Optics Express paper](https://img.shields.io/badge/DOI-10.1364/OE.582633-9E4394)](https://doi.org/10.1364/OE.582633)

Mirage is a GPU-accelerated coupled optics and curing physics engine.
It can model additive manufacturing workflows, but is not limited to additive manufacturing applications.

Mirage can be used as a foundational physics engine to build vat photopolymerization workflows, including Digital Light Processing (DLP) and Tomographic Volumetric Additive
Manufacturing (TVAM) simulations.

This package distributes the compiled Python bindings for Mirage Optics and its built-in curing submodules.

- Distribution name: `mirage-optics-engine`
- Import namespace: `mirage`

## Capabilities

Standard ray tracers are usually not built to couple natively with multi-physics (finite element) solvers.
Mirage Optics is designed exactly for that workflow.

Core capabilities:

- GPU-accelerated finite-element ray tracing
- Volumetric light transport and absorption in gradient-index and gradient-absorptivity media
- Boundary-condition-based interface modeling:
  - reflection
  - refraction
  - rough-surface scattering
- Coupling-friendly architecture for external physics modules
- Proprietary ASCII ray collection format (`.ry`) for [custom ray generators](https://github.com/m-aarab/DMDprojector-raydiscretizer)
- Built-in accelerated curing submodules:
  - `energythreshold`
  - `reactiondiffusion`
- Designed to serve as a reusable simulation engine for process-level toolchains

## Coupling Picture

The figure below highlights the coupling interface between optics and other modules.

<img src="https://marwanaarab.com/assets/images/coupling_scheme.png" alt="Coupling interface between optics and external modules" width="500" style="max-width: 100%; height: auto;" />

## Install

```bash
pip install mirage-optics-engine
```

Quick import check:

```python
from mirage import optics_engine, energythreshold, reactiondiffusion
print("MIRAGE import OK")
```

## Attribution and Citation

If you use MIRAGE in academic work, please provide attribution and cite the relevant paper(s).

Optics module:

```bibtex
@article{aarab2026fert,
    title = "Fast Hessian-free finite element ray tracing method for light transport in gradient-index media",
    author = "Marwan Aarab and Geers, \{Marc G.D.\} and Remmers, \{Joris J.C.\}",
    year = "2026",
    doi = "10.1364/OE.582633",
    volume = "34",
    pages = "10749--10769",
    journal = "Optics Express",
    publisher = "Optica Publishing Group",
    number = "6",
}
```

Reaction-diffusion module:

```bibtex
@inproceedings{aarab2026optochem,  
    title = "High performance coupled opto-chemical simulation of gradient-index light transport in vat photopolymerization",
    author = "M. Aarab and Geers, \{Marc G.D.\} and J.J.C. Remmers",
    year = "2026",
    doi = "10.1117/12.3100381",
    series = "Proceedings of SPIE",
    publisher = "SPIE",
    editor = "Herkommer, \{Alois M.\} and \{von Freymann\}, Georg and Manuel Flury",
    booktitle = "3D Printed Optics and Additive Photonic Manufacturing V",
    address = "United States",
}
```


## System and Version Requirements (Summary)

- Linux x86_64
- Python >= 3.10 and < 3.13
- NVIDIA GPU with compute capability >= SM60
- CUDA runtime compatibility for wheel build/runtime expectations
- NumPy >= 1.23

## License

This package is released under the PolyForm Noncommercial License 1.0.0.

It is intended for non-commercial use.