openghg_inversions.rhime#

Public RHIME runners, specifications, builders, and orchestration stages.

Use run_rhime, run_rhime_multisector, or run_rhime_from_prepared_inputs for complete runs. Copied runners may use the supported resolve, retrieve/reload, filter, basis, sensitivity, assembly, alignment, materialization, build, sample, result, and output stages directly. Alignment is pure; acquisition may access data, model materialization crosses the eager backend boundary, sampling executes PyMC, and output stages may write requested products.

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

Bases: object

Serializable selection of reported observation error only.

property required_prepared_inputs: tuple[str, ...]#: Return prepared arrays owned by this likelihood.

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.RhimeModelBuildResult(model: ~pymc.model.core.Model, variable_roles: ~collections.abc.Mapping[str, str], supported_output_formats: tuple[~typing.Literal['none', 'inv_out', 'basic', 'paris', 'legacy'], ...] = ('none',), metadata: ~collections.abc.Mapping[str, ~typing.Any] = <factory>)#

Bases: object

Concrete model and serializable metadata returned by a model builder.

Custom builders default to supporting sampling-only runs (output_format="none"). A builder must explicitly declare additional formats after ensuring that its role manifest and trace satisfy those postprocessing contracts.

Parameters:

model – Concrete PyMC model for RhimeSampler.
variable_roles – Semantic role to concrete input/model variable name. Roles such as concentration, model_error, flux_scale, and baseline let sampling and outputs avoid name inference. Components that do not exist, such as model error in a fixed-error model, should be omitted.
supported_output_formats – Output formats the builder declares safe. "none" always means sampling without RHIME postprocessing.
metadata – Additional JSON-serializable builder/provenance metadata.

metadata: Mapping[str, Any]#

model: Model#

supported_output_formats: tuple[Literal['none', 'inv_out', 'basic', 'paris', 'legacy'], ...] = ('none',)#

validate_requested_output(output_format: str) → None#: Reject an output this model contract does not support.

variable_roles: Mapping[str, str]#

class openghg_inversions.rhime.RhimeModelBuilder(*args, **kwargs)#

Bases: Protocol

Advanced callable contract for a complete user-owned model factory.

class openghg_inversions.rhime.RhimeModelBuilderContext(prepared_inputs: RhimePreparedInputs, run_spec: RhimeRunSpec, multisector: bool)#

Bases: object

Advanced compatibility input supplied only to a complete model builder.

Ordinary in-tree recipes and components use explicit named scientific inputs. This context remains solely for user-owned complete models invoked through run_rhime_from_prepared_inputs; those builders own validation and materialization of any lazy arrays they consume.

Parameters:

prepared_inputs – Validated canonical inputs, retained basis functions, and preparation metadata.
run_spec – Model, output, and run settings for this execution. The callable is deliberately kept outside this serializable spec.
multisector – Whether the validated prepared layout and model spec are sector resolved.

multisector: bool#

prepared_inputs: RhimePreparedInputs#

run_spec: RhimeRunSpec#

class openghg_inversions.rhime.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.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>, model_build_result: RhimeModelBuildResult | None = None)#

Bases: object

Complete result of a standard or multisector RHIME recipe.

basis_functions: FluxWeightedBasis | None = None#

idata: InferenceData#

inv_inputs: Dataset#

inv_out: InversionOutput | None = None#

model: Model | None = None#

model_build_result: RhimeModelBuildResult | 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, *, variable_roles: Mapping[str, str] | None = None) → InferenceData#

Sample a built RHIME model and append requested predictive groups.

Parameters:

model – Concrete PyMC model to sample.
variable_roles – Optional semantic-role manifest from a RhimeModelBuildResult. Posterior-predictive entries may be role names. The historical default "y" resolves to the explicit concentration role when a custom model has no variable named y.

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, *, 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.assemble_rhime_inputs(merged: RhimeMergedData, basis_functions: FluxWeightedBasis, site_data: Mapping[str, Dataset], data_args: Mapping[str, Any]) → RhimePreparedInputs#

Construct and validate durable, backend-neutral RHIME model inputs.

The stage attaches domain metadata to shallow per-site copies, assembles observation-aligned arrays, applies the satellite boundary-condition scaling, and retains basis and site metadata. It also preserves the legacy construction of the minimum-error floor and boundary-condition temporal parameterization. Those are inverse-model settings, not properties of the acquired data; moving them to their model components is a later semantic change. This stage does not cross the PyMC materialization boundary.

openghg_inversions.rhime.build_co2_model(flux_sensitivity: DataArray, *, retained_prior: CorrelatedLognormalPrior, fixed_prior_contribution: DataArray, observations: DataArray, observation_error: DataArray, minimum_error: DataArray, aggregation_error: AggregationError, sigma_alignment: SigmaAlignment | None = None, sigma_prior: dict[str, Any] | None = None, fixed_model_mismatch: float | DataArray | None = None, state_activity: StateActivity | None = None, boundary_sensitivity: DataArray | None = None, bc_prior: dict[str, Any] | None = None, bc_state_activity: StateActivity | None = None, offset_prior: dict[str, Any] | None = None, offset_args: dict | None = None) → Model#

Build the CO2 coherent-reduction model from explicit scientific arrays.

flux_sensitivity is prepared once as the reduced operator H_alpha: exact-zero columns are omitted from the backend co2_sensitivity while flux_scaling retains the complete labelled scientific state. fixed_prior_contribution is then added with the shared coherent-affine component to produce modelled_concentration.

fixed_prior_contribution is the affine term H m - H_alpha (Pi m). The latter is a fixed prior contribution, not an atmospheric boundary condition. retained_prior contains the complete labelled arithmetic moments for the positive flux state.

Known fixed states remain in the public state and forward calculation but are omitted from the sampled correlated state. fixed_model_mismatch is an optional known concentration standard deviation. openghg_inversions leaves this policy unset by default; the Verification Games fixed likelihood passes 1 ppm explicitly. Inner and outer same-grid states remain in this one flux state and are distinguished by basis_group metadata retained for output-side selection. The model builds only their complete shared flux contribution. Optional boundary and offset terms remain scientifically distinct components named mu_bc and offset.

Direct custom callers are responsible for supplying scientifically coherent arrays from one preparation and for their positional semantics when labels are absent.

Parameters:

flux_sensitivity – Reduced CO2 sensitivity with observation dimension nmeasure and one labelled retained-state dimension.
retained_prior – Complete labelled arithmetic-moment prior for the retained positive state.
fixed_prior_contribution – Fixed coherent-reduction affine intercept named fixed_prior_contribution on nmeasure.
observations – Observed CO2 concentrations on nmeasure.
observation_error – Reported observation standard deviation.
minimum_error – Minimum independent model-data mismatch standard deviation.
aggregation_error – Prepared fixed aggregation-error representation.
sigma_alignment – Optional grouping policy for inferred additive model error.
sigma_prior – Optional prior arguments for inferred additive model error.
fixed_model_mismatch – Optional known scalar or labelled concentration standard deviation.
state_activity – Optional labelled activity policy for retained flux states.
boundary_sensitivity – Optional atmospheric boundary-condition sensitivity already resolved for the model, for example data.
bc_prior – Optional prior arguments for boundary-condition scaling.
bc_state_activity – Optional labelled activity policy for boundary states.
offset_prior – Optional prior for an offset component. When omitted, no offset is added. Site codes are derived from the site coordinate on observations.
offset_args – Extra keyword arguments for the offset component.

Returns:

A registered PyMC model containing the complete affine concentration and Gaussian likelihood.

Raises:

ValueError – If shared preparation, prior construction, or registered coordinate alignment fails, or if sigma_prior is supplied without sigma_alignment.

openghg_inversions.rhime.build_multisector_rhime_model(flux_sensitivity: DataArray, *, observations: DataArray, observation_error: DataArray, aggregation_error: AggregationError, minimum_error: DataArray | None = None, likelihood_settings: PollutionEventSettings | AdditiveSigmaSettings | FixedErrorSettings | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, sectors: Sequence[SectorSpec], boundary_sensitivity: DataArray | None = None, bc_prior: dict[str, Any] | None = None, offset_prior: dict[str, Any] | None = None, add_offset: bool = False, use_bc: bool = True, offset_args: dict | None = None, state_activity: StateActivity | None = None, bc_state_activity: StateActivity | None = None, sigma_alignment: SigmaAlignment | None = None) → Model#

Build the concrete shared-basis multi-sector RHIME model.

Each sector receives its own state vector x_<sector> and forward-model contribution mu_<sector>. The recipe visibly sums those contributions, adds the baseline and optional offset, then passes the completed mean to the likelihood.

Parameters:

flux_sensitivity – Labelled source-resolved flux sensitivity, either shared-basis or gathered source-specific state layout.
observations – Observed mole fractions.
observation_error – Reported observation-error standard deviations.
aggregation_error – Validated fixed aggregation-error representation.
minimum_error – Optional prepared minimum total-error floor.
likelihood_settings – Resolved built-in likelihood settings.
likelihood_builder – Optional Python-only custom likelihood.
likelihood_kwargs – Options for the custom likelihood.
sectors – Ordered sector specifications containing each scientific name, OpenGHG source, PyMC suffix, prior, and optional activity override.
boundary_sensitivity – Optional labelled boundary sensitivity matrix.
bc_prior – Prior for boundary-condition scaling factors.
offset_prior – Prior for optional offsets.
add_offset – Whether to include an offset term.
use_bc – Whether to include boundary-condition terms.
offset_args – Extra keyword arguments for the offset component.
state_activity – State policy shared by sectors without an override.
bc_state_activity – Optional active/fixed boundary-state policy.
sigma_alignment – Optional precomputed mismatch alignment. Ordinary runners derive it from observations.

Returns:

Built PyMC model.

Raises:

KeyError – If required sensitivity inputs are absent.
ValueError – If sector labels, sources, suffixes, state policies, or canonical likelihood variables are invalid.
TypeError – If the likelihood returns the wrong result type.

openghg_inversions.rhime.build_multisector_rhime_model_result(*, prepared: RhimePreparedInputs, model_inputs: Dataset, run_spec: RhimeRunSpec, model_builder: RhimeModelBuilder | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None) → RhimeModelBuildResult#

Validate source-specific bases and build the multisector graph result.

Parameters:

prepared – Retained source-specific prepared-input artifact.
model_inputs – Eager canonical arrays for the built-in PyMC graph.
run_spec – Resolved model, sampling, and output specification.
model_builder – Optional complete-model builder for advanced prepared- input workflows.
likelihood_builder – Optional observation-error and distribution builder used with the built-in graph.
likelihood_kwargs – Options expanded only into the custom likelihood.

Returns:

Model plus variable roles, supported outputs, and build metadata.

Raises:

ValueError – If the basis layout is incompatible, both extension points are supplied, or the result conflicts with the run specification.

openghg_inversions.rhime.build_rhime_basis(merged: RhimeMergedData, data_args: Mapping[str, Any]) → FluxWeightedBasis#

Load or fit the retained RHIME basis for filtered observations.

This stage may read or write basis artifacts and may execute the selected basis algorithm. It treats merged as borrowed and does not build sensitivities.

openghg_inversions.rhime.build_rhime_sensitivities(merged: RhimeMergedData, basis_functions: FluxWeightedBasis, data_args: Mapping[str, Any], *, multisector: bool) → dict[str, Dataset]#

Construct labelled flux and optional boundary-condition sensitivities.

The stage creates per-site dataset copies, computes the basis projection, and may load boundary-condition basis data. merged and basis_functions remain borrowed.

openghg_inversions.rhime.build_standard_rhime_model(flux_sensitivity: DataArray, *, observations: DataArray, observation_error: DataArray, aggregation_error: AggregationError, minimum_error: DataArray | None = None, likelihood_settings: PollutionEventSettings | AdditiveSigmaSettings | FixedErrorSettings | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, boundary_sensitivity: DataArray | None = None, x_prior: dict[str, Any] | None = None, bc_prior: dict[str, Any] | None = None, offset_prior: dict[str, Any] | None = None, add_offset: bool = False, use_bc: bool = True, offset_args: dict | None = None, state_activity: StateActivity | None = None, bc_state_activity: StateActivity | None = None, preserve_legacy_likelihood: bool = False, sigma_alignment: SigmaAlignment | None = None, legacy_unused_sigma_settings: PollutionEventSettings | None = None, legacy_minimum_error_floor: bool = False) → Model#

Build the concrete standard single-sector RHIME model.

Parameters:

flux_sensitivity – Labelled flux sensitivity matrix.
observations – Observed mole fractions.
observation_error – Reported observation-error standard deviations.
aggregation_error – Validated fixed aggregation-error representation.
minimum_error – Optional prepared minimum total-error floor.
likelihood_settings – Resolved built-in likelihood settings.
likelihood_builder – Optional Python-only custom likelihood.
likelihood_kwargs – Options for the custom likelihood.
boundary_sensitivity – Optional labelled boundary sensitivity matrix.
x_prior – Prior specification for flux scaling factors.
bc_prior – Prior specification for boundary-condition scaling factors.
offset_prior – Prior specification for optional offsets.
add_offset – Whether to include an offset term.
use_bc – Whether to include boundary-condition terms.
offset_args – Extra keyword arguments for the offset component.
state_activity – Optional active/fixed flux-state policy.
bc_state_activity – Optional active/fixed boundary-state policy.
preserve_legacy_likelihood – Whether to preserve run_hbmcmc’s boundary-only pollution event and unused sigma variable.
sigma_alignment – Optional precomputed mismatch alignment. Ordinary runners derive it from observations.
legacy_unused_sigma_settings – Private run_hbmcmc settings for its historical disconnected sigma variable.
legacy_minimum_error_floor – Preserve the historical additive callback’s minimum-error floor when inferred model error was disabled.

Returns:

Built PyMC model.

Raises:

KeyError – If required sensitivity inputs are absent.
ValueError – If labels, state policies, priors, or canonical likelihood variables are invalid.
TypeError – If the likelihood returns the wrong result type.

openghg_inversions.rhime.build_standard_rhime_model_result(*, prepared: RhimePreparedInputs, model_inputs: Dataset, run_spec: RhimeRunSpec, model_builder: RhimeModelBuilder | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, preserve_legacy_likelihood: bool = False, legacy_unused_sigma_settings: PollutionEventSettings | None = None, legacy_minimum_error_floor: bool = False) → RhimeModelBuildResult#

Build the standard graph and describe its output roles.

Parameters:

prepared – Retained prepared-input artifact used by custom builders.
model_inputs – Eager canonical arrays for the built-in PyMC graph.
run_spec – Resolved model, sampling, and output specification.
model_builder – Optional complete-model builder for advanced prepared- input workflows.
likelihood_builder – Optional observation-error and distribution builder used with the built-in graph.
likelihood_kwargs – Options expanded only into the custom likelihood.
preserve_legacy_likelihood – Whether to preserve the historical run_hbmcmc likelihood graph and pollution-event definition.
legacy_unused_sigma_settings – Private compatibility settings for a disconnected historical sigma variable.
legacy_minimum_error_floor – Preserve the historical additive callback’s minimum-error floor when inferred model error was disabled.

Returns:

Model plus variable roles, supported outputs, and build metadata.

Raises:

ValueError – If both builder extension points are supplied or the built result is inconsistent with the run specification.

openghg_inversions.rhime.co2_model_input_names(prepared_inputs: RhimePreparedInputs, *, aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'], preserve_prepared_fixed_mismatch: bool) → tuple[str, ...]#

Declare prepared arrays consumed by the selected CO2 components.

Parameters:

prepared_inputs – Prepared RHIME artifact containing the candidate inversion inputs.
aggregation_error_mode – Aggregation-error representation selected for the likelihood.
preserve_prepared_fixed_mismatch – Include a prepared fixed mismatch field when present.

Returns:

Names of the arrays to materialize for model construction.

Raises:

ValueError – If a required prepared input is absent.

openghg_inversions.rhime.filter_rhime_observations(merged: RhimeMergedData, data_args: Mapping[str, Any]) → RhimeMergedData#

Filter borrowed observations and remove empty sites with aligned metadata.

The stage may compute site data if a filter cannot operate lazily. It returns a new merged-data handoff when filtering changes data and never constructs basis functions or model inputs.

openghg_inversions.rhime.make_multisector_rhime_outputs(*, result: RhimeResult, prepared: RhimePreparedInputs) → None#

Create and attach the requested multisector RHIME outputs.

Parameters:

result – Sampled multisector result receiving requested products.
prepared – Retained source-resolved inputs and basis functions.

openghg_inversions.rhime.make_multisector_rhime_result(*, prepared: RhimePreparedInputs, run_spec: RhimeRunSpec, sampler: RhimeSampler, model_build_result: RhimeModelBuildResult, idata: InferenceData, build_and_sample_seconds: float, model_builder: RhimeModelBuilder | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None) → RhimeResult#

Construct a sampled multisector result before output side effects.

Parameters:

prepared – Retained source-resolved inputs and basis functions.
run_spec – Resolved model, output, and run settings.
sampler – Sampler configuration used for the trace.
model_build_result – Concrete graph and semantic variable roles.
idata – Sampled posterior and predictive groups.
build_and_sample_seconds – Combined graph-build and sampling duration.
model_builder – Optional complete-model callable used for provenance.
likelihood_builder – Optional likelihood callable used for provenance.
likelihood_kwargs – Serializable options owned by the likelihood.

Returns:

Multisector result ready for requested output construction.

openghg_inversions.rhime.make_standard_rhime_outputs(*, result: RhimeResult, prepared: RhimePreparedInputs) → None#

Create and attach the requested standard RHIME outputs.

Parameters:

result – Sampled standard result receiving requested products.
prepared – Retained canonical inputs and basis functions.

openghg_inversions.rhime.make_standard_rhime_result(*, prepared: RhimePreparedInputs, run_spec: RhimeRunSpec, sampler: RhimeSampler, model_build_result: RhimeModelBuildResult, idata: InferenceData, build_and_sample_seconds: float, model_builder: RhimeModelBuilder | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, _compatibility_likelihood_provenance: Mapping[str, Any] | None = None) → RhimeResult#

Construct a sampled standard result before output side effects.

Parameters:

prepared – Retained canonical inputs and basis functions.
run_spec – Resolved model, output, and run settings.
sampler – Sampler configuration used for the trace.
model_build_result – Concrete graph and semantic variable roles.
idata – Sampled posterior and predictive groups.
build_and_sample_seconds – Combined graph-build and sampling duration.
model_builder – Optional complete-model callable used for provenance.
likelihood_builder – Optional likelihood callable used for provenance.
likelihood_kwargs – Serializable options owned by the likelihood.
_compatibility_likelihood_provenance – Pre-resolved private compatibility provenance.

Returns:

Standard-run result ready for requested output construction.

openghg_inversions.rhime.materialize_pymc_inputs(prepared: RhimePreparedInputs, *, variable_names: Collection[str]) → Dataset#

Materialize related PyMC arrays together without mutating preparation.

variable_names comes from the concrete recipe and its selected components. Sparse chunk payloads are converted with to_dense(); those arrays and their lazy auxiliary coordinates are computed in one shared Dask operation and installed in a shallow dataset copy. Unselected prepared products and the canonical prepared artifact remain unchanged.

Parameters:

prepared – Borrowed backend-neutral prepared inputs.
variable_names – Names selected by the concrete recipe and its active components.

Returns:

A shallow dataset copy in which selected arrays and their lazy coordinates have been materialized together.

Raises:

ValueError – If a selected variable is absent from the prepared data.

openghg_inversions.rhime.multisector_model_input_names(prepared: RhimePreparedInputs, model_spec: RhimeModelSpec) → tuple[str, ...]#

Declare arrays required by selected multisector-model components.

Parameters:

prepared – Backend-neutral prepared inputs.
model_spec – Resolved multisector component options.

Returns:

Prepared variable names selected for coordinated materialization.

Raises:

ValueError – If a selected component’s required input is absent or its aggregation-error representation is ambiguous.

openghg_inversions.rhime.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, normalise: bool = True) → 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.
normalise – Whether to normalize and validate the merged parameters. Complete runners defer this to their public resolution stage.

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.resolve_rhime_options(*, params: Mapping[str, Any], multisector: bool) → RhimeRunnerSetup#: Normalize raw options into preparation, model, sampling, and output settings.

openghg_inversions.rhime.retrieve_or_reload_rhime_data(data_args: Mapping[str, Any], *, multisector: bool, merged_data: RhimeMergedData | None = None) → RhimeMergedData#

Retrieve, reload, or accept externally supplied merged RHIME data.

Passing merged_data is the explicit no-I/O path. The object remains borrowed and is returned unchanged after a sector-layout compatibility check. Otherwise this stage may read OpenGHG stores or a local merged artifact, optionally write merged data, sanitize flux arrays, print progress, and emit warnings. data_args is never mutated.

openghg_inversions.rhime.run_rhime(*, config_file: str | Path | None = None, merged_data: RhimeMergedData | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, preserve_legacy_likelihood: bool = False, _compatibility_likelihood_provenance: Mapping[str, Any] | None = None, _compatibility_unused_sigma_settings: PollutionEventSettings | None = None, _compatibility_minimum_error_floor: bool = False, **kwargs: Any) → RhimeResult#

Run a standard single-sector RHIME inversion.

The visible process is resolve → retrieve/reload → filter → basis → sensitivities → assemble → materialize → build → sample → result → requested outputs.

Parameters:

config_file – Optional INI configuration file. Values in kwargs override values read from this file.
merged_data – Optional externally supplied merged scientific data. Passing this borrowed handoff bypasses OpenGHG acquisition and merged-cache I/O, then resumes at the visible filtering stage. The retrieval stage checks its sector layout without mutating it.
likelihood_builder – Optional Python-only callable invoked with a completed forward-model mean and explicit error-model inputs in the active PyMC model. It must return the canonical observed variable y and create the canonical error scale epsilon. The callable is never read from configuration or stored in run/model specifications.
likelihood_kwargs – Options specific to the custom likelihood. Common scientific arrays are passed explicitly by the recipe.
preserve_legacy_likelihood – Private run_hbmcmc compatibility switch. Ordinary RHIME callers should leave it false.
_compatibility_likelihood_provenance – Private run_hbmcmc record of the historical additive callback spelling and options.
_compatibility_unused_sigma_settings – Private run_hbmcmc settings for its historical disconnected sigma variable.
_compatibility_minimum_error_floor – Private run_hbmcmc switch for the historical additive callback’s minimum-error floor.
**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:

TypeError – If a likelihood builder is not callable or returns the wrong result type.
ValueError – If required parameters are missing, unsupported parameters are supplied, the flux-source count is invalid, or likelihood variables or requested-output compatibility are invalid.

openghg_inversions.rhime.run_rhime_co2(*, prepared_inputs: RhimePreparedInputs, sigma_alignment: SigmaAlignment | None = None, sigma_prior: dict[str, Any] | None = None, fixed_model_mismatch: float | DataArray | None = None, sampler: RhimeSampler | None = None, aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'] = 'dense', no_model_error: bool = False) → InferenceData#

Materialize, build, and sample the CO2 coherent-reduction model.

This callable is the public production replay seam for an already validated RhimePreparedInputs artifact. It alone unpacks the prepared dataset and constructs the complete retained prior; the model builder receives named scientific values.

fixed_model_mismatch=None preserves a prepared fixed-mismatch field if present, otherwise omits the term. An explicit scalar or labelled vector overrides prepared data. By default, inferred model error varies by site over one shared time period. An explicit sigma_alignment overrides that alignment; no_model_error=True disables inferred model error. The Verification Games fixed-likelihood harness passes 1 ppm and disables inferred model error.

Parameters:

prepared_inputs – Validated coherent-reduction inputs for the CO2 recipe.
sigma_alignment – Optional grouping policy for inferred additive model error. The default is derived from the prepared site indicator.
sigma_prior – Optional prior arguments for inferred additive model error.
fixed_model_mismatch – Optional known scalar or labelled mismatch standard deviation. When omitted, a prepared value is preserved.
sampler – Optional RHIME sampler configuration.
aggregation_error_mode – Prepared aggregation-error representation to use in the likelihood.
no_model_error – If true, omit inferred additive model error.

Returns:

Sampled inference data annotated with the CO2 variable-role and model manifests.

Raises:

ValueError – If model-error options contradict no_model_error, or prepared inputs are missing, inconsistent, or fail model construction.

openghg_inversions.rhime.run_rhime_from_prepared_inputs(*, prepared_inputs: RhimePreparedInputs, run_spec: RhimeRunSpec, sampler: RhimeSampler | None = None, model_builder: RhimeModelBuilder | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None) → RhimeResult#

Build, sample, construct a result, and output a prepared RHIME run.

This advanced route intentionally starts after retrieval, filtering, basis construction, sensitivity construction, and labelled-input assembly. It validates the retained scientific layout before crossing the PyMC materialization boundary.

Parameters:

prepared_inputs – Validated canonical inversion inputs and retained basis functions.
run_spec – Resolved model, output, and run settings.
sampler – Optional sampler configuration; defaults to RhimeSampler.
model_builder – Optional complete-model callable for advanced graphs.
likelihood_builder – Optional ordinary likelihood callable used with the built-in graph.
likelihood_kwargs – Options specific to the custom likelihood.

Returns:

Sampled result with any requested output products attached.

Raises:

ValueError – If layouts, extension points, aggregation error, or output settings are inconsistent.
TypeError – If an extension point has an invalid callable contract.

openghg_inversions.rhime.run_rhime_multisector(*, config_file: str | Path | None = None, merged_data: RhimeMergedData | None = None, likelihood_builder: Callable[[...], TensorVariable] | None = None, likelihood_kwargs: Mapping[str, Any] | None = None, **kwargs: Any) → RhimeResult#

Run a shared-basis multi-sector RHIME inversion.

The visible process is resolve → retrieve/reload → filter → basis → sensitivities → assemble → materialize → build → sample → result → requested outputs. This module keeps source layout validation and sector-aware outputs beside that process instead of hiding them behind standard/multisector branching.

Parameters:

config_file – Optional INI configuration file. Values in kwargs override values read from this file.
merged_data – Optional externally supplied source-resolved merged scientific data. Passing it bypasses OpenGHG acquisition and merged-cache I/O, then resumes at filtering after validation.
likelihood_builder – Optional Python-only callable invoked with a completed forward-model mean and explicit error-model inputs in the active PyMC model. It must return the canonical observed variable y and create the canonical error scale epsilon. The callable is never read from configuration or stored in run/model specifications.
likelihood_kwargs – Options specific to the custom likelihood. Common scientific arrays are passed explicitly by the recipe.
**kwargs – RHIME run parameters using snake-case names. Multi-sector runs require at least two flux_sources and may include a complete sector_priors mapping keyed by sector name. When model sector labels differ from OpenGHG source values, pass sector_sources as a one-to-one mapping from sector name to one unique 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:

TypeError – If a likelihood builder is not callable or returns the wrong result type.
ValueError – If required parameters are missing, unsupported parameters are supplied, fewer than two flux sources are provided, or likelihood variables or requested-output compatibility are invalid.

openghg_inversions.rhime.sample_rhime_model(model_build_result: RhimeModelBuildResult, sampler: RhimeSampler) → InferenceData#

Sample a built RHIME graph at the named sampler boundary.

Parameters:

model_build_result – Concrete graph and semantic variable roles.
sampler – Configured sampler used for posterior and predictive draws.

Returns:

Sampled posterior and predictive groups.

openghg_inversions.rhime.standard_model_input_names(prepared: RhimePreparedInputs, model_spec: RhimeModelSpec) → tuple[str, ...]#

Declare arrays required by selected standard-model components.

Parameters:

prepared – Backend-neutral prepared inputs.
model_spec – Resolved standard-model component options.

Returns:

Prepared variable names selected for coordinated materialization.

Raises:

ValueError – If a selected component’s required input is absent or its aggregation-error representation is ambiguous.

openghg_inversions.rhime.with_prepared_rhime_sites(run_spec: RhimeRunSpec, prepared: RhimePreparedInputs) → RhimeRunSpec#: Align run provenance to the observations retained by preparation.

openghg_inversions.rhime.co2