The simulator is built on a Hamilton dataflow framework — a directed graph of processing steps defined as Python functions. The base Simulator class (simulator.py) orchestrates this by loading modules and executing a Hamilton Driver.
Common Pipeline (all variants)¶
Every simulator runs the same four-stage pipeline:
Atmosphere → Limb Observation Geometry → Radiative Transfer (FER) → Instrument Model → (optional: POR + L2)
POR is the “program of record”: the background temperature, pressure and tropopause height the retrieval uses as ancillary data.
Atmosphere — builds atmospheric constituents (Rayleigh, O3, aerosol, solar irradiance, albedo)
Limb Observation — sets up viewing geometry with tangent altitudes + 450 km observer altitude
FER (Front-End Radiance) — runs SASKTRAN2 radiative transfer to produce Stokes I, Q, U
Instrument Model — converts FER → L1B measurements (this is where the variants diverge)
The Three Simulator Variants¶
cesm-hawc uses the imager variant (ideal_dolp_imager).
| Aspect | IdealALISimulator (Spectrograph) | IdealALISimulator (Imager) | ALIPhase0Simulator (Full) |
|---|---|---|---|
| File | ideal_spectrograph.py | ideal_dolp_imager.py | full_inst.py |
| Instrument step | ideal_inst | ideal_imager | full_inst |
| Measurement model | Direct Stokes I, Q, U | Mueller matrix from 3 polarization angles | Realistic L1A→L1B via ali_l1 package |
| Tangent altitudes | 10–40 km | −0.5–50 km | from −0.5 km |
| Wavelengths | Any, set by sample_wavelengths | Any, set by sample_wavelengths | 11 specific bands: 610–1560 nm |
| Error modeling | Fixed DOLP/AOLP/intensity uncertainties; noise added only if include_noise=True | Noise model propagated through the Mueller inversion, plus systematic errors | Realistic detector noise/gains |
| External dep | None | None | ali_l1 package required |
Spectrograph (ideal_inst)¶
inst_model.py / steps/ideal_inst.py
The simplest model. It directly measures Stokes parameters, with configurable Gaussian uncertainties:
intensity_error: 1% (default)dolp_error: 0.003aolp_error: 0.2°
Random noise with these uncertainties is added only when include_noise=True; by default the measurements are noise-free. It does not use the noise_model passed in l1b_cfg.
Can output any combination of I, dolp, aolp, q. This is the “ideal” in the sense that the instrument is assumed to directly observe polarization state without optical complexity.
Imager (ideal_imager)¶
inst_model_imager.py / steps/ideal_imager.py
More physically realistic polarimetric model. It simulates a filter-based imaging polarimeter that takes three measurements at polarization angles (-60°, 0°, 60°), then reconstructs Stokes I, Q, U via Mueller matrix inversion. This means:
Noise is propagated through the matrix inversion (not just added at the end)
Supports pointing errors (
pointing_error_1sigmaparameter)Tangent altitude range extends down to -500 m (ground level)
Phase 0 Full Instrument (full_inst)¶
configurations/full_inst.py / steps/full_inst.py
The highest-fidelity model, representing the actual planned ALI instrument. It uses the external ali_l1 package to simulate realistic L1A→L1B detector processing (gains, detector response, specific band filter set). Only operates at 11 specific wavelength bands (610–1560 nm) rather than a continuous spectrum. This configuration is not supported by CESM-HAWC for modelling studies.
Where to Look¶
In the hawc-simulator repository, the configuration classes are in src/hawcsimulator/ali/configurations/ and the step implementations are in src/hawcsimulator/ali/steps/. The notebook notebooks/ali/examples/quickstart.ipynb shows how to use these in practice.