Atmospheric model¶

bolojax computes atmospheric brightness temperature and transmission using am (Scott Paine’s atmospheric radiative transfer code). Internally, it uses am-python to dispatch am calls.

How it works¶

An am configuration file (.amc) defines the atmospheric layer structure, molecular abundances, and spectral line parameters for a given site and season. Runtime parameters are passed to am through positional placeholders (%1, %2, …) in the .amc file.

Rather than calling am for every parameter combination at runtime, bolojax pre-computes a grid of atmosphere profiles across the Cartesian product of the varying parameters. The grid is cached to disk, so subsequent runs load instantly.

At evaluation time, each sampled parameter combination is matched to the nearest grid point, and the brightness temperature and transmission spectra are interpolated onto the channel’s frequency grid.

Configuration¶

The atmosphere is configured in the universe.atmosphere section of the YAML config:

universe:
  atmosphere:
    amc_file: SPole_annual_median_MERRA2_2007-2016.amc
    amc_args: [0, 300, zenith, pwv_scale]
    profile_pwv_mm: 0.425

Fields¶

amc_file: Path to an am configuration file defining the atmospheric layer structure and spectral properties for a given site.
amc_args: The argument list passed to am, corresponding positionally to the %1, %2, … placeholders in the .amc file. Numeric entries are static. The keywords zenith and pwv_scale are resolved at runtime from the instrument’s elevation and PWV fields.
profile_pwv_mm: The reference PWV (in mm) baked into the .amc profile. Used by the pwv_scale derived parameter to compute the water vapor scaling factor.

Observational parameters¶

Dynamic atmosphere parameters are configured on the instrument (not the atmosphere) because they are observational quantities that may be sampled from distributions:

instrument:
  elevation:
    var_type: pdf
    fname: Pdf/elevation_pole.txt
  pwv:
    var_type: pdf
    fname: Pdf/pwv_pole.txt

For deterministic evaluation (for example, Fisher analysis), use fixed scalars:

instrument:
  elevation: 60.0
  pwv: 0.6

Parameter resolution¶

The two dynamic parameters, elevation and PWV, are resolved from amc_args string entries via built-in transforms:

Keyword	Source	Transform	Grid step
`zenith`	`elevation`	`90 - elevation`	1°
`pwv_scale`	`pwv`	`pwv / profile_pwv_mm`	0.1 mm

Numeric entries in amc_args are passed to am as-is. For amc_args: [0, 300, zenith, pwv_scale]:

0 and 300 set the frequency range (static)
zenith is computed from the instrument’s elevation field
pwv_scale is computed from the instrument’s pwv field

Grid¶

Grid extents are inferred lazily from the sampled parameter values; no manual grid specification is needed. On first evaluation, a regular grid is built covering the sampled range at each parameter’s grid step.

For a typical South Pole configuration (PWV 0.2–1.6 mm at 0.1 mm step, elevation 55–65° at 1° step), this produces ~170 profiles. Subsequent runs load from cache.

Backends¶

`AmAtm` (primary)¶

Computes atmosphere profiles from an .amc file using am-python. Builds a 2D grid over elevation and PWV, caches to disk, and performs nearest-neighbor lookup at evaluation time.

`AtmProfile` (fallback)¶

Loads a single fixed atmosphere profile from a text file (three columns: frequency in GHz, brightness temperature in K, transmission). Ignores all runtime parameters. Activated by custom_atm_file on the instrument config:

instrument:
  custom_atm_file: Bands/atacama_atm.txt

No atmosphere¶

If neither amc_file nor custom_atm_file is configured, the atmosphere model returns None and no atmospheric effects are applied.

Shipped profiles¶

bolojax ships one .amc profile:

SPole_annual_median_MERRA2_2007-2016.amc — South Pole annual median atmosphere derived from MERRA-2 reanalysis (2007–2016), profile_pwv_mm = 0.425.

Custom .amc files for other sites (e.g. Atacama, balloon altitudes) can be used by pointing amc_file to the file and adjusting amc_args to match the file’s placeholder conventions.