kika.benchmarks

Benchmark profiles stored in the schema-v3 SQLite database expose the same SensitivityProfile representation as SDF inputs. This keeps database I/O outside the numerical UQ layer.

SQLite sandwich and c-k ranking

from kika.benchmarks import (
    benchmark_uncertainty,
    get_sensitivity_profile,
    rank_benchmarks_by_ck,
)

benchmark = get_sensitivity_profile(profile_id, db_path="benchmarks.db")
uncertainty = benchmark_uncertainty(
    profile_id,
    covariance,
    db_path="benchmarks.db",
)
ranking = rank_benchmarks_by_ck(
    application,
    covariance,
    db_path="benchmarks.db",
    benchmark_ids=["HEU-COMP-INTER-003-001"],
    limit=20,
)

Preferred variants are ranked by signed \(c_k\) in descending order by default, with benchmark id as the deterministic tie-breaker. Set rank_by_absolute=True to rank by \(|c_k|\). Failed candidates are not hidden in strict mode.

ICSBEP/DICE benchmark sensitivities for KIKA.

Build a local, self-contained database from your own NEA-licensed DICE sensitivity data, then screen and rank benchmarks by their sensitivity to a given isotope, reaction and energy region. kika ships no benchmark data itself.

Quick start:

>>> import kika.benchmarks as benchmarks
>>> # One-time build from the DICE sensitivity/ folder:
>>> benchmarks.build_benchmarks_db(source_dir="/path/to/DiceData/sensitivity",
...                                db_path="/path/to/kika_benchmarks.db")
>>> # Then point kika at it (or set KIKA_BENCHMARKS_DB_PATH):
>>> benchmarks.configure(db_path="/path/to/kika_benchmarks.db")
>>> hits = benchmarks.find_sensitive_benchmarks("Fe-56", reaction="elastic",
...                                             energy_region="fast")

kika.benchmarks.configure(db_path: str | None = None, source_dir: str | None = None) → None[source]

Configure default settings for the benchmarks module.

Settings persist for the duration of the Python session.

Parameters:

db_path (str, optional) – Path to the built kika_benchmarks.db SQLite database. Once set, all functions that accept db_path use this as the default.
source_dir (str, optional) – Path to the raw DICE sensitivity/ folder, used only when building the database via kika.benchmarks.build_benchmarks_db().

kika.benchmarks.get_config() → dict[source]: Return a copy of the current benchmarks module configuration.

kika.benchmarks.get_db_path(explicit_path: str | None = None) → str[source]

Resolve the database path to use.

Priority: 1. Explicitly passed path (if not None) 2. Module configuration (set via configure()) 3. Environment variable KIKA_BENCHMARKS_DB_PATH 4. Default ~/.kika/benchmarks/kika_benchmarks.db

Parameters:: explicit_path (str, optional) – Path explicitly passed to a function.
Returns:: The database path to use.
Return type:: str

kika.benchmarks.get_source_dir(explicit_path: str | None = None) → str | None[source]

Resolve the DICE source directory to use for ingest.

Priority: explicit arg > configured > env KIKA_DICE_SOURCE_DIR > None.

kika.benchmarks.reset_config() → None[source]: Reset configuration to defaults.

class kika.benchmarks.BenchmarksDatabase(db_path: str | None = None)[source]

Bases: object

Interface to a built kika_benchmarks.db SQLite database.

close() → None[source]

get_balance(benchmark_id: str) → dict | None[source]

Return the reaction-rate balance {'summary', 'text'} or None.

summary holds the extracted scalars (keff, leakage, n_zones); text is the full balance file rendered verbatim.

get_benchmark(benchmark_id: str) → dict[source]: Return a benchmark’s metadata plus the list of its profile variants.

get_benchmark_dashboard(benchmark_id: str) → dict[source]

Return the whole per-benchmark record in one bundle (for the app dashboard).

Combines metadata, experimental keff, the profile-variant list, the preferred profile’s sensitivity vectors, the flux spectrum, the balance, and the list of available input-deck codes.

get_experimental_keff(benchmark_id: str) → dict[source]: Return {'keff', 'keff_unc'} (the ICSBEP benchmark value), or empty dict.

get_input_deck(benchmark_id: str, code: str | None = None) → List[dict][source]

Return the raw input deck(s) as [{'code', 'text'}] (verbatim).

Pass code ('KENO' / 'MCNP') to fetch a single deck; otherwise all decks stored for the benchmark are returned.

get_preferred_profile(benchmark_id: str) → dict[source]: Return the preferred profile row for a benchmark.

get_profile_vector(profile_id: int, zaid: int | None = None, mt: int | None = None) → dict[source]

Return a profile’s full per-group sensitivity vectors.

Each reaction error vector contains absolute one-sigma standard deviations, or None when errors were not stored. The returned dict matches the app’s SDFSensitivityData shape so the existing SDF plotting components can render it directly:

{"pert_energies": [...], "reactions": [
    {"zaid", "mt", "nuclide", "reaction_name", "sensitivity": [...],
     "error": [...] | None}, ...]}

get_sensitivity_profile(profile_id: int) → SensitivityProfile[source]: Return a profile as a validated, format-neutral UQ object.

get_spectrum(benchmark_id: str) → dict | None[source]: Return the 299-group flux spectrum {'energies', 'flux'} or None.

get_statistics() → dict[source]: Return counts and ingest metadata for the database.

list_benchmarks(category: str | None = None, spectrum: str | None = None, library: str | None = None, search: str | None = None, limit: int = 200, offset: int = 0) → List[dict][source]: List benchmarks with optional filters (one row per benchmark).

list_similarity_profiles(benchmark_ids: List[str] | None = None, preferred_only: bool = True) → List[dict][source]: Return deterministic profile candidates for c-k ranking.

screen(zaid: int, mt: int | None = None, region: str = 'total', sensitivity_threshold: float = 0.0, fraction_threshold: float | None = None, preferred_only: bool = True, limit: int = 100) → List[dict][source]: Return benchmark reactions sensitive to (zaid, mt) in an energy region, ranked by absolute integral sensitivity (descending).

kika.benchmarks.build_benchmarks_db(source_dir: str | None = None, db_path: str | None = None, categories: List[str] | None = None, store_errors: bool = True, store_region_profiles: bool = False, occurrences_rule: Literal['sum', 'first', 'last', 'error'] = 'sum', source_root: str | None = None, overwrite: bool = True, n_workers: int | None = None, progress_callback: Callable[[int, int, str], None] | None = None) → dict[source]

Build the benchmarks database from DICE data.

Parameters:

source_dir (str, optional) – Path to the DICE sensitivity/ folder (containing HEU/IEU/… subfolders). Resolved via kika.benchmarks.config.get_source_dir() if not given.
db_path (str, optional) – Output database path. Resolved via config/env/default if not given.
categories (list of str, optional) – Restrict ingest to these categories (e.g. ["HEU"]) — useful for testing.
store_errors (bool, optional) – Store per-group absolute standard-deviation vectors alongside sensitivities. Default True (roughly doubles the per-group vector storage).
occurrences_rule ({"sum", "first", "last", "error"}, optional) – Resolve repeated reaction keys explicitly. “sum” combines absolute uncertainties in quadrature and is the default.
store_region_profiles (bool, optional) – Also keep the non-system-total per-mixture spatial sub-profiles (the non-(0, 0) (unit, region) profiles). Default False. Enabling this multiplies the sensitivity payload by ~2-3x; screening and preferred-variant selection still use only the (0, 0) system totals.
source_root (str, optional) – DiceData root used to locate the auxiliary sibling folders (input/, spectra/, balance/, keff/). Defaults to the parent of source_dir. Whichever of those folders exist are ingested; missing ones are skipped silently.
overwrite (bool, optional) – Remove any existing database at db_path first. Default True.
n_workers (int, optional) – Number of worker processes. Default os.cpu_count() - 1 (minimum 1).
progress_callback (callable, optional) – Called as progress_callback(index, total, benchmark_id) per file.

Returns:

Summary counts: benchmarks, profiles, reactions, spectra, balance, inputs, keff_matched, db_bytes, files_total, files_skipped, skipped.

Return type:

dict

kika.benchmarks.find_sensitive_benchmarks(isotope: str | int, reaction: str | int | None = None, energy_region: str = 'total', sensitivity_threshold: float = 0.0, fraction_threshold: float | None = None, preferred_only: bool = True, limit: int = 100, db_path: str | None = None) → List[dict][source]

Find benchmarks sensitive to an isotope/reaction in an energy region.

Parameters:

isotope (str or int) – Isotope as ZAID (26056), symbol (‘Fe56’) or hyphenated symbol (‘Fe-56’).
reaction (str or int, optional) – Reaction as MT (2), alias (‘elastic’, ‘capture’) or canonical label (‘(n,el)’). None matches any reaction of the isotope.
energy_region (str) – ‘thermal’, ‘epithermal’, ‘fast’ or ‘total’ (default).
sensitivity_threshold (float) – Minimum absolute integral sensitivity in the region.
fraction_threshold (float, optional) – Minimum |region sensitivity| / (sum of |sensitivity|) for the reaction.
preferred_only (bool) – Only consider the preferred profile per benchmark (default True).
limit (int) – Maximum number of results.
db_path (str, optional) – Explicit database path (otherwise resolved from config/env/default).

Returns:

One row per matching benchmark reaction, ranked by absolute sensitivity (descending). Each row includes benchmark id/category/spectrum, profile code/library, keff, the region sensitivity and its fraction of the total.

Return type:

list of dict

kika.benchmarks.rank_benchmarks(isotope: str | int, reaction: str | int | None = None, energy_region: str = 'total', limit: int = 100, db_path: str | None = None) → List[dict][source]

Rank benchmarks by absolute sensitivity to an isotope/reaction/region.

Convenience wrapper over find_sensitive_benchmarks() with no thresholds.

kika.benchmarks.get_benchmark(benchmark_id: str, db_path: str | None = None) → dict[source]: Return a benchmark’s metadata and its list of profile variants.

kika.benchmarks.get_benchmark_dashboard(benchmark_id: str, db_path: str | None = None) → dict[source]: Return the whole per-benchmark record (metadata, keff, vectors, spectrum, balance, input codes) in a single bundle for the app dashboard.

kika.benchmarks.get_profile_vector(profile_id: int, zaid: int | None = None, mt: int | None = None, db_path: str | None = None) → dict[source]: Return a profile’s full per-group sensitivity vectors (SDFSensitivityData shape).

kika.benchmarks.get_sensitivity_profile(profile_id: int, db_path: str | None = None)[source]: Return a profile as a validated format-neutral sensitivity object.

kika.benchmarks.get_experimental_keff(benchmark_id: str, db_path: str | None = None) → dict[source]: Return a benchmark’s experimental keff {'keff', 'keff_unc'} (empty if unknown).

kika.benchmarks.get_spectrum(benchmark_id: str, db_path: str | None = None) → dict | None[source]: Return a benchmark’s 299-group flux spectrum {'energies', 'flux'} or None.

kika.benchmarks.get_balance(benchmark_id: str, db_path: str | None = None) → dict | None[source]: Return a benchmark’s reaction-rate balance {'summary', 'text'} or None.

kika.benchmarks.get_input_deck(benchmark_id: str, code: str | None = None, db_path: str | None = None) → list[source]: Return a benchmark’s raw input deck(s) as [{'code', 'text'}] (verbatim).

kika.benchmarks.plot_profile(source: str | dict, reactions: Sequence[Tuple[int, int]] | None = None, per_lethargy: bool = True, uncertainty: bool = True, profile_id: int | None = None, db_path: str | None = None, style: str = 'light', figsize: Tuple[float, float] = (8, 6), title: str | None = None, show: bool = False)[source]

Plot the sensitivity profile(s) of a benchmark.

Parameters:

source (str or dict) – A benchmark id (its preferred profile is used) or a profile-vector dict as returned by BenchmarksDatabase.get_profile_vector().
reactions (sequence of (zaid, mt), optional) – Which reactions to draw. Defaults to every reaction in the vector.
per_lethargy (bool) – Plot sensitivity per unit lethargy (default True).
uncertainty (bool) – Draw per-group error bars where error vectors are available.
profile_id (int, optional) – Plot this specific profile instead of the benchmark’s preferred one (ignored when source is a dict).
db_path (str, optional) – Explicit database path (otherwise resolved from config/env/default).
style – Forwarded to / used with PlotBuilder.
figsize – Forwarded to / used with PlotBuilder.
title – Forwarded to / used with PlotBuilder.
show – Forwarded to / used with PlotBuilder.

Return type:

matplotlib.figure.Figure

class kika.benchmarks.BenchmarkSimilarity(benchmark_id: str, profile_id: int, ck: float, n_parameters: int, application_parameter_coverage: float, benchmark_parameter_coverage: float, application_sensitivity_coverage: float, benchmark_sensitivity_coverage: float, code: str | None = None, library: str | None = None, group_structure: str | None = None, result: SimilarityResult | None = None)[source]

Bases: object

One deterministic row in a benchmark c-k ranking.

code: str | None = None

group_structure: str | None = None

library: str | None = None

result: SimilarityResult | None = None

benchmark_id: str

profile_id: int

ck: float

n_parameters: int

application_parameter_coverage: float

benchmark_parameter_coverage: float

application_sensitivity_coverage: float

benchmark_sensitivity_coverage: float

kika.benchmarks.benchmark_uncertainty(profile_id: int, covariance=None, legendre_covariance=None, *, db_path: str | None = None, **kwargs) → UncertaintyResult[source]: Run sandwich propagation for one SQLite benchmark profile.

kika.benchmarks.similarity_ck(application: SensitivityProfile | SDFData, benchmark_profile_id: int, covariance=None, legendre_covariance=None, *, db_path: str | None = None, **kwargs) → SimilarityResult[source]: Calculate c-k between an application and one SQLite benchmark profile.

kika.benchmarks.rank_benchmarks_by_ck(application: SensitivityProfile | SDFData, covariance=None, legendre_covariance=None, *, benchmark_ids: Sequence[str] | None = None, preferred_only: bool = True, limit: int | None = 100, rank_by_absolute: bool = False, db_path: str | None = None, alias_policy: str = 'exact', missing: str = 'error', include=None, exclude=None, include_mt1: bool = False, nubar_mode='total', energy_tolerance: float = 1e-06) → List[BenchmarkSimilarity][source]

Rank SQLite benchmark profiles by covariance-weighted c-k.

Covariance normalization is performed once. In strict mode any candidate that cannot be aligned aborts the ranking with its benchmark/profile label; no failed candidate is silently omitted.

exception kika.benchmarks.BenchmarksError[source]

Bases: Exception

Base class for all benchmarks-subpackage errors.

exception kika.benchmarks.DatabaseNotConfiguredError[source]

Bases: BenchmarksError

Raised when no benchmarks database path is configured or the file is missing.

exception kika.benchmarks.BenchmarkNotFoundError[source]

Bases: BenchmarksError

Raised when a requested benchmark id or profile is not present in the database.

Thin benchmark-database adapters for Kika’s format-neutral UQ APIs.

class kika.benchmarks.uq.BenchmarkSimilarity(benchmark_id: str, profile_id: int, ck: float, n_parameters: int, application_parameter_coverage: float, benchmark_parameter_coverage: float, application_sensitivity_coverage: float, benchmark_sensitivity_coverage: float, code: str | None = None, library: str | None = None, group_structure: str | None = None, result: SimilarityResult | None = None)[source]

Bases: object

One deterministic row in a benchmark c-k ranking.

benchmark_id: str

profile_id: int

ck: float

n_parameters: int

application_parameter_coverage: float

benchmark_parameter_coverage: float

application_sensitivity_coverage: float

benchmark_sensitivity_coverage: float

code: str | None = None

library: str | None = None

group_structure: str | None = None

result: SimilarityResult | None = None

kika.benchmarks.uq.benchmark_uncertainty(profile_id: int, covariance=None, legendre_covariance=None, *, db_path: str | None = None, **kwargs) → UncertaintyResult[source]: Run sandwich propagation for one SQLite benchmark profile.

kika.benchmarks.uq.similarity_ck(application: SensitivityProfile | SDFData, benchmark_profile_id: int, covariance=None, legendre_covariance=None, *, db_path: str | None = None, **kwargs) → SimilarityResult[source]: Calculate c-k between an application and one SQLite benchmark profile.

kika.benchmarks.uq.rank_benchmarks_by_ck(application: SensitivityProfile | SDFData, covariance=None, legendre_covariance=None, *, benchmark_ids: Sequence[str] | None = None, preferred_only: bool = True, limit: int | None = 100, rank_by_absolute: bool = False, db_path: str | None = None, alias_policy: str = 'exact', missing: str = 'error', include=None, exclude=None, include_mt1: bool = False, nubar_mode='total', energy_tolerance: float = 1e-06) → List[BenchmarkSimilarity][source]

Rank SQLite benchmark profiles by covariance-weighted c-k.

Covariance normalization is performed once. In strict mode any candidate that cannot be aligned aborts the ranking with its benchmark/profile label; no failed candidate is silently omitted.