# Welcome to CAPyBARA Documentation

**CAPyBARA** - Coronagraph and Aberration Python Based Algorithm for Roman Analysis

CAPyBARA simulates observing sequences with the Roman Space Telescope Coronagraphic Instrument (CGI), from dark zone digging using high-order wavefront sensing and control (HOWFSC) to science target acquisitions.

```{note}
CAPyBARA is currently in **beta** (v0.1.x). The API may change as development continues. See the [Roadmap](roadmap) for planned features.
```

---

## Getting Started

New to CAPyBARA? Start here:

1. **[Installation](installation)** - Set up your environment
2. **[Quick Start](quickstart)** - Run your first simulation in 10 minutes  
3. **[Workflow Guide](workflow)** - Understand the complete execution flow

---

```{toctree}
:maxdepth: 2
:caption: User Guide

installation
quickstart
workflow
configuration
outputs
```

```{toctree}
:maxdepth: 2
:caption: Reference

api
```

```{toctree}
:maxdepth: 1
:caption: Development

contributing
changelog
roadmap
```

---

## About

### Project Status

CAPyBARA is in active development as part of the **ESCAPE** project (ERC Grant No. 101044152).

**Current version:** v0.1.x (beta)

**What's working:**
- Jacobian matrix generation
- Fully observing sequence via Jupyter notebook
- Broadband and monochromatic EFC control loop and observing sequence 
- Probe (Dither) injection and reference star acquisition 
- Slew and roll science obseration with aberration drift_timeseriess 
- FITS output with proper headers and metadata 
- Contrast calculation and visualisation ultilities 

**Known limitations:**
- `run_CAPyBARA.py` for EFC/observation modes not yet functional (use notebook instead)
- Command-line time-series generaion incomplete
- API may change without warning (beta status)
- Typing and comprehensive exception handling are incomplete
- Some ultility functions have overlapping implementations 
- Error messages could be more informative
- Configuration files (and function files) may require adaptation depending on the use case

### Citation

If you use CAPyBARA in your research, please cite:

> Altinier, L et al. (2024). "ESCAPE project CAPyBARA: a Roman Coronagraph simulator for post-processing methods development." *Proc. SPIE* 13092, 1309258. [https://doi.org/10.1117/12.3019211](https://doi.org/10.1117/12.3019211)

### Licence

CAPyBARA is released under an **Academic Use Only** licence. Commercial use is strictly prohibited without prior written permission. See the [LICENSE](https://gitlab.lam.fr/escape/CAPyBARA/-/blob/main/LICENSE) file for full details.

### Funding

This project is funded by the **European Union** (ERC, ESCAPE, project No 101044152).

*Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.*

### Acknowledgements

This research made use of:
- **[HCIPy](https://docs.hcipy.org/)** - High-contrast imaging simulation framework (Por et al. 2018)
- **Roman CGI** - Coronagraph instrument design specifications from NASA/GSFC
- **Python scientific stack** - NumPy, SciPy, Matplotlib, Astropy

---

## Additional Resources

- **GitLab Repository**: [CAPyBARA on GitLab](https://gitlab.lam.fr/escape/CAPyBARA)
- **Issue Tracker**: [Report bugs or request features](https://gitlab.lam.fr/escape/CAPyBARA/-/boards)
- **SPIE Paper**: [Altinier et al. (2024)](https://doi.org/10.1117/12.3019211)
- **HCIPy**: [https://docs.hcipy.org/](https://docs.hcipy.org/)

---

## Authors

**Developed by:**
- **Alexis Lau** - Co-lead Developer
- **Lisa Altinier** - Co-lead Developer
- **Damien Camugli** - PwP contribution 
- **Élodie Choquet** - Principal investigator