plesty.fss.data

The fine_structure data kind: what a polarization sweep says about each line.

Importing this module registers the kind, so ExperimentData.load rebuilds a saved result and fine_structure resolves as an analyzer schema dtype.

Classes

FineStructureData

Fine structure of each fitted line, one entry per line.

Module Contents

class plesty.fss.data.FineStructureData(values: Mapping[str, numpy.typing.ArrayLike], wavelength_unit: str | None = 'nm', metadata: dict[str, Any] | None = None, provenance: dict[str, Any] | None = None)

Bases: plesty.lib.data.ExperimentData

Fine structure of each fitted line, one entry per line.

Produced by plesty.fss.FineStructure. Every array has shape (peaks,), nan where a line’s sweep could not be fitted.

fss	fine-structure splitting (µeV)
fss_wavelength	the same splitting as a wavelength (wavelength unit)
axis_deg	rotator angle of the longer-wavelength line (deg)
mean_center	mean line position over the sweep (wavelength unit)
r_squared	coefficient of determination of the sweep fit
n_points	sweep points the fit used
fwhm	median fitted linewidth over the sweep (wavelength unit)
fss_valid	1 when fss_wavelength < fwhm (fss is a splitting), else 0

fss, fss_wavelength, axis_deg and mean_center each have a one-sigma <name>_err array. metadata records the rotator, the sweep coordinate (angle) and its period_deg.

The splitting is the peak-to-peak amplitude of the oscillation of one fitted line’s position with the rotator angle, divided by the rotator’s contrast (½ for a quarter-wave plate, else 1). It measures a doublet only while the doublet’s two components are closer than the linewidth and appear as one line, whose position cannot then move by more than that linewidth. An oscillation at least as wide as the line (fss_valid == 0) means the fit followed a different line from frame to frame — typically because the two components are further apart than their linewidth and appear as two separate lines — and fss is then not a splitting.

Validate the arrays and attach their units.

Parameters:

• values (Mapping[str, numpy.typing.ArrayLike]) – Every name in names(), as arrays.

• wavelength_unit (str | None) – Unit of the fitted spectrum’s axis.

• metadata (dict[str, Any] | None) – Sweep context (rotator, angle, period_deg).

• provenance (dict[str, Any] | None) – Origin of the data.

Raises:

ValueError – If a name is missing, the metadata lacks period_deg, or the shapes disagree.

kind = 'fine_structure'

Registry key and schema dtype token, e.g. "spectrum".

schema_version = 1

Version of the array layout this class writes and reads.

QUANTITIES: ClassVar[tuple[str, ...]] = ('fss', 'fss_wavelength', 'axis_deg', 'mean_center')

columns

array name → entry, in reading order.

An entry’s keys, all optional:

• label — the column heading, inline markup and $math$ allowed; the array name when left out.

• unit — used when the array carries none of its own.

• description — one line of meaning.

• result — False for an array the analysis kept but a reader does not need (a fit quality, a point count); default True.

• error — name of the array holding this one’s one-sigma uncertainty, so the two are shown as one value ± error.

Arrays left out are not tabulated.

Type:

What each array means to a reader

values: dict[str, plesty.lib.data.PlestyArray]

Every array by name.

classmethod names() → tuple[str, ...]

Return every array name, in storage order.

Return type:

tuple[str, …]

static _units(wavelength: str | None) → dict[str, str | None]

Return the unit of each array.

Parameters:

wavelength (str | None)

Return type:

dict[str, str | None]

__getitem__(name: str) → plesty.lib.data.PlestyArray

Return the array called name, e.g. result["fss"].

Parameters:

name (str)

Return type:

plesty.lib.data.PlestyArray

property n_peaks: int

Number of lines.

Return type:

int

property period_deg: float

Rotator angle over which each line’s position repeats.

Return type:

float

evaluate(angle_deg: numpy.typing.ArrayLike) → numpy.ndarray

Evaluate each line’s fitted position at rotator angles.

Parameters:

angle_deg (numpy.typing.ArrayLike) – Rotator angles in degrees, 1-D.

Returns:

Positions of shape (angles, peaks), in the wavelength unit.

Return type:

numpy.ndarray

to_arrays() → dict[str, plesty.lib.data.PlestyArray]

Return every array by name.

Return type:

dict[str, plesty.lib.data.PlestyArray]

classmethod from_arrays(arrays: dict[str, plesty.lib.data.PlestyArray], metadata: dict[str, Any], provenance: dict[str, Any]) → Self

Rebuild the result from to_arrays(); units travel with the arrays.

Parameters:

• arrays (dict[str, plesty.lib.data.PlestyArray])

• metadata (dict[str, Any])

• provenance (dict[str, Any])

Return type:

Self

classmethod example() → Self

Return one line at 775 nm with a 40 µeV splitting seen through a half-wave plate.

Return type:

Self