openghg_inversions.rhime.runner#

Modern public RHIME runner implementation.

This module accepts Python keyword arguments or RHIME .ini files, normalizes legacy spelling into the modern spec vocabulary, prepares inversion inputs, builds a PyMC model, samples it, and writes requested outputs.

Terminology used by the RHIME API:

  • species is the primary gas or tracer name used for object-store lookup and output naming.

  • source is the OpenGHG metadata key used to retrieve flux data. In sector-resolved inputs it is also the xarray coordinate on flux and sensitivity data.

  • flux_sources is the RHIME config/API field containing requested OpenGHG flux source values.

  • sector_sources optionally maps model sector names to OpenGHG flux source values when those labels differ.

  • sector is a model component optimized separately in a multi-sector RHIME run, usually backed by one flux source.

  • tracer is an additional species used to constrain the primary species, normally with linked forward models. The current RHIME preparation path does not support tracer inversions.

  • emissions_name is accepted only as a legacy compatibility spelling when flux_sources is absent.

class openghg_inversions.rhime.runner.RhimeModelSpec(species: str, domain: str, sectors: tuple[SectorSpec, ...], use_bc: bool = True, sigma_per_site: bool = True, add_offset: bool = False, pollution_events_from_obs: bool = False, no_model_error: bool = False, power: dict[str, Any] | float = 1.99, bc_prior: dict[str, Any] | None = None, sigma_prior: dict[str, Any] | None = None, offset_prior: dict[str, Any] | None = None, offset_args: dict[str, Any] | None = None)#

Bases: object

Model options used to build a RHIME PyMC model.

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.

  • sigma_per_site – Whether model-error terms vary by site.

  • add_offset – Whether model-data offsets are included.

  • pollution_events_from_obs – Whether model error scales with observed enhancements instead of modelled enhancements.

  • no_model_error – Whether explicit model-error terms are disabled.

  • power – Exponent or prior specification used in likelihood error scaling.

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

  • sigma_prior – Prior specification for model-error terms.

  • offset_prior – Prior specification for optional offsets.

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

add_offset: bool = False#
bc_prior: dict[str, Any] | None = None#
domain: str#
no_model_error: bool = False#
offset_args: dict[str, Any] | None = None#
offset_prior: dict[str, Any] | None = None#
pollution_events_from_obs: bool = False#
power: dict[str, Any] | float = 1.99#
sectors: tuple[SectorSpec, ...]#
sigma_per_site: bool = True#
sigma_prior: dict[str, Any] | None = None#
species: str#
use_bc: bool = True#
class openghg_inversions.rhime.runner.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.runner.RhimeResult(run_spec: RhimeRunSpec, model_spec: RhimeModelSpec, output_spec: RhimeOutputSpec, inv_inputs: Dataset, idata: InferenceData, output_metadata: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any]=<factory>, basis_functions: FluxWeightedBasis | None = None, model: Model | None = None, inv_out: InversionOutput | None = None, sampler: RhimeSampler = <factory>)#

Bases: object

Modern RHIME run result.

Parameters:

  • run_spec – Top-level run metadata.

  • model_spec – Model specification used to build the PyMC model.

  • output_spec – Output settings used by the run.

  • inv_inputs – Canonical xarray inversion inputs consumed by the model.

  • idata – ArviZ InferenceData returned by sampling.

  • output_metadata – Paths and notes for generated outputs.

  • outputs – In-memory derived outputs keyed by output kind.

  • model – Built PyMC model.

  • inv_out – Modern inversion output object when created.

  • basis_functions – Retained flux basis functions from preparation.

  • sampler – Sampler settings used by the run.

basis_functions: FluxWeightedBasis | None = None#
idata: InferenceData#
inv_inputs: Dataset#
inv_out: InversionOutput | None = None#
model: Model | None = None#
model_spec: RhimeModelSpec#
output_metadata: dict[str, Any]#
output_spec: RhimeOutputSpec#
outputs: dict[str, Any]#
run_spec: RhimeRunSpec#
sampler: RhimeSampler#
class openghg_inversions.rhime.runner.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.runner.RhimeSampler(*, draws: int = 1000, burn: int = 0, tune: int = 1000, chains: int = 4, nuts_sampler: Literal['pymc', 'nutpie', 'numpyro', 'blackjax'] | str = 'pymc', progressbar: bool = False, sample_kwargs: dict[str, Any] | None = None, sample_prior_predictive: bool | int = True, sample_posterior_predictive: bool | Sequence[str] = ('y',), posterior_predictive_kwargs: dict[str, Any] | None = None)#

Bases: object

PyMC sampler configuration and execution for RHIME models.

Parameters:

  • draws – Number of post-tuning draws requested from PyMC.

  • burn – Number of draws to discard from each chain after sampling.

  • tune – Number of PyMC tuning draws.

  • chains – Number of MCMC chains.

  • nuts_sampler – PyMC NUTS backend name.

  • progressbar – Whether PyMC progress output should be shown.

  • sample_kwargs – Extra keyword arguments forwarded to pm.sample.

  • sample_prior_predictive – Whether to append prior predictive draws.

  • sample_posterior_predictive – Whether to append posterior predictive draws, or variable names to sample.

  • posterior_predictive_kwargs – Extra keyword arguments forwarded to pm.sample_posterior_predictive.

burn: int#
chains: int#
draws: int#
nuts_sampler: Literal['pymc', 'nutpie', 'numpyro', 'blackjax']#
posterior_predictive_kwargs: dict[str, Any] | None#
progressbar: bool#
sample(model: Model) → InferenceData#

Sample a built RHIME model and append requested predictive groups.

sample_kwargs: dict[str, Any] | None#
sample_posterior_predictive: bool | tuple[str, ...]#
sample_prior_predictive: bool | int#
tune: int#
class openghg_inversions.rhime.runner.SectorSpec(name: str, flux_source: str, x_prior: dict[str, Any], variable_suffix: str)#

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.

flux_source: str#
name: str#
variable_suffix: str#
x_prior: dict[str, Any]#
openghg_inversions.rhime.runner.params_from_config(config_file: str | Path, *, start_date: str | None = None, end_date: str | None = None, output_path: str | None = None, extra_kwargs: Mapping[str, Any] | None = None) → dict[str, Any]#

Load RHIME run parameters from an INI config file.

Parameters:

  • config_file – Path to an INI configuration file.

  • start_date – Optional command-line start-date override.

  • end_date – Optional command-line end-date override.

  • output_path – Optional command-line output-path override.

  • extra_kwargs – Optional keyword overrides, normally parsed from CLI JSON.

Returns:

Normalized RHIME run parameters using snake-case public names.

Raises:

ValueError – If deprecated unsupported parameters are present or a structured RHIME option has an invalid type.

openghg_inversions.rhime.runner.resolve_flux_sources(*, flux_sources: str | Sequence[str] | None = None, emissions_name: str | Sequence[str] | None = None) → list[str]#

Resolve new flux_sources and legacy emissions_name arguments.

Parameters:

  • flux_sources – Preferred RHIME field containing OpenGHG flux source metadata values.

  • emissions_name – Legacy compatibility spelling accepted only when flux_sources is absent.

Returns:

Resolved flux source names.

Raises:

ValueError – If no usable flux source is supplied.

openghg_inversions.rhime.runner.run_rhime(*, config_file: str | Path | None = None, **kwargs: Any) → RhimeResult#

Run a standard single-sector RHIME inversion.

Parameters:

  • config_file – Optional INI configuration file. Values in kwargs override values read from this file.

  • **kwargs – RHIME run parameters using snake-case names, such as output_path, output_name, flux_sources, and x_prior. species names the primary gas or tracer used for object-store lookup and output naming. flux_sources contains OpenGHG flux source values. Legacy emissions_name is accepted only as a compatibility alias when flux_sources is absent.

Returns:

Modern RHIME result containing canonical inputs, InferenceData, specs, output metadata, and generated outputs.

Raises:

ValueError – If required parameters are missing, unsupported parameters are supplied, or the flux-source count is invalid.

openghg_inversions.rhime.runner.run_rhime_multisector(*, config_file: str | Path | None = None, **kwargs: Any) → RhimeResult#

Run a shared-basis multi-sector RHIME inversion.

Parameters:

  • config_file – Optional INI configuration file. Values in kwargs override values read from this file.

  • **kwargs – RHIME run parameters using snake-case names. Multi-sector runs require at least two flux_sources and may include sector_priors keyed by sector name. When model sector labels differ from OpenGHG source values, pass sector_sources as a mapping from sector name to one value in flux_sources. Legacy emissions_name is accepted only as a compatibility alias when flux_sources is absent.

Returns:

Modern RHIME result containing canonical inputs, InferenceData, specs, output metadata, and sector diagnostics.

Raises:

ValueError – If required parameters are missing, unsupported parameters are supplied, or fewer than two flux sources are provided.

On this page
Show Source