openghg_inversions.rhime#

Public RHIME API.

class openghg_inversions.rhime.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.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.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.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.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.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]#

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.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.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.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.