Data Models

The core data structures for representing material extractions.

Experiment

class litxbench.core.models.Experiment(raw_materials: 'dict[str, RawMaterial]', synthesis_groups: 'InitVar[dict[str, list[ProcessEvent]] | list[ProcessEvent]]', output_materials: 'list[Material[MeasurementClass]]', descriptions: 'list[DescriptionGroup[MeasurementClass, MeasurementKind]]'=<factory>)[source]
Parameters:
raw_materials: dict[str, RawMaterial]
synthesis_groups: dataclasses.InitVar[dict[str, list[litxbench.core.models.ProcessEvent]] | list[litxbench.core.models.ProcessEvent]]
output_materials: list[Material[MeasurementClass]]
descriptions: list[DescriptionGroup[MeasurementClass, MeasurementKind]]
synthesis_group_map: dict[str, SynthesisGroup]

Material

class litxbench.core.models.Material(*, process: 'str | None' = None, name: 'str | None' = None, measurements: 'Sequence[MeasurementClass]')[source]
Parameters:

  • process (str | None)

  • name (str | None)

  • measurements (Sequence[MeasurementClass])

process: str | None = None
name: str | None = None
measurements: Sequence[MeasurementClass]
process_steps: list[ProcessStep] | None = None

Measurements

class litxbench.core.models.Measurement(*, kind: 'str', value: 'float | int | str', unit: 'pint.Unit', uncertainty: 'float | None' = None, measurement_method: 'MeasurementMethodT | None' = None, description: 'str | None' = None, source: 'str | None' = None, temperature: 'Quantity | None' = None, pressure: 'Quantity | None' = None, measurement_statistic: 'MeasurementStatistic | None' = None, percentile: 'float | None' = None, group_name: 'str | None' = None, group_id: 'uuid.UUID | None' = None)[source]
Parameters:

  • kind (str)

  • value (float | int | str)

  • unit (Unit)

  • uncertainty (float | None)

  • measurement_method (MeasurementMethodT | None)

  • description (str | None)

  • source (str | None)

  • temperature (Quantity | None)

  • pressure (Quantity | None)

  • measurement_statistic (MeasurementStatistic | None)

  • percentile (float | None)

  • group_name (str | None)

  • group_id (UUID | None)

kind: str
value: float | int | str
unit: Unit
uncertainty: float | None = None
measurement_method: MeasurementMethodT | None = None
description: str | None = None
source: str | None = None
temperature: Quantity | None = None
pressure: Quantity | None = None
numeric_value: float | int | None = None
value_qualifier: ValueQualifier = 'exact'
measurement_statistic: MeasurementStatistic | None = None
percentile: float | None = None
group_name: str | None = None
group_id: UUID | None = None
static group_measurements(kind: str, unit: Unit, measurement_method: MeasurementMethodT, description: str | None = None, uncertainty: float | None = None, temperature: Quantity | None = None, pressure: Quantity | None = None, source: str | None = None, group_name: str | None = None, values: list[CoreMeasurementValue] = None) → list[Measurement[MeasurementMethodT]][source]
static group_measurements(kind: str, unit: Unit, measurement_method: None = None, description: str | None = None, uncertainty: float | None = None, temperature: Quantity | None = None, pressure: Quantity | None = None, source: str | None = None, group_name: str | None = None, values: list[CoreMeasurementValue] = None) → list[Measurement[Any]]
Parameters:

  • kind (str)

  • unit (Unit)

  • measurement_method (MeasurementMethodT | None)

  • description (str | None)

  • uncertainty (float | None)

  • temperature (Quantity | None)

  • pressure (Quantity | None)

  • source (str | None)

  • group_name (str | None)

  • values (list[CoreMeasurementValue] | None)

Return type:

list[Measurement[MeasurementMethodT]] | list[Measurement[Any]]

class litxbench.core.models.CompMeasurement(composition: 'Composition | str | dict[str, float]', method: 'MeasurementMethod' = <MeasurementMethod.Unspecified: 'unspecified'>, description: 'str | None' = None, source: 'str | None' = None, validate_composition: 'bool' = True) → 'None'[source]
Parameters:
composition: Composition
method: MeasurementMethod
description: str | None = None
source: str | None = None
validate_composition: bool = True
class litxbench.core.models.Configuration(*, name: 'str | None' = None, within: 'str | None' = None, struct: 'CrysStruct | None' = None, tags: 'set[ConfigTag] | None' = None, description: 'str | None' = None, source: 'str | None' = None, measurements: 'list[Measurement[MeasurementMethod] | LatticeMeasurement | CompMeasurement]' = <factory>)[source]
Parameters:
name: str | None = None
within: str | None = None
struct: CrysStruct | None = None
tags: set[ConfigTag] | None = None
description: str | None = None
source: str | None = None
measurements: list[Measurement[MeasurementMethod] | LatticeMeasurement | CompMeasurement]
class litxbench.core.models.GlobalLatticeParam(lattice: 'LatticeMeasurement | None' = None, struct: 'CrysStruct | None' = None, name: 'str | None' = None, description: 'str | None' = None, phase_fraction: 'Quantity | None' = None, source: 'str | None' = None)[source]
Parameters:
lattice: LatticeMeasurement | None = None
struct: CrysStruct | None = None
name: str | None = None
description: str | None = None
phase_fraction: Quantity | None = None
source: str | None = None
class litxbench.core.models.LatticeMeasurement(lattice: 'PymatgenLattice', description: 'str | None' = None, source: 'str | None' = None)[source]
Parameters:

  • lattice (Lattice)

  • description (str | None)

  • source (str | None)

lattice: Lattice
description: str | None = None
source: str | None = None

Process

class litxbench.core.models.ProcessEvent(*, kind: 'ProcessKind', description: 'str | None' = None, temperature: 'Quantity | None' = None, duration: 'Quantity | None' = None, equipment: 'str | None' = None, source: 'str | None' = None, inputs: 'list[str]' = <factory>)[source]
Parameters:
kind: ProcessKind
description: str | None = None
temperature: Quantity | None = None
duration: Quantity | None = None
equipment: str | None = None
source: str | None = None
inputs: list[str]
class litxbench.core.models.ProcessStep(base_name, variables, inputs=<factory>)[source]

Structured representation of a process step.

Replaces string notation with structured dataclass for easier validation and manipulation.

Parameters:
base_name: str

The base name of the process step (e.g., “annealing”, “melting”).

variables: dict[str, str]

Variable assignments - {"Temp": "800"} for materials, {"Temp": ""} for event templates.

inputs: list[str]

Input names feeding into this step (e.g., raw materials, named materials).

classmethod parse_material_step(step, *, inputs=None)[source]

Parse a material step like ‘annealing[Temp=800]’.

Parameters:
Return type:

ProcessStep

classmethod parse_process_string(process)[source]

Parse a full process string into a list of ProcessSteps.

Uses a single arrow type “->” to separate segments: - First segment = comma-separated input names - Remaining segments = steps parsed by parse_material_step

The first segment must always contain at least one explicit input.

Parameters:

process (str)

Return type:

list[ProcessStep]

classmethod parse_event_name(event_name)[source]

Parse an event definition like ‘annealing[Temp]’.

Parameters:

event_name (str)

Return type:

ProcessStep

to_string()[source]

Convert back to string notation for serialization/display.

Return type:

str

class litxbench.core.models.SynthesisGroup(name, base_name, template_vars, process_events)[source]

Structured representation of a synthesis group with template variables.

Parameters:
name: str

The full event name (e.g., “annealing[Temp]”).

base_name: str

The base name without brackets (e.g., “annealing”).

template_vars: set[str]

Set of template variable names (e.g., {“Temp”}).

process_events: list[ProcessEvent]

List of process events that may contain template placeholders.

classmethod from_name_and_events(name, process_events)[source]

Parse event name and create SynthesisGroup.

Parameters:
Return type:

SynthesisGroup

substitute_variables(variable_values)[source]

Substitute template variables in process events.

Parameters:

variable_values (dict[str, str])

Return type:

list[ProcessEvent]

Quantities & Raw Materials

class litxbench.core.models.Quantity(value: 'float | int | str', unit: 'pint.Unit', description: 'str | None' = None, source: 'str | None' = None)[source]
Parameters:
value: float | int | str
unit: Unit
description: str | None = None
source: str | None = None
numeric_value: float | int | None = None
value_qualifier: ValueQualifier = 'exact'
class litxbench.core.models.RawMaterial(*, kind: 'RawMaterialKind', description: 'str | None' = None, source: 'str | None' = None)[source]
Parameters:
kind: RawMaterialKind
description: str | None = None
source: str | None = None