Configuration Reference

Configuration Reference

These options are compiled into the atmosphere core only when it is built with MUSICA=true. Defaults and meanings below come from the v2026.08.01 Registry.xml.

Chemistry

Option	Default	Meaning
config_micm_file	empty	MICM mechanism file; empty disables chemistry
config_chem_tracer_output_unit	mmr	Global tracer output unit: mmr, fraction, percent, ppmv, ppbv, or pptv
config_chem_tracer_output_overrides	empty	Exact comma-separated overrides such as O3=ppmv,NO=ppbv
config_chem_substeps	1	MICM calls per chemistry event, each using the event interval divided by this value
config_micm_relative_tolerance	1.0e-6	MICM adaptive-solver relative tolerance
config_chemistry_ref_solve	.false.	Run a duplicate uncoupled reference solve; approximately doubles chemistry cost
config_chemistry_interval	0.0 s	0 solves every MPAS step; a positive value accumulates dynamics time between solves
config_chem_max_failures	3	Maximum consecutive recoverable chemistry failures before abort

Non-mmr selections add vmr_<species> diagnostics. The q<species> transport and restart variables remain mass mixing ratios. An override ending in =mmr suppresses the companion VMR field for that species.

Emissions

Option	Default	Meaning
config_miem_file	empty	MIEM configuration; empty disables emissions
config_miem_net_flux_species	empty	Exact comma-separated species allowed to have signed surface exchange
config_miem_diagnostic_sectors	empty	Exact MIEM sector names to expose
config_miem_diagnostic_categories	empty	Nonnegative category IDs to expose
config_miem_layered_diagnostics	.false.	Add per-layer total and requested group diagnostics
config_miem_max_diagnostic_fields	256	Cap on species × requested sector/category groups, times nVertLevels when layered diagnostics are enabled

Total fields use emis_<species>. Layered totals append _layer. Requested groups use sanitized names such as emis_NO__sector_finn_fire and emis_NO__category_100.

MIEM inventory requirements:

• Gregorian xtime records bracket the simulation;
• surface flux units are kg m-2 s-1;
• cells exactly match the global MPAS mesh and ascending indexToCellID ordering;
• exact-grid identity metadata and geometry agree with the run mesh; and
• a source-only field is finite and nonnegative unless its mechanism species is listed in config_miem_net_flux_species.

Photolysis

Option	Default	Meaning
config_tuvx_config_file	empty	TUV-x JSON; empty selects the optional cosine-SZA fallback
config_tuvx_top_extension	.false.	Consistency flag: true for either upper-column mode and false for none
config_tuvx_upper_column_mode	none	none, legacy_static, or spatial_climatology
config_tuvx_extension_file	empty	Static CSV required by legacy_static
config_tuvx_prescribed_field_file	empty	Exact-grid NetCDF required by spatial_climatology
config_tuvx_update_interval	0.0 s	0 updates every chemistry event; positive values reuse rates between updates
config_j_no2_max	0.0 s-1	Peak fallback jNO2 rate when TUV-x is disabled
config_chemistry_latitude	0.0 degrees N	Fixed idealized-case latitude
config_chemistry_longitude	0.0 degrees E	Fixed idealized-case longitude
config_chemistry_use_grid_coords	.false.	Use each cell's latCell/lonCell instead of the fixed coordinates

The static extension CSV columns are z_km,T_K,n_air_molec_cm3,n_O3_molec_cm3. The spatial package contract is documented in Data and Provenance.

Lightning NOx

Option	Default	Meaning
config_lnox_source_rate	0.0 ppbv s-1	Altitude mode: source at the reference vertical-velocity excess. Isotherm mode: constant source. Zero disables
config_lnox_w_threshold	5.0 m s-1	Minimum vertical velocity in both modes
config_lnox_w_ref	10.0 m s-1	Scale for velocity above the threshold; a nonpositive value disables lightning NOx in either mode
config_lnox_z_min	5000.0 m	Lower altitude bound above mean sea level
config_lnox_z_max	12000.0 m	Upper altitude bound above mean sea level
config_lnox_nox_tau	0.0 s	Optional timescale for matching LOSS.* reactions; zero disables
config_lnox_gating_mode	altitude	altitude or isotherm
config_lnox_t_min	233.15 K	Cold bound for isotherm mode
config_lnox_t_max	262.15 K	Warm bound for isotherm mode

Altitude-mode source scaling is rate * max(0, w - w_threshold) / w_ref inside the altitude bounds.

Minimal records

MICM only:

&chemistry
    config_micm_file = 'abba.yaml'
/

MICM plus TUV-x:

&chemistry
    config_micm_file = 'chapman_nox.yaml'
/

&photolysis
    config_tuvx_config_file = 'tuvx_chapman_nox.json'
    config_tuvx_top_extension = .true.
    config_tuvx_upper_column_mode = 'legacy_static'
    config_tuvx_extension_file = 'tuvx_upper_atm.csv'
    config_tuvx_update_interval = 3600.0
    config_chemistry_use_grid_coords = .true.
/

MIEM:

&emissions
    config_miem_file = 'global_mvp_cams_finn.yaml'
    config_miem_diagnostic_sectors = 'cams_harmonized_no_awb,finn_fire'
    config_miem_diagnostic_categories = '0,100'
    config_miem_layered_diagnostics = .false.
    config_miem_max_diagnostic_fields = 768
/