openghg_inversions.rhime.specs

Lightweight immutable specifications for RHIME models and runs.

class openghg_inversions.rhime.specs.AdditiveSigmaSettings(sigma_prior: dict[str, Any] | None = None, sigma_freq: str | None = None, sigma_per_site: bool = True, sigma_freq_anchor: str | datetime | datetime64 | Timestamp | None = None, use_minimum_error_floor: bool = False)

Bases: object

Serializable settings for additive model-data-mismatch error.

Parameters:

• sigma_prior – Prior for the additive model-error standard deviation.

• sigma_freq – Frequency of the latent model-error periods. None uses one period.

• sigma_per_site – Whether model error varies by observation site.

• sigma_freq_anchor – Optional anchor for fixed-duration periods.

• use_minimum_error_floor – Apply the prepared historical minimum total- error floor.

property required_prepared_inputs: tuple[str, ...]

Return prepared arrays owned by this likelihood.

sigma_freq: str | None = None

sigma_freq_anchor: str | datetime | datetime64 | Timestamp | None = None

sigma_per_site: bool = True

sigma_prior: dict[str, Any] | None = None

use_minimum_error_floor: bool = False

class openghg_inversions.rhime.specs.FixedErrorSettings

Bases: object

Serializable selection of reported observation error only.

property required_prepared_inputs: tuple[str, ...]

Return prepared arrays owned by this likelihood.

class openghg_inversions.rhime.specs.PollutionEventSettings(sigma_prior: dict[str, Any] | None = None, sigma_freq: str | None = None, sigma_per_site: bool = True, sigma_freq_anchor: str | datetime | datetime64 | Timestamp | None = None, pollution_events_from_obs: bool = False, power: dict[str, Any] | float = 1.99)

Bases: object

Serializable settings for pollution-event-scaled model error.

Parameters:

• sigma_prior – Prior for the observation-aligned fractional model error.

• sigma_freq – Frequency of the latent model-error periods. None uses one period.

• sigma_per_site – Whether model error varies by observation site.

• sigma_freq_anchor – Optional anchor for fixed-duration periods.

• pollution_events_from_obs – Derive pollution events from observations after removing the baseline instead of from modelled pollution.

• power – Exponent or prior used in pollution-event error scaling.

pollution_events_from_obs: bool = False

power: dict[str, Any] | float = 1.99

property required_prepared_inputs: tuple[str, ...]

Return prepared arrays owned by this likelihood.

sigma_freq: str | None = None

sigma_freq_anchor: str | datetime | datetime64 | Timestamp | None = None

sigma_per_site: bool = True

sigma_prior: dict[str, Any] | None = None

class openghg_inversions.rhime.specs.RhimeModelSpec(species: str, domain: str, sectors: tuple[SectorSpec, ...], use_bc: bool = True, add_offset: bool = False, bc_prior: dict[str, Any] | None = None, offset_prior: dict[str, Any] | None = None, offset_args: dict[str, Any] | None = None, *, likelihood: PollutionEventSettings | AdditiveSigmaSettings | FixedErrorSettings | None = None, aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'] = 'none', bc_state_activity: StateActivity | None = None, state_activity: StateActivity | None = None)

Bases: object

Scientific options used by the concrete RHIME model recipes.

Parameters:

• species – Primary gas or tracer name used for object-store lookup and output naming.

• domain – Model domain name.

• sectors – Flux sectors included in the model. Each sector is optimized separately and is normally backed by one OpenGHG flux source.

• use_bc – Whether boundary-condition scaling is included.

• likelihood – Resolved built-in likelihood settings, or None when a Python-only custom likelihood owns that step.

• add_offset – Whether model-data offsets are included.

• aggregation_error_mode – Fixed aggregation-error covariance representation. The default "none" preserves the ordinary model; other modes are an explicit opt-in.

• bc_prior – Prior specification for boundary-condition scaling factors.

• offset_prior – Prior specification for optional offsets.

• offset_args – Extra keyword arguments forwarded to the offset component.

• bc_state_activity – Optional active/fixed policy for the boundary- condition scaling vector. None preserves the ordinary fully sampled BC graph without zero pruning. Supplying a policy opts into active/fixed BC construction.

• state_activity – Optional labelled active/fixed state policy shared by flux sectors. The default retains exact-zero pruning.

add_offset: bool = False

aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'] = 'none'

bc_prior: dict[str, Any] | None = None

bc_state_activity: StateActivity | None = None

domain: str

likelihood: PollutionEventSettings | AdditiveSigmaSettings | FixedErrorSettings | None = None

offset_args: dict[str, Any] | None = None

offset_prior: dict[str, Any] | None = None

sectors: tuple[SectorSpec, ...]

species: str

state_activity: StateActivity | None = None

use_bc: bool = True

class openghg_inversions.rhime.specs.RhimeOutputSpec(output_format: Literal['none', 'inv_out', 'basic', 'paris', 'legacy'] = 'inv_out', output_path: str | None = None, output_name: str = 'rhime', save_trace: str | Path | bool = False, save_inversion_output: str | Path | bool = True, country_file: str | None = None, paris_postprocessing_kwargs: dict[str, Any] | None = None, output_filename_convention: Literal['rhime', 'legacy'] = 'rhime')

Bases: object

Output settings for a RHIME run.

Parameters:

• output_format – Output mode. "inv_out" saves/returns the modern inversion output, "basic" and "paris" additionally create derived outputs, "legacy" creates the old HBMCMC-compatible NetCDF product from modern RHIME output, and "none" skips output products.

• output_path – Directory for saved outputs.

• output_name – Base output name.

• save_trace – Trace save setting. If true, save to output_path using the default trace file name; if a path, save there.

• save_inversion_output – Inversion-output save setting. Runner parameter normalization defaults this to true for output_format="inv_out" and false for derived product formats.

• country_file – Optional country mask file used by derived outputs.

• paris_postprocessing_kwargs – Extra keyword arguments for PARIS output creation.

• output_filename_convention – Filename convention for derived products. Direct RHIME runs use "rhime". The run_hbmcmc.py compatibility shim uses "legacy" for old SLURM/config workflows.

country_file: str | None = None

output_filename_convention: Literal['rhime', 'legacy'] = 'rhime'

output_format: Literal['none', 'inv_out', 'basic', 'paris', 'legacy'] = 'inv_out'

output_name: str = 'rhime'

output_path: str | None = None

paris_postprocessing_kwargs: dict[str, Any] | None = None

save_inversion_output: str | Path | bool = True

save_trace: str | Path | bool = False

class openghg_inversions.rhime.specs.RhimeRunSpec(start_date: str, end_date: str, sites: tuple[str, ...], averaging_period: tuple[str | None, ...], model: RhimeModelSpec, output: RhimeOutputSpec, split_by_sectors: bool = False)

Bases: object

Top-level run metadata for a RHIME run.

Parameters:

• start_date – Inclusive inversion start date.

• end_date – Exclusive inversion end date.

• sites – Sites included after data preparation and filtering.

• averaging_period – Observation averaging period per retained site.

• model – Mathematical model specification.

• output – Output settings.

• split_by_sectors – Whether flux data were prepared in sector-resolved mode. Single-sector and multi-sector RHIME are runner/model modes; this flag records the prepared data layout.

averaging_period: tuple[str | None, ...]

end_date: str

model: RhimeModelSpec

output: RhimeOutputSpec

sites: tuple[str, ...]

split_by_sectors: bool = False

start_date: str

class openghg_inversions.rhime.specs.SectorSpec(name: str, flux_source: str, x_prior: dict[str, Any], variable_suffix: str, *, state_activity: StateActivity | None = None)

Bases: object

Configuration for one separately optimised flux sector.

Parameters:

• name – User-facing sector name.

• flux_source – OpenGHG flux source used to retrieve this sector.

• x_prior – Prior specification for this sector’s flux scaling factors.

• variable_suffix – PyMC-safe suffix used in multi-sector model variable names. Standard single-sector RHIME uses plain x/mu names.

• state_activity – Optional labelled active/fixed policy for this sector’s flux-scaling states. None still applies the default flux policy, fixing exactly-zero sensitivity columns to one.

flux_source: str

name: str

state_activity: StateActivity | None = None

variable_suffix: str

x_prior: dict[str, Any]

openghg_inversions.rhime.specs.make_output_spec(*, output_format: str, output_path: str | None, output_name: str, save_trace: str | Path | bool, save_inversion_output: str | Path | bool, country_file: str | None, paris_postprocessing_kwargs: dict[str, Any] | None, output_filename_convention: str, multisector: bool) → RhimeOutputSpec

Create validated output settings from normalized RHIME parameters.

Parameters:

• output_format – Requested product format.

• output_path – Optional default output directory.

• output_name – Base name for generated artifacts.

• save_trace – Trace-save setting or explicit path.

• save_inversion_output – Inversion-output save setting or explicit path.

• country_file – Optional country mask for derived products.

• paris_postprocessing_kwargs – Optional PARIS product settings.

• output_filename_convention – Naming convention for derived files.

• multisector – Whether the run is multisector.

Returns:

Validated immutable output specification.

Raises:

ValueError – If formats, paths, or model restrictions are inconsistent.

openghg_inversions.rhime.specs.validate_output_filename_convention(output_filename_convention: str) → None

Validate an output filename convention.

Parameters:

output_filename_convention – Requested filename convention.

Raises:

ValueError – If the convention is unsupported.

openghg_inversions.rhime.specs.validate_output_format(output_format: str) → None

Validate a RHIME output-format name.

Parameters:

output_format – Requested output-format name.

Raises:

ValueError – If the format is unsupported.

openghg_inversions.rhime.specs.validate_output_path_settings(*, output_format: str, output_path: str | None, save_trace: str | Path | bool, save_inversion_output: str | Path | bool, multisector: bool) → None

Validate output paths and single- versus multisector restrictions.

Parameters:

• output_format – Requested output format.

• output_path – Optional default output directory.

• save_trace – Trace-save setting or explicit path.

• save_inversion_output – Inversion-output save setting or explicit path.

• multisector – Whether the run is multisector.

Raises:

ValueError – If the format is incompatible with the model or a required default output directory is absent.