# mazinlab/momospecsim architecture

> Architecture diagram of the GitHub repository mazinlab/momospecsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mazinlab/momospecsim
- Repository: https://github.com/mazinlab/momospecsim

## Overview

##### Project type and purpose
- This is a scientific simulation and data-reduction pipeline for the Multi-Object MKID Optical Spectrometer (MOMOS).
- It provides two main command-line entrypoints:
- `simulate.py` – generates a photon table by propagating a model spectrum through an optical path.
- `reduce.py` – ingests three photon tables (continuum, lamp, observation) and produces a calibrated spectrum via four sub-steps (MSF, order-sorting, wavecal, extraction).

##### File structure
- Top level:
- `benchdesign/` – auxiliary scripts for grating design, plotting, edge cases.
- `filterphot.pyx` – Cython module for fast photon filtering/throughput.
- `momospecsim/` – core Python package (modules for detector, optics, engine, MSF, simulation settings, spectra, linelists, simfiles, reduction steps, general utilities).
- `scripts/` – thin wrappers (`simulate.py`, `reduce.py`) plus their argument templates.
- `requirements.txt`, `setup.py` – dependency and packaging metadata.
- Configuration/data:
- `momospecsim/linelists/*.csv` – reference spectral lines for calibration.
- `momospecsim/simfiles/` – data files for atmosphere transmission, sky emission, fridge throughput.
- `benchdesign/*.txt` – master grating specifications.

##### README for additional insights
- Describes the two core scripts and the four reduction steps.
- Points to a user manual and an AAS paper for detailed algorithmic background.

a. Main components
- CLI Layer: `simulate.py`, `reduce.py`
- Simulation Engine: `momospecsim.engine`, `optics`, `detector`, `spectra`, `simsettings`
- Data Sources: linelists, simfiles (atmosphere, fridge, sky)
- Reduction Pipeline: `momospecsim.steps` submodules (`fitmsf`, `ordersort`, `wavecal`, `extract`)
- Bench-design Tools: `benchdesign` module (optional pre-processing)
- Cython Module: `filterphot` for throughput calculations
- Utilities: `momospecsim.utils`
- External Dependencies: numpy, scipy, Cython, etc.

b. Relationships and data flow
1. `simulate.py` → parses arguments → calls Simulation Engine
2. Engine reads `simsettings`, linelists, simfiles → applies `optics` & `detector` logic → uses `filterphot` where needed → outputs photon table
3. `reduce.py` → loads continuum lamp and observation photon tables
- Step 1 (MSF): uses `fitmsf` → generates spread function model
- Step 2 (Order-sort): uses `ordersort` with MSF → sorts lamp & obs photons into orders
- Step 3 (Wavecal): uses `wavecal` → matches sorted lamp photons to linelist → finds wavelength solution
- Step 4 (Extract): uses `extract` → applies wavecal to obs photons → produces final spectrum
4. Output spectra and diagnostic plots are written to disk.

c. Architectural patterns / design principles
- Modular package structure: separate core simulation logic vs. pipeline steps.
- Data-driven design: heavy use of CSV/dat files for inputs.
- CLI orchestration: thin script wrappers that invoke library code.
- High-performance Cython for critical loops (`filterphot.pyx`).

d. Key technologies / frameworks
- Python 3.x, numpy, scipy, Cython
- Custom modules: `momospecsim.*`
- Scripts: plain argparse or config-file–driven CLIs.

##### Detail
- Data artifacts (Photon Table, Calibrated Spectrum) as distinct nodes.
- External inputs (linelist CSVs, transmission DAT files) so nothing is lost.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        SimCLI["simulate.py\n(simulate_args.txt)"]:::cli
        ReduceCLI["reduce.py\n(reduce_args.txt)"]:::cli
    end

    %% Simulation Phase
    subgraph "Simulation Phase"
        subgraph "Core Engine" 
            Engine["engine.py"]:::core
            Optics["optics.py"]:::core
            Detector["detector.py"]:::core
            Spectra["spectra.py"]:::core
            Settings["simsettings.py"]:::core
        end
        Perf["filterphot.pyx"]:::perf
    end

    %% Reduction Pipeline
    subgraph "Reduction Pipeline"
        MSF["fitmsf.py"]:::core
        OrderSort["ordersort.py"]:::core
        WaveCal["wavecal.py"]:::core
        Extract["extract.py"]:::core
    end

    %% Data Sources
    subgraph "Data Sources"
        LineLists["linelists/*.csv"]:::data
        Atmosphere["transmission.dat"]:::data
        SkyEm["sky_emission.dat\nradiance.dat"]:::data
        Fridge["fridge_filter.csv"]:::data
    end

    %% Bench-Design Tools
    Bench["benchdesign/"]:::bench

    %% Utilities
    Utils["general.py"]:::core

    %% Data Artifacts
    PhotonTable["Photon Table"]:::data
    CalSpec["Calibrated Spectrum"]:::data

    %% Connections: CLI to Simulation
    SimCLI -->|invokes| Engine
    Engine -->|uses| Optics
    Engine -->|uses| Detector
    Engine -->|uses| Spectra
    Engine -->|reads| Settings
    Engine -->|calls| Perf
    Engine -->|outputs| PhotonTable

    %% Data Sources to Simulation
    LineLists -->|reference| Engine
    Atmosphere -->|input| Engine
    SkyEm -->|input| Engine
    Fridge -->|input| Engine

    %% Bench-design optional input
    Bench -->|parameterizes| Settings

    %% Reduction flow
    ReduceCLI -->|loads tables| PhotonTable
    PhotonTable --> MSF
    MSF --> OrderSort
    OrderSort --> WaveCal
    WaveCal --> Extract
    Extract --> CalSpec

    %% Data Sources to Reduction
    LineLists -->|calibration| WaveCal

    %% Utilities usage
    Utils -->|helper functions| Engine
    Utils -->|helper functions| MSF
    Utils -->|helper functions| OrderSort
    Utils -->|helper functions| WaveCal
    Utils -->|helper functions| Extract

    %% Click Events
    click SimCLI "https://github.com/mazinlab/momospecsim/blob/develop/scripts/simulate.py"
    click ReduceCLI "https://github.com/mazinlab/momospecsim/blob/develop/scripts/reduce.py"
    click Engine "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/engine.py"
    click Optics "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/optics.py"
    click Detector "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/detector.py"
    click Spectra "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/spectra.py"
    click Settings "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/simsettings.py"
    click LineLists "https://github.com/mazinlab/momospecsim/tree/develop/momospecsim/linelists/"
    click Atmosphere "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/simfiles/atmosphere/transmission.dat"
    click SkyEm "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/simfiles/sky_emission/sky_emission.dat"
    click Fridge "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/simfiles/fridge_thruput/fridge_filter.csv"
    click MSF "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/steps/fitmsf.py"
    click OrderSort "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/steps/ordersort.py"
    click WaveCal "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/steps/wavecal.py"
    click Extract "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/steps/extract.py"
    click Utils "https://github.com/mazinlab/momospecsim/blob/develop/momospecsim/utils/general.py"
    click Perf "https://github.com/mazinlab/momospecsim/blob/develop/filterphot.pyx"
    click Bench "https://github.com/mazinlab/momospecsim/tree/develop/benchdesign/"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef perf fill:#FFA500,stroke:#333,stroke-width:1px
    classDef bench fill:#DDA0DD,stroke:#333,stroke-width:1px
```
