kika.UQ

The UQ package aligns format-neutral sensitivity profiles with covariance data, propagates nuclear-data uncertainty, and calculates the covariance- weighted similarity index \(c_k\).

Alignment is strict by default. Energy units are converted explicitly, but energy grids must coincide after conversion. Missing covariance raises MissingCovarianceError; missing="drop" is an explicit opt-in and the resulting loss is recorded in AlignmentReport. Grid condensation is not performed implicitly.

Exact alignment and sandwich propagation

import kika
from kika.UQ import align_sensitivity_covariance
from kika.UQ.sandwich import sandwich_uncertainty_propagation

profile = kika.read_sdf("application.sdf").to_sensitivity_profile()
aligned = align_sensitivity_covariance([profile], covariance)
result = sandwich_uncertainty_propagation(profile, covariance)

print(result.total_uncertainty)
print(aligned.report)

TSURFER aliases and incomplete coverage

Aliases and exclusions are never automatic. To use the documented TSURFER mapping and continue with the covered covariance subset:

aligned = align_sensitivity_covariance(
    [application, benchmark],
    covariance,
    alias_policy="tsurfer",
    missing="drop",
)

print(aligned.report.aliases)
print(aligned.report.dropped)
print(aligned.report.parameter_coverage)
print(aligned.report.sensitivity_coverage)

Similarity

from kika.UQ import similarity_ck

result = similarity_ck(application, benchmark, covariance)
print(result.value)
print(result.reaction_similarity)  # local, non-additive diagnostics

API

Strict, format-neutral alignment of sensitivities and covariance blocks.

class kika.UQ.alignment.ParameterKey(kind: Literal['xs', 'legendre'], zaid: int, mt: int, order: int | None = None)[source]

Bases: object

A nuclear-data parameter independent of its source file format.

kind: Literal['xs', 'legendre']

zaid: int

mt: int

order: int | None = None

classmethod from_sensitivity(zaid: int, mt: int) → ParameterKey[source]

property label: str

class kika.UQ.alignment.ParameterIndex(key: ParameterKey, group: int, energy_low: float, energy_high: float, energy_unit: str = 'MeV')[source]

Bases: object

Meaning of one element in an aligned flat vector.

key: ParameterKey

group: int

energy_low: float

energy_high: float

energy_unit: str = 'MeV'

class kika.UQ.alignment.AliasMapping(profile: 'int', source: 'ParameterKey', target: 'ParameterKey', reason: 'str')[source]

Bases: object

profile: int

source: ParameterKey

target: ParameterKey

reason: str

class kika.UQ.alignment.AlignmentReport(aliases: ~typing.List[~kika.UQ.alignment.AliasMapping] = <factory>, zeros_inserted: ~typing.Dict[int, ~typing.List[~kika.UQ.alignment.ParameterKey]] = <factory>, zero_covariance_blocks: ~typing.List[~typing.Tuple[~kika.UQ.alignment.ParameterKey, ~kika.UQ.alignment.ParameterKey]] = <factory>, missing_covariance: ~typing.List[~kika.UQ.alignment.ParameterKey] = <factory>, dropped: ~typing.List[~kika.UQ.alignment.ParameterKey] = <factory>, policy_exclusions: ~typing.Dict[int, ~typing.List[~kika.UQ.alignment.ParameterKey]] = <factory>, assumptions: ~typing.List[str] = <factory>, parameter_coverage: ~typing.List[float] = <factory>, sensitivity_coverage: ~typing.List[float] = <factory>)[source]

Bases: object

Complete record of non-exact decisions made while aligning data.

aliases: List[AliasMapping]

zeros_inserted: Dict[int, List[ParameterKey]]

zero_covariance_blocks: List[Tuple[ParameterKey, ParameterKey]]

missing_covariance: List[ParameterKey]

dropped: List[ParameterKey]

policy_exclusions: Dict[int, List[ParameterKey]]

assumptions: List[str]

parameter_coverage: List[float]

sensitivity_coverage: List[float]

exception kika.UQ.alignment.AlignmentError(message: str, report: AlignmentReport | None = None)[source]

Bases: ValueError

Base error for a sensitivity/covariance alignment failure.

exception kika.UQ.alignment.MissingCovarianceError(message: str, report: AlignmentReport | None = None)[source]

Bases: AlignmentError

Raised when sensitivity parameters lack covariance data.

class kika.UQ.alignment.AlignmentResult(sensitivity_vectors: ndarray, sensitivity_uncertainties: ndarray, covariance: ndarray, index: Tuple[ParameterIndex, ...], parameter_keys: Tuple[ParameterKey, ...], reaction_spans: Dict[int, Tuple[int, int]], profiles: Tuple[SensitivityProfile, ...], report: AlignmentReport)[source]

Bases: object

Aligned sensitivity vectors, absolute sigmas, relative covariance and index.

sensitivity_vectors: ndarray

sensitivity_uncertainties: ndarray

covariance: ndarray

index: Tuple[ParameterIndex, ...]

parameter_keys: Tuple[ParameterKey, ...]

reaction_spans: Dict[int, Tuple[int, int]]

profiles: Tuple[SensitivityProfile, ...]

report: AlignmentReport

class kika.UQ.alignment.PreparedCovariance(energy_grid_mev: ndarray, blocks: Dict[Tuple[ParameterKey, ParameterKey], ndarray], assumptions: Tuple[str, ...] = ())[source]

Bases: object

Normalized covariance blocks reusable for profiles on one exact grid.

energy_grid_mev: ndarray

blocks: Dict[Tuple[ParameterKey, ParameterKey], ndarray]

assumptions: Tuple[str, ...] = ()

kika.UQ.alignment.prepare_covariance(profile: SensitivityProfile | SDFData, covariance: CrossSectionCovariance | Sequence[CrossSectionCovariance] | None = None, legendre_covariance: MultigroupLegendreCovariance | Sequence[MultigroupLegendreCovariance] | None = None, *, energy_rtol: float = 1e-08) → PreparedCovariance[source]: Normalize covariance blocks once for repeated calculations on one grid.

kika.UQ.alignment.align_sensitivity_covariance(profiles: Sequence[SensitivityProfile | SDFData], covariance: CrossSectionCovariance | Sequence[CrossSectionCovariance] | None = None, legendre_covariance: MultigroupLegendreCovariance | Sequence[MultigroupLegendreCovariance] | None = None, *, alias_policy: Literal['exact', 'tsurfer'] = 'exact', missing: Literal['error', 'drop'] = 'error', energy_rtol: float = 1e-08, prepared_covariance: PreparedCovariance | None = None) → AlignmentResult[source]

Align one or more sensitivity profiles with relative covariance blocks.

Profile keys are combined by union. A missing key in one profile is an explicit zero sensitivity; a key missing from covariance is an error unless missing="drop" is requested.

Sandwich formula for uncertainty propagation in nuclear data.

This module implements the sandwich formula σ²_R = S^T Σ S for propagating nuclear data uncertainties from sensitivity coefficients and covariance matrices.

The sandwich formula allows propagation of uncertainties from nuclear cross-section covariances to integral responses through sensitivity coefficients.

class kika.UQ.sandwich.UncertaintyContribution(zaid: int, mt: int, variance_contribution: float)[source]

Bases: object

Container for individual uncertainty contributions from specific reactions.

zaid

ZAID of the nuclide

Type:: int

mt

MT reaction number

Type:: int

variance_contribution

Contribution to total variance from this reaction

Type:: float

uncertainty_contribution

Square root of variance contribution (1-sigma)

Type:: float

relative_contribution

Relative contribution to total variance (fraction)

Type:: float

nuclide

Nuclide symbol (e.g., ‘Fe-56’)

Type:: str

reaction_name

Reaction name (e.g., ‘elastic’)

Type:: str

zaid: int

mt: int

variance_contribution: float

uncertainty_contribution: float

relative_contribution: float

nuclide: str

reaction_name: str

class kika.UQ.sandwich.UncertaintyResult(total_variance: float, total_uncertainty: float, relative_uncertainty: float, response_value: float, response_error: float, contributions: List[UncertaintyContribution], n_reactions: int, n_energy_groups: int, correlation_effects: float = 0.0, bootstrap_ci_low: float | None = None, bootstrap_ci_high: float | None = None, bootstrap_mean: float | None = None, bootstrap_std: float | None = None, bootstrap_n_samples: int | None = None, ci_level: float = 0.95, alignment_report: AlignmentReport | None = None)[source]

Bases: object

Container for uncertainty propagation results.

total_variance

Total propagated variance

Type:: float

total_uncertainty

Total uncertainty (1-sigma, square root of variance)

Type:: float

relative_uncertainty

Relative uncertainty (σ/μ)

Type:: float

response_value

Reference response value used for relative uncertainty

Type:: float

response_error

Absolute one-sigma uncertainty on the unperturbed response. Reported as a diagnostic only — it is not combined with sigma_ND in this function.

Type:: float

contributions

Individual reaction contributions sorted by magnitude

Type:: List[UncertaintyContribution]

n_reactions

Number of reactions included in propagation

Type:: int

n_energy_groups

Number of energy groups used

Type:: int

correlation_effects

Contribution from cross-correlations between reactions

Type:: float

bootstrap_ci_low, bootstrap_ci_high

Lower / upper bound of the bootstrap CI on sigma_ND (relative). Both None when bootstrap was disabled.

Type:: float, optional

bootstrap_mean, bootstrap_std

Mean and std of the bootstrap distribution of sigma_ND (relative).

Type:: float, optional

bootstrap_n_samples

Number of bootstrap samples drawn. None when bootstrap was disabled.

Type:: int, optional

ci_level

Confidence level used for the bootstrap CI (default 0.95).

Type:: float

total_variance: float

total_uncertainty: float

relative_uncertainty: float

response_value: float

response_error: float

contributions: List[UncertaintyContribution]

n_reactions: int

n_energy_groups: int

correlation_effects: float = 0.0

bootstrap_ci_low: float | None = None

bootstrap_ci_high: float | None = None

bootstrap_mean: float | None = None

bootstrap_std: float | None = None

bootstrap_n_samples: int | None = None

ci_level: float = 0.95

alignment_report: AlignmentReport | None = None

property response_relative_error: float

kika.UQ.sandwich.sandwich_uncertainty_propagation(sdf_data: SDFData | SensitivityProfile, cov_mat: CrossSectionCovariance | List[CrossSectionCovariance] | None = None, legendre_cov_mat: MultigroupLegendreCovariance | List[MultigroupLegendreCovariance] | None = None, reaction_filter: Dict[int, List[int]] | None = None, nubar_mode: str | Dict[int, str] = 'total', energy_tolerance: float = 1e-06, verbose: bool = False, bootstrap: bool = True, n_bootstrap: int = 1000, ci_level: float = 0.95, bootstrap_seed: int | None = None, alias_policy: str = 'exact', missing: str = 'error') → UncertaintyResult[source]

Propagate nuclear-data uncertainty with S.T @ C @ S.

sdf_data may be an SDFData or a format-neutral SensitivityProfile. Alignment is strict by default. Use missing="drop" only when excluding uncovered parameters is intended; the returned alignment_report records every exclusion and alias.

kika.UQ.sandwich.filter_reactions_by_nuclide(zaid: int, mt_list: List[int] | None = None) → Dict[int, List[int]][source]

Convenience function to create reaction filter for a single nuclide.

Parameters:

zaid (int) – ZAID of the nuclide
mt_list (List[int], optional) – List of MT numbers to include. If None, includes all reactions for this nuclide.

Returns:

Reaction filter dictionary suitable for sandwich_uncertainty_propagation

Return type:

Dict[int, List[int]]

Examples

>>> # Include all reactions for Fe-56
>>> filter_dict = filter_reactions_by_nuclide(26056)
>>>
>>> # Include only elastic and inelastic for Fe-56
>>> filter_dict = filter_reactions_by_nuclide(26056, [2, 4])

kika.UQ.sandwich.filter_reactions_by_type(mt_numbers: List[int]) → Dict[int, List[int]][source]

Convenience function to create reaction filter by reaction type across all nuclides.

Parameters:: mt_numbers (List[int]) – List of MT numbers to include
Returns:: Reaction filter dictionary (note: this returns a special marker that the main function should interpret as “these MTs for all nuclides”)
Return type:: Dict[int, List[int]]

Examples

>>> # Include only elastic scattering for all nuclides
>>> filter_dict = filter_reactions_by_type([2])
>>>
>>> # Include elastic and (n,γ) for all nuclides
>>> filter_dict = filter_reactions_by_type([2, 102])

Covariance-weighted similarity of integral-response sensitivity profiles.

exception kika.UQ.similarity.ZeroSimilarityVarianceError[source]

Bases: ValueError

Raised when c-k is undefined because either covariance norm is non-positive.

class kika.UQ.similarity.ReactionSimilarity(key: ParameterKey, value: float | None, variance_a: float, variance_b: float, cross_covariance: float)[source]

Bases: object

Non-additive c-k diagnostic from one diagonal reaction block.

key: ParameterKey

value: float | None

variance_a: float

variance_b: float

cross_covariance: float

class kika.UQ.similarity.SimilarityResult(value: float, variance_a: float, variance_b: float, cross_covariance: float, reaction_similarity: Tuple[ReactionSimilarity, ...], index: Tuple[ParameterIndex, ...], parameter_keys: Tuple[ParameterKey, ...], alignment_report: AlignmentReport)[source]

Bases: object

Covariance-weighted similarity result and alignment provenance.

value: float

variance_a: float

variance_b: float

cross_covariance: float

reaction_similarity: Tuple[ReactionSimilarity, ...]

index: Tuple[ParameterIndex, ...]

parameter_keys: Tuple[ParameterKey, ...]

alignment_report: AlignmentReport

property ck: float: Covariance-weighted similarity coefficient.

kika.UQ.similarity.similarity_ck(profile_a: SensitivityProfile | SDFData, profile_b: SensitivityProfile | SDFData, covariance: CrossSectionCovariance | Sequence[CrossSectionCovariance] | None = None, legendre_covariance: MultigroupLegendreCovariance | Sequence[MultigroupLegendreCovariance] | None = None, *, alias_policy: str = 'exact', missing: str = 'error', include: Sequence[Tuple[int, int]] | None = None, exclude: Sequence[Tuple[int, int]] | None = None, include_mt1: bool = False, nubar_mode: str | dict = 'total', energy_tolerance: float = 1e-06, prepared_covariance: PreparedCovariance | None = None) → SimilarityResult[source]: Calculate covariance-weighted c-k between two sensitivity profiles.