openghg_inversions.rhime.multisector#

Readable scientific recipe for a source-resolved multisector RHIME inversion.

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