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 for planned features.

---

Getting Started

New to CAPyBARA? Start here:

1. Installation - Set up your environment

2. Quick Start - Run your first simulation in 10 minutes

3. Workflow Guide - Understand the complete execution flow

---

User Guide

• Installation
  • Prerequisites
• Quick Start
  • Prerequisites
  • Your First Simulation
  • Expected Output
  • Verification
  • Next Steps
  • Troubleshooting
  • Getting Help
• CAPyBARA Workflow Documentation
  • Introduction
  • Overview
  • Step 1: Initialisation & Jacobian Generation
  • Step 2: EFC Control Loop
  • Step 3: Reference Star Acquisition
  • Step 4: Science Target Acquisition
  • Step 5: Data Products and Outputs
  • Key Data Structures
  • Physical Units Reference
  • Execution Time Estimates
  • Random Seeds and Reproducibility
  • Common Issues and Debugging
  • Configuration Parameters Summary
  • Further Reading
  • Glossary
• Configuration Reference
  • Configuration File Structure
  • Section Reference
  • Complete Example Configuration
  • Configuration Tips
  • Validation
  • See Also
• Output Structure and Data Products
  • Introduction
  • Output Directory Structure
  • File Descriptions
  • Coronagraphic Image Cubes
  • DM Command Files
  • Aberration Cubes
  • Parameters Snapshot (JSON)
  • Execution Log
  • FITS Header Metadata
  • Common Headers
  • EFC-Specific Headers
  • Observation-Specific Headers
  • DM Command Headers
  • Normalisation Conventions
  • Image Normalisation
  • Broadband Averaging
  • Contrast Calculation
  • Physical Units Reference
  • File Size Estimates
  • Working with Output Files
  • Loading and Visualising
  • Calculating Contrast Evolution (when in the notebook)
  • Extracting Metadata
  • Archiving and Sharing
  • Best Practices
  • See Also

Reference

• API Reference
  • Quick Reference
  • Main Simulation Class
  • Module Index
  • See Also

Development

• Contributing to CAPyBARA
• Changelog
• CAPyBARA 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

Licence

CAPyBARA is released under an Academic Use Only licence. Commercial use is strictly prohibited without prior written permission. See the 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 - 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

• Issue Tracker: Report bugs or request features

• SPIE Paper: Altinier et al. (2024)

• HCIPy: 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