openghg_inversions.rhime.standard#

Readable scientific recipe for a standard single-sector RHIME inversion.

The public recipe deliberately spells out its complete execution order. Small amounts of forwarding shared with the multisector recipe are retained so a scientist can read or copy this module without reconstructing a pipeline.

openghg_inversions.rhime.standard.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.standard.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.standard.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.standard.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.standard.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.