nook.model

The data model returned by every source backend.

class nook.model.Level(index, energy, spin_parity=<factory>, half_life=<factory>, energy_offset=None, band=None, metastable=False, questionable=False, decay_modes=(), dataset=None, xref=(), observed_in=(), transfer_l=(), transfer_l_raw=None, spectroscopic_factor=None, magnetic_dipole=None, electric_quadrupole=None, properties=<factory>, raw=<factory>)

Bases: object

A single nuclear level.

energy is keV above the ground state. When energy_offset is set the position is unknown and energy is only the numeric part of offset + energy (manual V.18).

index: int

energy: Uncertain

spin_parity: SpinParity

half_life: HalfLife

energy_offset: str | None = None

band: str | None = None

metastable: bool = False

questionable: bool = False

decay_modes: tuple[tuple[str, Uncertain], ...] = ()

dataset: str | None = None

xref: tuple[str, ...] = ()

ENSDF XREF symbols – which datasets reported this level.

observed_in: tuple[str, ...] = ()

The same, resolved to dataset identifiers via the X records.

transfer_l: tuple[int, ...] = ()

Transferred angular momenta from the L field of a reaction dataset.

transfer_l_raw: str | None = None

spectroscopic_factor: Uncertain | None = None

Spectroscopic factor from the S field.

magnetic_dipole: Uncertain | None = None

Magnetic dipole moment, nuclear magnetons (ENSDF MOMM1).

electric_quadrupole: Uncertain | None = None

Electric quadrupole moment, barn (ENSDF MOME2).

properties: Mapping[str, str]

Everything from the data-continuation records, as raw text.

raw: Mapping[str, Any]

property energy_kev: float | None

property is_floating: bool

True if the excitation energy carries an unknown offset.

property jpi: JPi | None

Shorthand for an unambiguous spin-parity, else None.

class nook.model.Gamma(energy, start_index=None, end_index=None, intensity=None, multipolarity=None, mixing_ratio=None, conversion_coefficient=None, final_level_energy=None, properties=<factory>, raw=<factory>)

Bases: object

An electromagnetic transition between two levels.

energy: Uncertain

start_index: int | None = None

end_index: int | None = None

intensity: Uncertain | None = None

multipolarity: str | None = None

mixing_ratio: Uncertain | None = None

conversion_coefficient: Uncertain | None = None

final_level_energy: float | None = None

Final-level energy stated by an FL= continuation, if present.

properties: Mapping[str, str]

Everything from the gamma data-continuation records, as raw text.

raw: Mapping[str, Any]

property energy_kev: float | None

class nook.model.LevelScheme(nuclide, levels=(), gammas=(), source='', dataset=None, metadata=<factory>)

Bases: object

Levels plus gamma transitions for one nuclide from one source.

nuclide: Nuclide

levels: tuple[Level, ...] = ()

gammas: tuple[Gamma, ...] = ()

source: str = ''

dataset: str | None = None

metadata: dict[str, Any]

filter(predicate)

A new scheme keeping only levels satisfying predicate.

below(energy_kev)

Levels at or below energy_kev (floating levels are dropped).

with_known_jpi(allow_tentative=True)

Levels carrying an unambiguous spin-parity assignment.

complete_up_to(allow_tentative=True)

Truncate at the first level lacking a firm E, J and pi.

This reproduces the usual RIPL-style “discrete level cutoff” used when handing a level scheme to a reaction code: everything below the first incompletely characterised level.

isomers(min_half_life_s=1e-09)

Levels living longer than min_half_life_s.

seen_in(pattern)

Levels reported by a dataset whose identifier contains pattern.

Provenance filtering: scheme.seen_in("(P,D)") keeps only levels a transfer measurement actually observed, rather than every level the evaluator adopted from anywhere.

band(label)

Levels carrying the ENSDF band flag label (column 77).

bands()

Every labelled band, ordered by bandhead energy.

Not every flag has a BAND() definition – 180Ta uses 27 and documents 24 – so band_definition() may return None for a group returned here. Labels are case-sensitive.

band_definition(label)

The decoded BAND() text, or None if it was never defined.

level_by_index(index)

The level with this ENSDF index, or None if it isn’t present.

decays_from(level)

to_records()

Flat dict-per-level, convenient for pandas.DataFrame.

to_dataframe()

Requires pandas; kept optional so the core stays stdlib-only.