analysis

Fitting analysis: minimizers, fit parameters, and results.

Modules:

Name	Description
analysis	Analysis orchestration of fitting, parameters, and results.
calculators	CrysFML, CrysPy, and PDFfit calculation backends.
categories	CIF categories for fitting analysis configuration.
corrections	Calculator-independent corrections applied on top of a backend pattern.
enums	Enumeration types used by analysis components.
fit_helpers	Fit-result reporting and Bayesian posterior summaries.
fitting	Fitter orchestrating model refinement via a pluggable minimizer.
minimizers	Minimizer adapters for lmfit, bumps, dfo-ls and emcee.
sequential	Sequential fitting infrastructure: template, worker, CSV, recovery.
verification	Helpers for the documentation cross-engine verification pages.

Classes

Modules

analysis

Analysis orchestration of fitting, parameters, and results.

Classes:

Name	Description
UndoFitOutcome	Summary of one undo-fit operation.
AnalysisDisplay	Display helper - parameter tables, CIF, and fit results.
Analysis	High-level orchestration of analysis tasks for a Project.

Classes

UndoFitOutcome(restored_parameter_names, cleared_fit_result, cleared_sidecar, was_no_op) dataclass

Summary of one undo-fit operation.

Attributes:

Name	Type	Description
restored_parameter_names	tuple[str, ...]	Unique names of parameters restored to pre-fit values.
cleared_fit_result	bool	Whether a committed fit-result projection was cleared.
cleared_sidecar	bool	Whether in-memory sidecar arrays were cleared.
was_no_op	bool	Whether the call found no fit to undo.

AnalysisDisplay(analysis)

Display helper - parameter tables, CIF, and fit results.

Accessed via analysis.display.

Methods:

Name	Description
help	Print available analysis-display methods.
all_params	Print all parameters for structures and experiments.
fittable_params	Print all fittable parameters.
free_params	Print only currently free (varying) parameters.
how_to_access_parameters	Show Python access paths for all parameters.
parameter_uids	Show the constraint unique identifier per parameter.
parameter_edi_tags	Show the Edi persistence tag for every parameter.
parameter_cif_tags	Show the report CIF tag for every parameter.
constraints	Print a table of all user-defined symbolic constraints.
fit_results	Display a summary of the fit results.
as_cif	Render the analysis section as text in console.

Methods:

help()

Print available analysis-display methods.

all_params()

Print all parameters for structures and experiments.

fittable_params()

Print all fittable parameters.

free_params()

Print only currently free (varying) parameters.

how_to_access_parameters()

Show Python access paths for all parameters.

The output explains how to reference specific parameters in code.

parameter_uids()

Show the constraint unique identifier per parameter.

parameter_edi_tags()

Show the Edi persistence tag for every parameter.

parameter_cif_tags()

Show the report CIF tag for every parameter.

constraints()

Print a table of all user-defined symbolic constraints.

fit_results()

Display a summary of the fit results.

Renders the fit quality metrics (reduced χ², R-factors) and a table of fitted parameters with their starting values, final values, and uncertainties.

This method should be called after :meth:Analysis.fit completes. If no fit has been performed yet, a warning is logged.

as_cif()

Render the analysis section as text in console.

Analysis(project)

High-level orchestration of analysis tasks for a Project.

This class wires calculators and minimizers, exposes a compact interface for parameters, constraints and results, and coordinates computations across the project's structures and experiments.

Parameters:

Name	Type	Description	Default
project	object	The project that owns models and experiments.	required

Methods:

Name	Description
help	Print a summary of analysis properties and methods.
fit	Execute fitting for the currently selected fitting mode.
calculate	Calculate the diffraction pattern for every experiment.
undo_fit	Roll back the latest fit output and scalar state.
show_as_text	Pretty-print the analysis section as text.
__str__	Return the string representation of this object.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.

Attributes:

Name	Type	Description
fitting_mode	FittingMode	Active fitting-mode selector category.
minimizer	MinimizerCategoryBase	Active minimizer settings and result category.
joint_fit	object	Per-experiment weight collection for joint fitting.
sequential_fit	SequentialFit	Persisted settings for sequential fitting.
sequential_fit_extract	SequentialFitExtractCollection	Persisted extract rules for sequential fitting.
as_cif	str	Serialize the analysis section to a CIF string.
unique_name	str	Fallback unique name: the class name.
parameters	list	All parameters from all owned categories.
categories	list	All category objects owned by this object, sorted by priority.
fit_parameters	FitParameters	Persisted fit-parameter control snapshots.
fit_result	FitResultBase	Persisted common fit-result status metadata.
fit_parameter_correlations	FitParameterCorrelations	Persisted fit-parameter correlation summaries.
software	Software	Software snapshot for the latest successful fit.
project	object	Project that owns this analysis section.
aliases	object	Alias mappings used by symbolic constraints and displays.
constraints	object	Symbolic constraints owned by this analysis section.
display	AnalysisDisplay	Display helper for parameter tables, CIF, and fit results.
fitter	Fitter	Fitting engine used by this analysis object.
fit_results	object | None	Results from the most recent fit, if any.

Attributes

fitting_mode property

Active fitting-mode selector category.

minimizer property

Active minimizer settings and result category.

joint_fit property

Per-experiment weight collection for joint fitting.

sequential_fit property

Persisted settings for sequential fitting.

sequential_fit_extract property

Persisted extract rules for sequential fitting.

as_cif property

Serialize the analysis section to a CIF string.

Returns:

Type	Description
str	The analysis section represented as a CIF document string.

unique_name property

Fallback unique name: the class name.

parameters property

All parameters from all owned categories.

categories property

All category objects owned by this object, sorted by priority.

fit_parameters property

Persisted fit-parameter control snapshots.

fit_result property

Persisted common fit-result status metadata.

fit_parameter_correlations property

Persisted fit-parameter correlation summaries.

software property

Software snapshot for the latest successful fit.

project property

Project that owns this analysis section.

aliases property

Alias mappings used by symbolic constraints and displays.

constraints property

Symbolic constraints owned by this analysis section.

display property

Display helper for parameter tables, CIF, and fit results.

fitter property writable

Fitting engine used by this analysis object.

fit_results property writable

Results from the most recent fit, if any.

Methods:

help()

Print a summary of analysis properties and methods.

fit(*, resume=False, extra_steps=None)

Execute fitting for the currently selected fitting mode.

calculate()

Calculate the diffraction pattern for every experiment.

Refreshes the linked structures and each experiment so the calculated intensities (experiment.data.intensity_calc) reflect the current parameters and the selected calculation engines. This is the non-fitting counterpart of :meth:fit: call it after changing parameters or a calculator to update the calculated pattern without running a minimization.

undo_fit()

Roll back the latest fit output and scalar state.

Returns:

Type	Description
UndoFitOutcome	Summary of the rollback operation.

show_as_text()

Pretty-print the analysis section as text.

__str__()

Return the string representation of this object.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

Functions:

calculators

CrysFML, CrysPy, and PDFfit calculation backends.

Modules:

Name	Description
base	Abstract base API for diffraction calculation backends.
crysfml	CrysFML calculation backend for powder diffraction patterns.
cryspy	CrysPy calculation backend for diffraction patterns.
factory	Calculator factory — delegates to FactoryBase.
pdffit	PDF calculation backend using diffpy.pdffit2 if available.
support	Calculator support matrix.

Classes

Modules

base

Abstract base API for diffraction calculation backends.

Classes:

Name	Description
PowderReflnRecord	Calculated powder reflection metadata for one reflection row.
CalculatorBase	Base API for diffraction calculation engines.

Classes

PowderReflnRecord(structure_id, d_spacing, sin_theta_over_lambda, index_h, index_k, index_l, f_calc, f_squared_calc, two_theta=None, time_of_flight=None) dataclass

Calculated powder reflection metadata for one reflection row.

CalculatorBase

Base API for diffraction calculation engines.

Methods:

Name	Description
calculate_structure_factors	Calculate structure factors for one experiment.
calculate_pattern	Calculate diffraction pattern for one structure-experiment pair.
last_powder_refln_records	Return the last powder reflection records for one structure.

Attributes:

Name	Type	Description
name	str	Short identifier of the calculation engine.
engine_imported	bool	True if the underlying calculation library is available.

Attributes

name abstractmethod property

Short identifier of the calculation engine.

engine_imported abstractmethod property

True if the underlying calculation library is available.

Methods:

calculate_structure_factors(structure, experiment, *, called_by_minimizer) abstractmethod

Calculate structure factors for one experiment.

calculate_pattern(structure, experiment, *, called_by_minimizer) abstractmethod

Calculate diffraction pattern for one structure-experiment pair.

Parameters:

Name	Type	Description	Default
structure	Structures	The structure object.	required
experiment	ExperimentBase	The experiment object.	required
called_by_minimizer	bool	Whether the calculation is called by a minimizer. Default is False.	required

Returns:

Type	Description
np.ndarray	The calculated diffraction pattern as a NumPy array.

last_powder_refln_records(structure, experiment, *, structure_id)

Return the last powder reflection records for one structure.

Backends that do not expose powder reflection metadata return None so callers can clear stale reflection rows and warn.

crysfml

CrysFML calculation backend for powder diffraction patterns.

Builds a CrysFML CFL description (PATTERN_* and PHASE_* blocks) from the structure and experiment and runs cfml_py_utilities.patterns_simulation to obtain the calculated pattern. The backend uses the CFL API exclusively.

Notes

The CFL patterns_simulation path only supports a uniform calculation grid (GEN_PATT xmin step xmax); the grid is derived from the experiment x-axis assuming uniform spacing. Constant-wavelength patterns are fully supported. The upstream CFL simulation currently parses but does not apply Zero_Sy when placing CW reflections, so the two-theta zero is encoded by shifting the calculation grid. Time-of-flight patterns parse but return zero intensities, because the upstream CFL simulation does not yet implement the TOF branch.

Classes:

Name	Description
CrysfmlCalculator	Wrapper for Crysfml library.

Classes

CrysfmlCalculator()

Wrapper for Crysfml library.

Methods:

Name	Description
calculate_structure_factors	Call Crysfml to calculate structure factors.
calculate_pattern	Calculate the diffraction pattern using Crysfml.
last_powder_refln_records	Return the last powder reflection records for one structure.

Attributes:

Name	Type	Description
name	str	Short identifier of this calculator engine.

Attributes

name property

Short identifier of this calculator engine.

Methods:

calculate_structure_factors(structures, experiments)

Call Crysfml to calculate structure factors.

Parameters:

Name	Type	Description	Default
structures	Structures	The structures to calculate structure factors for.	required
experiments	Experiments	The experiments associated with the sample models.	required

Raises:

Type	Description
NotImplementedError	HKL calculation is not implemented for CrysfmlCalculator.

calculate_pattern(structure, experiment, *, called_by_minimizer=False)

Calculate the diffraction pattern using Crysfml.

Parameters:

Name	Type	Description	Default
structure	Structures	The structure to calculate the pattern for.	required
experiment	ExperimentBase	The experiment associated with the structure.	required
called_by_minimizer	bool	Whether the calculation is called by a minimizer.	False

Returns:

Type	Description
np.ndarray | list[float]	The calculated diffraction pattern as a NumPy array or a list of floats.

Raises:

Type	Description
ValueError	If experiment is time-of-flight; CrysFML's CFL backend has no time-of-flight branch.

last_powder_refln_records(structure, experiment, *, structure_id)

Return the last powder reflection records for one structure.

Backends that do not expose powder reflection metadata return None so callers can clear stale reflection rows and warn.

Modules

cryspy

CrysPy calculation backend for diffraction patterns.

Classes:

Name	Description
CryspyCalculator	Cryspy-based diffraction calculator.

Classes

CryspyCalculator()

Cryspy-based diffraction calculator.

Converts EasyDiffraction models into Cryspy objects and computes patterns.

Methods:

Name	Description
calculate_structure_factors	Raise NotImplementedError as HKL calculation is not implemented.
calculate_pattern	Calculate the diffraction pattern using Cryspy.
last_powder_refln_records	Return powder reflection records from the latest pattern run.

Attributes:

Name	Type	Description
name	str	Short identifier of this calculator engine.

Attributes

name property

Short identifier of this calculator engine.

Methods:

calculate_structure_factors(structure, experiment, *, called_by_minimizer=False)

Raise NotImplementedError as HKL calculation is not implemented.

Parameters:

Name	Type	Description	Default
structure	Structure	The structure to calculate structure factors for.	required
experiment	ExperimentBase	The experiment associated with the sample models.	required
called_by_minimizer	bool	Whether the calculation is called by a minimizer.	False

calculate_pattern(structure, experiment, *, called_by_minimizer=False)

Calculate the diffraction pattern using Cryspy.

We only recreate the cryspy_obj if this method is - NOT called by the minimizer, or - the cryspy_dict is NOT yet created. In other cases, we are modifying the existing cryspy_dict This allows significantly speeding up the calculation

Parameters:

Name	Type	Description	Default
structure	Structure	The structure to calculate the pattern for.	required
experiment	ExperimentBase	The experiment associated with the structure.	required
called_by_minimizer	bool	Whether the calculation is called by a minimizer.	False

Returns:

Type	Description
np.ndarray | list[float]	The calculated diffraction pattern as a NumPy array or a list of floats.

last_powder_refln_records(structure, experiment, *, structure_id)

Return powder reflection records from the latest pattern run.

Functions:

Modules

factory

Calculator factory — delegates to FactoryBase.

Overrides _supported_map to filter out calculators whose engines are not importable in the current environment.

Classes:

Name	Description
CalculatorFactory	Factory for creating calculation engine instances.

Classes

CalculatorFactory

Factory for creating calculation engine instances.

Only calculators whose engine_imported flag is True are available for creation.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

pdffit

PDF calculation backend using diffpy.pdffit2 if available.

The class adapts the engine to EasyDiffraction calculator interface and silences stdio on import to avoid noisy output in notebooks and logs.

Classes:

Name	Description
PdffitCalculator	Wrapper for Pdffit library.

Classes

PdffitCalculator

Wrapper for Pdffit library.

Methods:

Name	Description
calculate_structure_factors	Return an empty list; PDF does not compute structure factors.
calculate_pattern	Calculate the PDF pattern using PDFfit2.
last_powder_refln_records	Return the last powder reflection records for one structure.

Attributes:

Name	Type	Description
name	str	Short identifier of this calculator engine.

Attributes

name property

Short identifier of this calculator engine.

Methods:

calculate_structure_factors(structures, experiments)

Return an empty list; PDF does not compute structure factors.

Parameters:

Name	Type	Description	Default
structures	object	Unused; kept for interface consistency.	required
experiments	object	Unused; kept for interface consistency.	required

Returns:

Type	Description
list	An empty list.

calculate_pattern(structure, experiment, *, called_by_minimizer=False)

Calculate the PDF pattern using PDFfit2.

Parameters:

Name	Type	Description	Default
structure	Structure	The structure object supplying atom sites and cell parameters.	required
experiment	ExperimentBase	The experiment object supplying instrument and peak parameters.	required
called_by_minimizer	bool	Unused; kept for interface consistency.	False

last_powder_refln_records(structure, experiment, *, structure_id)

Return the last powder reflection records for one structure.

Backends that do not expose powder reflection metadata return None so callers can clear stale reflection rows and warn.

support

Calculator support matrix.

Aggregates the per-instrument Compatibility and CalculatorSupport metadata declared on the registered instrument categories into a single queryable matrix: which calculation engines can compute which experiment conditions. Used by the Verification documentation to enumerate comparable engine x condition combinations.

Classes:

Name	Description
SupportEntry	One instrument condition and the engines that can compute it.

Functions:

Name	Description
calculator_support_matrix	Return the engine x experiment-condition support matrix.

Classes

SupportEntry(instrument_tag, description, compatibility, calculators) dataclass

One instrument condition and the engines that can compute it.

Attributes:

Name	Type	Description
instrument_tag	str	The instrument category tag (for example 'cwl-pd-neutron').
description	str	One-line human-readable description of the instrument.
compatibility	Compatibility	The experimental conditions (sample_form x scattering_type x beam_mode x radiation_probe) the instrument supports.
calculators	frozenset	The CalculatorEnum engines declared able to handle it.

Functions:

calculator_support_matrix()

Return the engine x experiment-condition support matrix.

One entry per registered instrument category, pairing its Compatibility with the calculators declared able to handle it.

Returns:

Type	Description
list[SupportEntry]	One entry per registered instrument category.

categories

CIF categories for fitting analysis configuration.

Modules:

Name	Description
aliases	Parameter alias categories for fit expressions.
constraints	Parameter constraint categories for fitting.
fit_parameter_correlations	Fit parameter correlation categories from fit results.
fit_parameters	Refined fit parameter categories with values and errors.
fit_result	Fit-result categories for least-squares and Bayesian fits.
fitting_mode	Analysis fitting-mode category exports.
joint_fit	Joint-fit categories for fitting multiple experiments together.
minimizer	Minimizer category implementations.
sequential_fit	Sequential-fit category for fitting experiments one by one.
sequential_fit_extract	Categories for extracted results of a sequential fit.
software	Analysis software-provenance category exports.

Classes

Modules

aliases

Parameter alias categories for fit expressions.

Modules:

Name	Description
default	Alias category for mapping friendly names to parameters.
factory	Aliases factory — delegates entirely to FactoryBase.

Classes

Modules

default

Alias category for mapping friendly names to parameters.

Defines a small record type used by analysis configuration to refer to parameters via readable ids instead of opaque identifiers. At runtime each alias holds a direct object reference to the parameter; for CIF serialization the parameter's unique_name is stored.

Classes:

Name	Description
Alias	Single alias entry.
Aliases	Collection of :class:Alias items.

Classes

Alias()

Single alias entry.

Maps a human-readable id to a parameter object. The parameter_unique_name descriptor stores the parameter's unique_name for CIF serialization.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
id	StringDescriptor	Human-readable alias id (e.g. 'biso_La').
param	object | None	The referenced parameter object, or None before resolution.
parameter_unique_name	StringDescriptor	Unique name of the referenced parameter (for CIF).
parameters	list	Descriptors owned by this alias (excludes the param reference).
unique_name	str	Fully qualified name: datablock, category, entry.
as_cif	str	Return CIF representation of this object.

Attributes

id property writable

Human-readable alias id (e.g. 'biso_La').

Reading this property returns the underlying StringDescriptor object. Assigning to it updates the parameter value.

param property

The referenced parameter object, or None before resolution.

parameter_unique_name property

Unique name of the referenced parameter (for CIF).

Reading this property returns the underlying StringDescriptor object.

parameters property

Descriptors owned by this alias (excludes the param reference).

unique_name property

Fully qualified name: datablock, category, entry.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

Aliases()

Collection of :class:Alias items.

Methods:

Name	Description
create	Create a new alias mapping an id to a parameter.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

create(*, id, param)

Create a new alias mapping an id to a parameter.

Parameters:

Name	Type	Description	Default
id	str	Human-readable alias name (e.g. 'biso_La').	required
param	object	The parameter object to reference.	required

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

factory

Aliases factory — delegates entirely to FactoryBase.

Classes:

Name	Description
AliasesFactory	Create alias collections by tag.

Classes

AliasesFactory

Create alias collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

constraints

Parameter constraint categories for fitting.

Modules:

Name	Description
default	Simple symbolic constraint between parameters.
factory	Constraints factory — delegates entirely to FactoryBase.

Classes

Modules

default

Simple symbolic constraint between parameters.

Represents an equation of the form lhs_alias = rhs_expr stored as a single expression string. The left- and right-hand sides are derived by splitting the expression at the = sign.

Classes:

Name	Description
Constraint	Single constraint item stored as lhs = rhs expression.
Constraints	Collection of :class:Constraint items.

Classes

Constraint()

Single constraint item stored as lhs = rhs expression.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
id	StringDescriptor	Explicit identifier for this constraint row.
expression	StringDescriptor	Full constraint equation (e.g. 'occ_Ba = 1 - occ_La').
lhs_alias	str	Left-hand side alias derived from the expression.
rhs_expr	str	Right-hand side expression derived from the expression.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

id property writable

Explicit identifier for this constraint row.

expression property writable

Full constraint equation (e.g. 'occ_Ba = 1 - occ_La').

Reading this property returns the underlying StringDescriptor object. Assigning to it updates the value.

lhs_alias property

Left-hand side alias derived from the expression.

rhs_expr property

Right-hand side expression derived from the expression.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

Constraints()

Collection of :class:Constraint items.

Methods:

Name	Description
enable	Activate constraints so they are applied during fitting.
disable	Deactivate constraints without deleting them.
create	Create a constraint from an expression string.
show	Print a table of all user-defined symbolic constraints.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.

Attributes:

Name	Type	Description
enabled	bool	Whether constraints are currently active.
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

enabled property

Whether constraints are currently active.

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

enable()

Activate constraints so they are applied during fitting.

disable()

Deactivate constraints without deleting them.

create(*, expression, id=None)

Create a constraint from an expression string.

Automatically enables constraints on the first call.

Parameters:

Name	Type	Description	Default
expression	str	Constraint equation, e.g. 'biso_Co2 = biso_Co1' or 'occ_Ba = 1 - occ_La'.	required
id	str | None	Explicit row identifier. When not None, this value is used as the collection key instead of the left-hand alias.	None

show()

Print a table of all user-defined symbolic constraints.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

Functions:

factory

Constraints factory — delegates entirely to FactoryBase.

Classes:

Name	Description
ConstraintsFactory	Create constraint collections by tag.

Classes

ConstraintsFactory

Create constraint collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

fit_parameter_correlations

Fit parameter correlation categories from fit results.

Modules:

Name	Description
default	Persisted fit-parameter correlation summaries.
factory	Fit-parameter-correlation factory.

Classes

Modules

default

Persisted fit-parameter correlation summaries.

Classes:

Name	Description
FitParameterCorrelationItem	Single persisted fit-parameter correlation row.
FitParameterCorrelations	Collection of persisted fit-parameter correlation summaries.

Classes

FitParameterCorrelationItem()

Single persisted fit-parameter correlation row.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
id	StringDescriptor	Stable identifier for the persisted correlation row.
source_kind	EnumDescriptor	Origin of the persisted correlation summary.
parameter_unique_name_i	StringDescriptor	First unique parameter name in the persisted pair.
parameter_unique_name_j	StringDescriptor	Second unique parameter name in the persisted pair.
correlation	NumericDescriptor	Persisted correlation coefficient for the parameter pair.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

id property

Stable identifier for the persisted correlation row.

source_kind property

Origin of the persisted correlation summary.

parameter_unique_name_i property

First unique parameter name in the persisted pair.

parameter_unique_name_j property

Second unique parameter name in the persisted pair.

correlation property

Persisted correlation coefficient for the parameter pair.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

FitParameterCorrelations()

Collection of persisted fit-parameter correlation summaries.

Methods:

Name	Description
create	Create a persisted fit-parameter correlation row.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

create(*, source_kind, parameter_unique_name_i, parameter_unique_name_j, correlation, id=None)

Create a persisted fit-parameter correlation row.

Parameters:

Name	Type	Description	Default
source_kind	str	Origin of the persisted correlation summary.	required
parameter_unique_name_i	str	First unique parameter name in the pair.	required
parameter_unique_name_j	str	Second unique parameter name in the pair.	required
correlation	float	Correlation coefficient for the parameter pair.	required
id	str | None	Explicit persisted row identifier. When omitted, a simple sequential identifier is generated.	None

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

factory

Fit-parameter-correlation factory.

Classes:

Name	Description
FitParameterCorrelationsFactory	Create fit-parameter correlation collections by tag.

Classes

FitParameterCorrelationsFactory

Create fit-parameter correlation collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

fit_parameters

Refined fit parameter categories with values and errors.

Modules:

Name	Description
default	Fit-parameter control snapshots.
factory	Fit-parameter factory.

Classes

Modules

default

Fit-parameter control snapshots.

Classes:

Name	Description
FitParameterItem	Single persisted fit-parameter control row.
FitParameters	Collection of persisted fit-parameter control snapshots.

Classes

FitParameterItem()

Single persisted fit-parameter control row.

Methods:

Name	Description
has_posterior_summary	Return whether any posterior summary field is populated.
posterior_summary	Return this row as a posterior summary, if populated.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
parameter_unique_name	StringDescriptor	Unique name of the referenced live parameter.
fit_min	NumericDescriptor	Persisted lower fit bound.
fit_max	NumericDescriptor	Persisted upper fit bound.
bounds_uncertainty_multiplier	NumericDescriptor	Multiplier used to derive fit bounds from uncertainty.
start_value	NumericDescriptor	Persisted pre-fit value snapshot.
start_uncertainty	NumericDescriptor	Persisted pre-fit uncertainty snapshot.
posterior_best_sample_value	NumericDescriptor	Highest-posterior sampled parameter value.
posterior_median	NumericDescriptor	Posterior median value.
posterior_uncertainty	NumericDescriptor	Posterior standard deviation.
posterior_interval_68_low	NumericDescriptor	Lower bound of the 68% credible interval.
posterior_interval_68_high	NumericDescriptor	Upper bound of the 68% credible interval.
posterior_interval_95_low	NumericDescriptor	Lower bound of the 95% credible interval.
posterior_interval_95_high	NumericDescriptor	Upper bound of the 95% credible interval.
posterior_gelman_rubin	NumericDescriptor	Rank-normalized split-R-hat when available.
posterior_effective_sample_size_bulk	NumericDescriptor	Bulk effective sample size when available.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

parameter_unique_name property

Unique name of the referenced live parameter.

fit_min property

Persisted lower fit bound.

fit_max property

Persisted upper fit bound.

bounds_uncertainty_multiplier property

Multiplier used to derive fit bounds from uncertainty.

start_value property

Persisted pre-fit value snapshot.

start_uncertainty property

Persisted pre-fit uncertainty snapshot.

posterior_best_sample_value property

Highest-posterior sampled parameter value.

posterior_median property

Posterior median value.

posterior_uncertainty property

Posterior standard deviation.

posterior_interval_68_low property

Lower bound of the 68% credible interval.

posterior_interval_68_high property

Upper bound of the 68% credible interval.

posterior_interval_95_low property

Lower bound of the 95% credible interval.

posterior_interval_95_high property

Upper bound of the 95% credible interval.

posterior_gelman_rubin property

Rank-normalized split-R-hat when available.

posterior_effective_sample_size_bulk property

Bulk effective sample size when available.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

has_posterior_summary()

Return whether any posterior summary field is populated.

posterior_summary(*, display_name)

Return this row as a posterior summary, if populated.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

FitParameters()

Collection of persisted fit-parameter control snapshots.

Methods:

Name	Description
create	Create a persisted fit-parameter control snapshot row.
set_posterior_summary	Attach a posterior summary to an existing row.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

create(*, parameter_unique_name, fit_min, fit_max, bounds_uncertainty_multiplier=None, start_value=None, start_uncertainty=None)

Create a persisted fit-parameter control snapshot row.

Parameters:

Name	Type	Description	Default
parameter_unique_name	str	Unique name of the referenced live parameter.	required
fit_min	float	Persisted lower fit bound.	required
fit_max	float	Persisted upper fit bound.	required
bounds_uncertainty_multiplier	float | None	Multiplier used to derive fit bounds from uncertainty.	None
start_value	float | None	Persisted pre-fit value snapshot.	None
start_uncertainty	float | None	Persisted pre-fit uncertainty snapshot.	None

set_posterior_summary(summary)

Attach a posterior summary to an existing row.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

factory

Fit-parameter factory.

Classes:

Name	Description
FitParametersFactory	Create fit-parameter collections by tag.

Classes

FitParametersFactory

Create fit-parameter collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

fit_result

Fit-result categories for least-squares and Bayesian fits.

Modules:

Name	Description
base	Common fit-result status category.
bayesian	Bayesian fit-result category.
default	Default fit-result category import.
factory	Fit-result factory.
lsq	Least-squares fit-result category.

Classes

Modules

base

Common fit-result status category.

Classes:

Name	Description
FitResultBase	Common persisted fit-result status metadata.

Classes

FitResultBase()

Common persisted fit-result status metadata.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
result_kind	EnumDescriptor	Kind of the latest persisted fit-result projection.
success	BoolDescriptor	Whether the latest persisted fit-result projection succeeded.
message	StringDescriptor	Status message for the latest persisted fit-result projection.
iterations	IntegerDescriptor	Iteration count for the latest persisted fit-result projection.
fitting_time	NumericDescriptor	Fitting time in seconds for the latest persisted projection.
reduced_chi_square	NumericDescriptor	Reduced chi-square for the latest persisted projection.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

result_kind property

Kind of the latest persisted fit-result projection.

success property

Whether the latest persisted fit-result projection succeeded.

message property

Status message for the latest persisted fit-result projection.

iterations property

Iteration count for the latest persisted fit-result projection.

fitting_time property

Fitting time in seconds for the latest persisted projection.

reduced_chi_square property

Reduced chi-square for the latest persisted projection.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bayesian

Bayesian fit-result category.

Classes:

Name	Description
BayesianFitResult	Persisted Bayesian fit-result metadata.

Classes

BayesianFitResult()

Persisted Bayesian fit-result metadata.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
point_estimate_name	StringDescriptor	Committed sampled point estimate name.
sampler_completed	BoolDescriptor	Whether the sampler completed and returned posterior data.
credible_interval_inner	NumericDescriptor	Inner credible-interval level used in summaries.
credible_interval_outer	NumericDescriptor	Outer credible-interval level used in summaries.
resolved_random_seed	IntegerDescriptor	Runtime random seed used by the sampler.
acceptance_rate_mean	NumericDescriptor	Mean sampler acceptance rate.
gelman_rubin_max	NumericDescriptor	Maximum rank-normalized split R-hat.
effective_sample_size_min	NumericDescriptor	Minimum bulk effective sample size.
best_log_posterior	NumericDescriptor	Best log-posterior value found.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
result_kind	EnumDescriptor	Kind of the latest persisted fit-result projection.
success	BoolDescriptor	Whether the latest persisted fit-result projection succeeded.
message	StringDescriptor	Status message for the latest persisted fit-result projection.
iterations	IntegerDescriptor	Iteration count for the latest persisted fit-result projection.
fitting_time	NumericDescriptor	Fitting time in seconds for the latest persisted projection.
reduced_chi_square	NumericDescriptor	Reduced chi-square for the latest persisted projection.

Attributes

point_estimate_name property

Committed sampled point estimate name.

sampler_completed property

Whether the sampler completed and returned posterior data.

credible_interval_inner property

Inner credible-interval level used in summaries.

credible_interval_outer property

Outer credible-interval level used in summaries.

resolved_random_seed property

Runtime random seed used by the sampler.

acceptance_rate_mean property

Mean sampler acceptance rate.

gelman_rubin_max property

Maximum rank-normalized split R-hat.

effective_sample_size_min property

Minimum bulk effective sample size.

best_log_posterior property

Best log-posterior value found.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

result_kind property

Kind of the latest persisted fit-result projection.

success property

Whether the latest persisted fit-result projection succeeded.

message property

Status message for the latest persisted fit-result projection.

iterations property

Iteration count for the latest persisted fit-result projection.

fitting_time property

Fitting time in seconds for the latest persisted projection.

reduced_chi_square property

Reduced chi-square for the latest persisted projection.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

default

Default fit-result category import.

Classes

factory

Fit-result factory.

Classes:

Name	Description
FitResultFactory	Create fit-result categories by tag.

Classes

FitResultFactory

Create fit-result categories by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

lsq

Least-squares fit-result category.

Classes:

Name	Description
LeastSquaresFitResult	Persisted least-squares fit-result metadata.

Classes

LeastSquaresFitResult()

Persisted least-squares fit-result metadata.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
result_kind	EnumDescriptor	Kind of the latest persisted fit-result projection.
success	BoolDescriptor	Whether the latest persisted fit-result projection succeeded.
message	StringDescriptor	Status message for the latest persisted fit-result projection.
iterations	IntegerDescriptor	Iteration count for the latest persisted fit-result projection.
fitting_time	NumericDescriptor	Fitting time in seconds for the latest persisted projection.
reduced_chi_square	NumericDescriptor	Reduced chi-square for the latest persisted projection.
prof_r_factor	NumericDescriptor	Profile R factor for powder fits.
prof_wr_factor	NumericDescriptor	Weighted profile R factor for powder fits.
prof_wr_expected	NumericDescriptor	Expected weighted profile R factor for powder fits.
number_restraints	NumericDescriptor	Number of restraints used in the deterministic fit.
number_constraints	NumericDescriptor	Number of constraints used in the deterministic fit.
shift_over_su_max	NumericDescriptor	Maximum absolute parameter shift divided by s.u.
shift_over_su_mean	NumericDescriptor	Mean absolute parameter shift divided by s.u.
profile_function	StringDescriptor	Active profile function names.
background_function	StringDescriptor	Active background function names.
r_factor_all	NumericDescriptor	R factor for all observed data.
wr_factor_all	NumericDescriptor	Weighted R factor for all observed data.
r_factor_gt	NumericDescriptor	R factor for observations above the threshold.
wr_factor_gt	NumericDescriptor	Weighted R factor for observations above the threshold.
threshold_expression	StringDescriptor	Expression defining the observed-reflection threshold.
number_reflns_total	NumericDescriptor	Total number of reflections represented in the fit.
number_reflns_gt	NumericDescriptor	Number of reflections above the observed threshold.
objective_name	StringDescriptor	Objective function name for the persisted deterministic fit.
objective_value	NumericDescriptor	Objective value for the persisted deterministic fit.
n_data_points	NumericDescriptor	Number of data points used in the persisted deterministic fit.
n_parameters	NumericDescriptor	Number of parameters in the persisted deterministic fit.
n_free_parameters	NumericDescriptor	Number of free parameters in the persisted deterministic fit.
degrees_of_freedom	NumericDescriptor	Degrees of freedom for the persisted deterministic fit.
covariance_available	BoolDescriptor	Whether deterministic covariance was available.
correlation_available	BoolDescriptor	Whether deterministic correlations were available.
exit_reason	StringDescriptor	Backend exit reason for the persisted deterministic fit.

Attributes

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

result_kind property

Kind of the latest persisted fit-result projection.

success property

Whether the latest persisted fit-result projection succeeded.

message property

Status message for the latest persisted fit-result projection.

iterations property

Iteration count for the latest persisted fit-result projection.

fitting_time property

Fitting time in seconds for the latest persisted projection.

reduced_chi_square property

Reduced chi-square for the latest persisted projection.

prof_r_factor property

Profile R factor for powder fits.

prof_wr_factor property

Weighted profile R factor for powder fits.

prof_wr_expected property

Expected weighted profile R factor for powder fits.

number_restraints property

Number of restraints used in the deterministic fit.

number_constraints property

Number of constraints used in the deterministic fit.

shift_over_su_max property

Maximum absolute parameter shift divided by s.u.

shift_over_su_mean property

Mean absolute parameter shift divided by s.u.

profile_function property

Active profile function names.

background_function property

Active background function names.

r_factor_all property

R factor for all observed data.

wr_factor_all property

Weighted R factor for all observed data.

r_factor_gt property

R factor for observations above the threshold.

wr_factor_gt property

Weighted R factor for observations above the threshold.

threshold_expression property

Expression defining the observed-reflection threshold.

number_reflns_total property

Total number of reflections represented in the fit.

number_reflns_gt property

Number of reflections above the observed threshold.

objective_name property

Objective function name for the persisted deterministic fit.

objective_value property

Objective value for the persisted deterministic fit.

n_data_points property

Number of data points used in the persisted deterministic fit.

n_parameters property

Number of parameters in the persisted deterministic fit.

n_free_parameters property

Number of free parameters in the persisted deterministic fit.

degrees_of_freedom property

Degrees of freedom for the persisted deterministic fit.

covariance_available property

Whether deterministic covariance was available.

correlation_available property

Whether deterministic correlations were available.

exit_reason property

Backend exit reason for the persisted deterministic fit.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

fitting_mode

Analysis fitting-mode category exports.

Modules:

Name	Description
default	Analysis fitting-mode category.
factory	Factory for analysis fitting-mode categories.

Classes

Modules

default

Analysis fitting-mode category.

Classes:

Name	Description
FittingMode	Fitting-mode selector for an analysis.

Classes

FittingMode()

Fitting-mode selector for an analysis.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

factory

Factory for analysis fitting-mode categories.

Classes:

Name	Description
FittingModeFactory	Create analysis fitting-mode category instances.

Classes

FittingModeFactory

Create analysis fitting-mode category instances.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

joint_fit

Joint-fit categories for fitting multiple experiments together.

Modules:

Name	Description
default	Joint-fit weighting configuration.
factory	Joint-fit factory - delegates to FactoryBase.

Classes

Modules

default

Joint-fit weighting configuration.

Stores per-experiment weights to be used when multiple experiments are fitted simultaneously.

Classes:

Name	Description
JointFitItem	A single joint-fit entry.
JointFitCollection	Collection of :class:JointFitItem items.

Classes

JointFitItem()

A single joint-fit entry.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
experiment_id	StringDescriptor	Experiment identifier.
weight	NumericDescriptor	Weight factor.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

experiment_id property writable

Experiment identifier.

Reading this property returns the underlying StringDescriptor object. Assigning to it updates the parameter value.

weight property writable

Weight factor.

Reading this property returns the underlying NumericDescriptor object. Assigning to it updates the parameter value.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

JointFitCollection()

Collection of :class:JointFitItem items.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.
create	Create a new item with the given attributes and add it.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

create(**kwargs)

Create a new item with the given attributes and add it.

A default instance of the collection's item type is created, then each keyword argument is applied via setattr.

Parameters:

Name	Type	Description	Default
**kwargs	object	Attribute names and values for the new item.	{}

factory

Joint-fit factory - delegates to FactoryBase.

Classes:

Name	Description
JointFitFactory	Create joint-fit collections by tag.

Classes

JointFitFactory

Create joint-fit collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

minimizer

Minimizer category implementations.

Modules:

Name	Description
base	Base class for persisted minimizer category items.
bayesian_base	Behavior helpers for Bayesian minimizer categories.
bumps	Persisted category for the default BUMPS minimizer.
bumps_amoeba	Persisted category for the BUMPS amoeba minimizer.
bumps_de	Persisted category for the BUMPS de minimizer.
bumps_dream	Persisted category for the BUMPS DREAM minimizer.
bumps_lm	Persisted category for the BUMPS lm minimizer.
dfols	Persisted category for the DFO-LS minimizer.
emcee	Persisted category for the emcee minimizer.
factory	Factory for persisted minimizer category items.
lmfit	Persisted category for the default LMFIT minimizer.
lmfit_least_squares	Persisted category for the LMFIT least_squares minimizer.
lmfit_leastsq	Persisted category for the LMFIT leastsq minimizer.
lsq_base	Behavior helpers for deterministic minimizer categories.

Classes

Modules

base

Base class for persisted minimizer category items.

Classes:

Name	Description
MinimizerCategoryBase	Base class for persisted minimizer settings and results.

Classes

MinimizerCategoryBase()

Base class for persisted minimizer settings and results.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bayesian_base

Behavior helpers for Bayesian minimizer categories.

Classes:

Name	Description
BayesianMinimizerBase	Shared behavior for Bayesian minimizer categories.

Classes

BayesianMinimizerBase()

Shared behavior for Bayesian minimizer categories.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
sampling_steps	IntegerDescriptor	Total sampler iterations per chain.
burn_in_steps	IntegerDescriptor	Sampler iterations discarded as warm-up.
thinning_interval	IntegerDescriptor	Sampler thinning interval.
population_size	IntegerDescriptor	Number of chains or walkers.
parallel_workers	IntegerDescriptor	Worker count; 0 uses all available CPUs.
initialization_method	StringDescriptor	Sampler initialization method.
random_seed	IntegerDescriptor	Random seed; None uses a system-derived seed.
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

sampling_steps property writable

Total sampler iterations per chain.

burn_in_steps property writable

Sampler iterations discarded as warm-up.

thinning_interval property writable

Sampler thinning interval.

population_size property writable

Number of chains or walkers.

parallel_workers property writable

Worker count; 0 uses all available CPUs.

initialization_method property writable

Sampler initialization method.

random_seed property writable

Random seed; None uses a system-derived seed.

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bumps

Persisted category for the default BUMPS minimizer.

Classes:

Name	Description
BumpsMinimizer	Persisted settings for the default BUMPS minimizer.

Classes

BumpsMinimizer()

Persisted settings for the default BUMPS minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bumps_amoeba

Persisted category for the BUMPS amoeba minimizer.

Classes:

Name	Description
BumpsAmoebaMinimizer	Persisted settings for the BUMPS amoeba minimizer.

Classes

BumpsAmoebaMinimizer()

Persisted settings for the BUMPS amoeba minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bumps_de

Persisted category for the BUMPS de minimizer.

Classes:

Name	Description
BumpsDeMinimizer	Persisted settings for the BUMPS de minimizer.

Classes

BumpsDeMinimizer()

Persisted settings for the BUMPS de minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bumps_dream

Persisted category for the BUMPS DREAM minimizer.

Classes:

Name	Description
BumpsDreamMinimizer	Persisted settings for the BUMPS DREAM minimizer.

Classes

BumpsDreamMinimizer()

Persisted settings for the BUMPS DREAM minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
chains	IntegerDescriptor	Alias for population_size (the population scale factor).
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
sampling_steps	IntegerDescriptor	Total sampler iterations per chain.
burn_in_steps	IntegerDescriptor	Sampler iterations discarded as warm-up.
thinning_interval	IntegerDescriptor	Sampler thinning interval.
population_size	IntegerDescriptor	Number of chains or walkers.
parallel_workers	IntegerDescriptor	Worker count; 0 uses all available CPUs.
initialization_method	StringDescriptor	Sampler initialization method.
random_seed	IntegerDescriptor	Random seed; None uses a system-derived seed.

Attributes

chains property writable

Alias for population_size (the population scale factor).

DREAM runs ceil(chains * n_parameters) parallel chains. chains and population_size share one descriptor, so setting either updates the same value (no separate value to conflict).

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

sampling_steps property writable

Total sampler iterations per chain.

burn_in_steps property writable

Sampler iterations discarded as warm-up.

thinning_interval property writable

Sampler thinning interval.

population_size property writable

Number of chains or walkers.

parallel_workers property writable

Worker count; 0 uses all available CPUs.

initialization_method property writable

Sampler initialization method.

random_seed property writable

Random seed; None uses a system-derived seed.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

bumps_lm

Persisted category for the BUMPS lm minimizer.

Classes:

Name	Description
BumpsLmMinimizer	Persisted settings for the BUMPS lm minimizer.

Classes

BumpsLmMinimizer()

Persisted settings for the BUMPS lm minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

dfols

Persisted category for the DFO-LS minimizer.

Classes:

Name	Description
DfolsMinimizer	Persisted settings for the DFO-LS minimizer.

Classes

DfolsMinimizer()

Persisted settings for the DFO-LS minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

emcee

Persisted category for the emcee minimizer.

Classes:

Name	Description
EmceeMinimizer	Persisted settings for the emcee minimizer.

Classes

EmceeMinimizer()

Persisted settings for the emcee minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
proposal_moves	StringDescriptor	Single emcee proposal move.
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
sampling_steps	IntegerDescriptor	Total sampler iterations per chain.
burn_in_steps	IntegerDescriptor	Sampler iterations discarded as warm-up.
thinning_interval	IntegerDescriptor	Sampler thinning interval.
population_size	IntegerDescriptor	Number of chains or walkers.
parallel_workers	IntegerDescriptor	Worker count; 0 uses all available CPUs.
initialization_method	StringDescriptor	Sampler initialization method.
random_seed	IntegerDescriptor	Random seed; None uses a system-derived seed.

Attributes

proposal_moves property writable

Single emcee proposal move.

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

sampling_steps property writable

Total sampler iterations per chain.

burn_in_steps property writable

Sampler iterations discarded as warm-up.

thinning_interval property writable

Sampler thinning interval.

population_size property writable

Number of chains or walkers.

parallel_workers property writable

Worker count; 0 uses all available CPUs.

initialization_method property writable

Sampler initialization method.

random_seed property writable

Random seed; None uses a system-derived seed.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

factory

Factory for persisted minimizer category items.

Classes:

Name	Description
MinimizerCategoryFactory	Create minimizer category items by tag.

Classes

MinimizerCategoryFactory

Create minimizer category items by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

lmfit

Persisted category for the default LMFIT minimizer.

Classes:

Name	Description
LmfitMinimizer	Persisted settings for the default LMFIT minimizer.

Classes

LmfitMinimizer()

Persisted settings for the default LMFIT minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

lmfit_least_squares

Persisted category for the LMFIT least_squares minimizer.

Classes:

Name	Description
LmfitLeastSquaresMinimizer	Persisted settings for the LMFIT least_squares minimizer.

Classes

LmfitLeastSquaresMinimizer()

Persisted settings for the LMFIT least_squares minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

lmfit_leastsq

Persisted category for the LMFIT leastsq minimizer.

Classes:

Name	Description
LmfitLeastsqMinimizer	Persisted settings for the LMFIT leastsq minimizer.

Classes

LmfitLeastsqMinimizer()

Persisted settings for the LMFIT leastsq minimizer.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.
max_iterations	IntegerDescriptor	Maximum solver iterations.

Attributes

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

max_iterations property writable

Maximum solver iterations.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

lsq_base

Behavior helpers for deterministic minimizer categories.

Classes:

Name	Description
LeastSquaresMinimizerBase	Shared behavior for least-squares minimizer categories.

Classes

LeastSquaresMinimizerBase()

Shared behavior for least-squares minimizer categories.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
max_iterations	IntegerDescriptor	Maximum solver iterations.
type	str	Active factory tag for this category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

max_iterations property writable

Maximum solver iterations.

type property writable

Active factory tag for this category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

show_supported()

Print supported types and mark the active one.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

sequential_fit

Sequential-fit category for fitting experiments one by one.

Modules:

Name	Description
default	Sequential-fit configuration category.
factory	Sequential-fit factory - delegates to FactoryBase.

Classes

Modules

default

Sequential-fit configuration category.

Stores persisted settings for directory-based sequential fitting.

Classes:

Name	Description
SequentialFit	Persisted settings for sequential fitting.

Classes

SequentialFit()

Persisted settings for sequential fitting.

Methods:

Name	Description
from_cif	Populate this sequential-fit category from a CIF block.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.

Attributes:

Name	Type	Description
data_dir	StringDescriptor	Directory containing sequential-fit data files.
file_pattern	StringDescriptor	Glob pattern selecting sequential-fit files.
max_workers	StringDescriptor	Worker-count token for sequential fitting.
chunk_size	StringDescriptor	Chunk-size token for sequential fitting.
reverse	BoolDescriptor	Whether to process sequential-fit files in reverse.
copy_data	BoolDescriptor	Whether to copy matched data files into the project.
as_cif	str	Return CIF representation of this sequential-fit category.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.

Attributes

data_dir property writable

Directory containing sequential-fit data files.

file_pattern property writable

Glob pattern selecting sequential-fit files.

max_workers property writable

Worker-count token for sequential fitting.

chunk_size property writable

Chunk-size token for sequential fitting.

reverse property writable

Whether to process sequential-fit files in reverse.

copy_data property writable

Whether to copy matched data files into the project.

as_cif property

Return CIF representation of this sequential-fit category.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

Methods:

from_cif(block, idx=0)

Populate this sequential-fit category from a CIF block.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

factory

Sequential-fit factory - delegates to FactoryBase.

Classes:

Name	Description
SequentialFitFactory	Create sequential-fit category items by tag.

Classes

SequentialFitFactory

Create sequential-fit category items by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

sequential_fit_extract

Categories for extracted results of a sequential fit.

Modules:

Name	Description
default	Sequential-fit extract-rule configuration.
factory	Sequential-fit-extract factory - delegates to FactoryBase.

Classes

Modules

default

Sequential-fit extract-rule configuration.

Stores persisted rules for extracting diffrn metadata from sequential fit input files.

Classes:

Name	Description
SequentialFitExtractItem	A single sequential-fit extract rule.
SequentialFitExtractCollection	Collection of :class:SequentialFitExtractItem items.

Classes

SequentialFitExtractItem()

A single sequential-fit extract rule.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
id	StringDescriptor	Identifier for this extract rule.
target	StringDescriptor	Diffrn attribute updated by this extract rule.
pattern	StringDescriptor	Regex used to extract one numeric capture group.
required	BoolDescriptor	Whether this extract rule must match every file.
unique_name	str	Fully qualified name: datablock, category, entry.
parameters	list	All GenericDescriptorBase instances on this item.
as_cif	str	Return CIF representation of this object.

Attributes

id property writable

Identifier for this extract rule.

target property writable

Diffrn attribute updated by this extract rule.

pattern property writable

Regex used to extract one numeric capture group.

required property writable

Whether this extract rule must match every file.

unique_name property

Fully qualified name: datablock, category, entry.

parameters property

All GenericDescriptorBase instances on this item.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

SequentialFitExtractCollection()

Collection of :class:SequentialFitExtractItem items.

Methods:

Name	Description
create	Create a validated sequential-fit extract rule.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
from_cif	Populate this collection from a CIF block.
add	Insert or replace a pre-built item into the collection.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

create(*, id, target, pattern, required=False)

Create a validated sequential-fit extract rule.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

from_cif(block)

Populate this collection from a CIF block.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

factory

Sequential-fit-extract factory - delegates to FactoryBase.

Classes:

Name	Description
SequentialFitExtractFactory	Create sequential-fit-extract collections by tag.

Classes

SequentialFitExtractFactory

Create sequential-fit-extract collections by tag.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

software

Analysis software-provenance category exports.

Modules:

Name	Description
base	Software-provenance row items.
default	Analysis software-provenance category.
factory	Factory for analysis software-provenance categories.

Classes

Modules

base

Software-provenance row items.

Classes:

Name	Description
SoftwareRole	Name, version, and URL for one software role.

Classes

SoftwareRole(role='framework')

Name, version, and URL for one software role.

Parameters:

Name	Type	Description	Default
role	SoftwareRoleEnum | str	Software role represented by this row.	'framework'

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print parameters, other properties, and methods.
from_cif	Populate this item from a CIF block.

Attributes:

Name	Type	Description
id	EnumDescriptor	Software role.
name	StringDescriptor	Software name.
version	StringDescriptor	Software version.
url	StringDescriptor	Software project URL.
parameters	list[StringDescriptor]	Descriptors owned by this software role.
unique_name	str	Fully qualified name: datablock, category, entry.
as_cif	str	Return CIF representation of this object.

Attributes

id property

Software role.

name property writable

Software name.

version property writable

Software version.

url property writable

Software project URL.

parameters property

Descriptors owned by this software role.

unique_name property

Fully qualified name: datablock, category, entry.

as_cif property

Return CIF representation of this object.

Methods:

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print parameters, other properties, and methods.

from_cif(block, idx=0)

Populate this item from a CIF block.

default

Analysis software-provenance category.

Classes:

Name	Description
Software	Software-provenance snapshot for the latest successful fit.

Classes

Software()

Software-provenance snapshot for the latest successful fit.

Methods:

Name	Description
from_cif	Populate software provenance from Edi or legacy CIF.
has_provenance	Return True when any role contains provenance data.
__str__	Human-readable representation of this component.
__repr__	Return the developer representation of this object.
__getattr__	Raise a descriptive error for unknown attribute access.
__setattr__	Set an attribute with access-control diagnostics.
help	Print a summary of public attributes and contained items.
__getitem__	Return an item by name or positional index.
__setitem__	Insert or replace an item under the given identity key.
__delitem__	Delete an item by key or raise KeyError if missing.
__contains__	Check whether an item with the given key exists.
__iter__	Iterate over items in insertion order.
__len__	Return the number of items in the collection.
remove	Remove an item by its key.
clear	Remove every item, then mark the parent datablock dirty.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
add	Insert or replace a pre-built item into the collection.
create	Create a new item with the given attributes and add it.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all items in this collection.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

Methods:

from_cif(block)

Populate software provenance from Edi or legacy CIF.

has_provenance()

Return True when any role contains provenance data.

__str__()

Human-readable representation of this component.

__repr__()

Return the developer representation of this object.

__getattr__(key)

Raise a descriptive error for unknown attribute access.

__setattr__(key, value)

Set an attribute with access-control diagnostics.

help()

Print a summary of public attributes and contained items.

__getitem__(key)

Return an item by name or positional index.

Parameters:

Name	Type	Description	Default
key	str | int	Identity key (str) or zero-based positional index (int).	required

Returns:

Type	Description
GuardedBase	The item matching the given key or index.

Raises:

Type	Description
TypeError	If key is neither str nor int.

__setitem__(name, item)

Insert or replace an item under the given identity key.

__delitem__(name)

Delete an item by key or raise KeyError if missing.

__contains__(name)

Check whether an item with the given key exists.

__iter__()

Iterate over items in insertion order.

__len__()

Return the number of items in the collection.

remove(name)

Remove an item by its key.

Parameters:

Name	Type	Description	Default
name	str	Identity key of the item to remove.	required

clear()

Remove every item, then mark the parent datablock dirty.

Layers dirty-marking on :meth:CollectionBase.clear, mirroring how :meth:add layers it on the base insert.

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

add(item)

Insert or replace a pre-built item into the collection.

Parameters:

Name	Type	Description	Default
item	object	A CategoryItem instance to add.	required

create(**kwargs)

Create a new item with the given attributes and add it.

A default instance of the collection's item type is created, then each keyword argument is applied via setattr.

Parameters:

Name	Type	Description	Default
**kwargs	object	Attribute names and values for the new item.	{}

factory

Factory for analysis software-provenance categories.

Classes:

Name	Description
SoftwareFactory	Create software-provenance categories.

Classes

SoftwareFactory

Create software-provenance categories.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

corrections

Calculator-independent corrections applied on top of a backend pattern.

Each module here adjusts an already-calculated diffraction pattern rather than computing one. The shared informal contract is a module level apply(y, experiment) -> y function that returns the corrected intensities, leaving y unchanged when the correction does not apply. Engines live in the sibling analysis.calculators package; these corrections are consumed by those engines after they return a convolved profile.

Modules:

Name	Description
absorption	Calculator-independent sample-absorption correction factor.
polarization	Calculator-independent CW Lorentz-polarization correction factor.

Modules

absorption

Calculator-independent sample-absorption correction factor.

The correction is a slowly varying envelope of sin^2(theta), so it is applied pointwise to the calculated pattern by both backends rather than per reflection. This keeps the cryspy and crysfml results bit-for-bit consistent on the absorption term.

Functions:

Name	Description
apply	Apply the sample-absorption correction to a calculated pattern.
factor	Return the per-point sample-absorption correction A.

Classes

Functions:

apply(y, experiment)

Apply the sample-absorption correction to a calculated pattern.

Shared by both backends so the absorption term stays identical across calculators. The pattern is returned unchanged when the experiment exposes no absorption category (single-crystal / total scattering), or when it is empty or its length does not match the 2-theta grid (the backends' "no calculated data" paths).

Parameters:

Name	Type	Description	Default
y	object	Calculated intensities (NumPy array or list).	required
experiment	object	Experiment providing data.x (the 2-theta grid) and, when applicable, the active absorption category.	required

Returns:

Type	Description
object	Corrected intensities, or y unchanged when no correction applies.

factor(two_theta, absorption)

Return the per-point sample-absorption correction A.

Parameters:

Name	Type	Description	Default
two_theta	np.ndarray	Scattering angle 2-theta grid in degrees.	required
absorption	object	Active absorption category (its type_info.tag selects the correction form).	required

Returns:

Type	Description
np.ndarray	Multiplicative correction A with the same shape as two_theta; all ones when no correction applies.

polarization

Calculator-independent CW Lorentz-polarization correction factor.

The public instrument stores the physical monochromator angle in degrees. Backends that expose the FullProf/Cryspy form consume cthm = cos^2(2theta_m), while backends without a native field use the same value in the pointwise multiplier here.

Functions:

Name	Description
monochromator_cthm	Return the backend monochromator cthm value.
lp_factor	Return the CW Lorentz-polarization multiplier.
apply	Apply the CW Lorentz-polarization factor to calculated intensities.

Functions:

monochromator_cthm(two_theta_m)

Return the backend monochromator cthm value.

Parameters:

Name	Type	Description	Default
two_theta_m	float	Pre-specimen monochromator 2-theta angle in degrees.	required

Returns:

Type	Description
float	cos^2(two_theta_m) with the angle interpreted in degrees.

lp_factor(two_theta, polarization_coefficient, cthm)

Return the CW Lorentz-polarization multiplier.

Parameters:

Name	Type	Description	Default
two_theta	np.ndarray	Scattering angle 2-theta grid in degrees.	required
polarization_coefficient	float	Dimensionless polarization coefficient, 0 to 1.	required
cthm	float	Monochromator factor cos^2(two_theta_m).	required

Returns:

Type	Description
np.ndarray	Multiplicative Lorentz-polarization factor.

apply(y, experiment)

Apply the CW Lorentz-polarization factor to calculated intensities.

The pattern is returned unchanged unless the experiment has an X-ray CW powder instrument with a nonzero polarization coefficient. Empty arrays and backend no-data paths whose shape does not match the experiment 2-theta grid are also left unchanged.

Parameters:

Name	Type	Description	Default
y	object	Calculated intensities (NumPy array or list).	required
experiment	object	Experiment providing instrument and data.x.	required

Returns:

Type	Description
object	Corrected intensities, or y unchanged when no correction applies.

enums

Enumeration types used by analysis components.

Classes:

Name	Description
FitModeEnum	Fitting mode for the analysis.
FitResultKindEnum	Persisted kind of the latest fit-result projection.
FitCorrelationSourceEnum	Source of a persisted fit-parameter correlation summary.
SoftwareRoleEnum	Role of a software package in the latest fit.

Classes

FitModeEnum

Fitting mode for the analysis.

Methods:

Name	Description
default	Return the default fit mode (SINGLE).
description	Return a human-readable description of this fit mode.

Methods:

default() classmethod

Return the default fit mode (SINGLE).

description()

Return a human-readable description of this fit mode.

FitResultKindEnum

Persisted kind of the latest fit-result projection.

Methods:

Name	Description
default	Return the default persisted fit-result kind.
description	Return a human-readable description of this fit-result kind.

Methods:

default() classmethod

Return the default persisted fit-result kind.

description()

Return a human-readable description of this fit-result kind.

FitCorrelationSourceEnum

Source of a persisted fit-parameter correlation summary.

Methods:

Name	Description
default	Return the default persisted correlation source.
description	Return a human-readable description of this correlation source.

Methods:

default() classmethod

Return the default persisted correlation source.

description()

Return a human-readable description of this correlation source.

SoftwareRoleEnum

Role of a software package in the latest fit.

Methods:

Name	Description
default	Return the default software role.
description	Return a human-readable description of this role.

Methods:

default() classmethod

Return the default software role.

description()

Return a human-readable description of this role.

fit_helpers

Fit-result reporting and Bayesian posterior summaries.

Modules:

Name	Description
bayesian	Bayesian fit result models and posterior data containers.
metrics	R-factor and reduced chi-square fit-quality metrics.
reporting	Least-squares fit-result container and summary rendering.
tracking	Track and display fit and sampler progress during optimization.

Classes

Modules

bayesian

Bayesian fit result models and posterior data containers.

Classes:

Name	Description
PosteriorPredictiveSummary	Posterior predictive summaries for one experiment.
PosteriorSamples	Posterior samples and sample statistics from a Bayesian fit.
BayesianFitResults	Container for Bayesian fit results and posterior summaries.

Functions:

Name	Description
posterior_predictive_cache_key	Return the cache key for one posterior predictive summary.
compute_convergence_diagnostics	Compute convergence diagnostics from posterior samples.
summarize_posterior_parameters	Build posterior parameter summaries in EasyDiffraction order.
standard_deviations_from_summaries	Return posterior standard deviations in summary order.

Classes

PosteriorPredictiveSummary(experiment_name, x_axis_name, x, best_sample_prediction, lower_95=None, upper_95=None, lower_68=None, upper_68=None, draws=None) dataclass

Posterior predictive summaries for one experiment.

Attributes:

Name	Type	Description
experiment_name	str	Experiment identifier.
x_axis_name	str	Name of the x-axis used for the predictive arrays.
x	np.ndarray	X-axis values for the predictive curves.
best_sample_prediction	np.ndarray	Prediction corresponding to the committed point estimate.
lower_95	np.ndarray | None, default=None	Lower bound of the 95% credible interval.
upper_95	np.ndarray | None, default=None	Upper bound of the 95% credible interval.
lower_68	np.ndarray | None, default=None	Lower bound of the 68% credible interval.
upper_68	np.ndarray | None, default=None	Upper bound of the 68% credible interval.
draws	np.ndarray | None, default=None	Optional capped predictive draws with shape (n_draws, n_x).

PosteriorSamples(parameter_names, parameter_samples, log_posterior=None, draw_index=None) dataclass

Posterior samples and sample statistics from a Bayesian fit.

Attributes:

Name	Type	Description
parameter_names	list[str]	Parameter names in the preserved EasyDiffraction order.
parameter_samples	np.ndarray	Sample array with shape (n_draws, n_chains, n_parameters).
log_posterior	np.ndarray | None, default=None	Log-posterior values with shape (n_draws, n_chains) when available.
draw_index	np.ndarray | None, default=None	Optional draw or generation indices associated with the first axis of parameter_samples.

Methods:

Name	Description
flattened	Return flattened posterior samples by parameter.
validate_shapes	Validate stored sample shapes.

Methods:

flattened()

Return flattened posterior samples by parameter.

Returns:

Type	Description
np.ndarray	Array with shape (n_draws * n_chains, n_parameters).

validate_shapes()

Validate stored sample shapes.

Returns:

Type	Description
tuple[int, int, int]	Tuple (n_draws, n_chains, n_parameters).

Raises:

Type	Description
ValueError	If the sample array is not 3-D, the parameter axis does not match parameter_names, or log_posterior (when present) does not match the first two sample axes.

BayesianFitResults(*, success=False, parameters=None, reduced_chi_square=None, engine_result=None, starting_parameters=None, fitting_time=None, sampler_name='dream', point_estimate_name='best_sample', posterior_samples=None, posterior_parameter_summaries=None, posterior_predictive=None, posterior_distribution_caches=None, posterior_pair_caches=None, credible_interval_levels=DEFAULT_CI_LEVELS, sampler_settings=None, convergence_diagnostics=None, sampler_completed=False, best_log_posterior=None) dataclass

Container for Bayesian fit results and posterior summaries.

Attributes:

Name	Type	Description
success	bool, default=False	Whether the Bayesian fit produced usable posterior results.
parameters	list[object] | None, default=None	Final committed parameter objects.
reduced_chi_square	float | None, default=None	Reduced chi-square evaluated at the committed point estimate.
engine_result	object | None, default=None	Opaque backend result object.
starting_parameters	list[object] | None, default=None	Starting parameter objects or snapshots.
fitting_time	float | None, default=None	Total fitting time in seconds.
sampler_name	str, default='dream'	Sampler identifier.
point_estimate_name	str, default='best_sample'	Name of the point estimate committed back to the project.
posterior_samples	PosteriorSamples | None, default=None	Stored posterior samples.
posterior_parameter_summaries	SummaryList, default=None	Posterior summaries for each sampled parameter.
posterior_predictive	PredictiveMap, default=None	Posterior predictive summaries keyed by experiment name.
posterior_distribution_caches	ArrayPayloadMap, default=None	Cached posterior density arrays keyed by parameter name.
posterior_pair_caches	ArrayPayloadMap, default=None	Cached posterior pair-density arrays keyed by cache id.
credible_interval_levels	IntervalLevels, default=DEFAULT_CI_LEVELS	Interval levels available in the summaries.
sampler_settings	SettingsMap, default=None	Sampler settings recorded for reproducibility.
convergence_diagnostics	DiagnosticsMap, default=None	Convergence diagnostics and status metadata.
sampler_completed	bool, default=False	Whether the sampler completed a run and returned posterior data.
best_log_posterior	float | None, default=None	Best log-posterior value reported by the sampler.

Methods:

Name	Description
__post_init__	Initialize inherited FitResults state and normalize containers.
display_results	Render a Bayesian fit summary with posterior diagnostics.

Methods:

__post_init__()

Initialize inherited FitResults state and normalize containers.

display_results(y_obs=None, y_calc=None, y_err=None, f_obs=None, f_calc=None)

Render a Bayesian fit summary with posterior diagnostics.

Parameters:

Name	Type	Description	Default
y_obs	list[float] | None	Observed intensities for pattern R-factor metrics.	None
y_calc	list[float] | None	Calculated intensities for pattern R-factor metrics.	None
y_err	list[float] | None	Standard deviations of observed intensities for wR.	None
f_obs	list[float] | None	Observed structure-factor magnitudes for Bragg R.	None
f_calc	list[float] | None	Calculated structure-factor magnitudes for Bragg R.	None

Functions:

posterior_predictive_cache_key(experiment_name, x_axis_name, *, include_draws=True)

Return the cache key for one posterior predictive summary.

compute_convergence_diagnostics(posterior_samples)

Compute convergence diagnostics from posterior samples.

Parameters:

Name	Type	Description	Default
posterior_samples	PosteriorSamples	Posterior samples container.	required

Returns:

Type	Description
dict[str, object]	Convergence metrics keyed by diagnostic name.

summarize_posterior_parameters(parameter_names, posterior_samples, best_sample_values, parameter_display_names=None, convergence_diagnostics=None)

Build posterior parameter summaries in EasyDiffraction order.

Parameters:

Name	Type	Description	Default
parameter_names	list[str]	Sampled parameter names in EasyDiffraction order.	required
posterior_samples	PosteriorSamples	Posterior sample container.	required
best_sample_values	np.ndarray	Best posterior sample values in the same order.	required
parameter_display_names	list[str] | None	Human-readable parameter names in the same order.	None
convergence_diagnostics	dict[str, object] | None	Optional convergence diagnostics keyed by parameter name.	None

Returns:

Type	Description
list[PosteriorParameterSummary]	Summary rows matching the input parameter order.

Raises:

Type	Description
ValueError	If the posterior sample array is incompatible with the parameter name list.

standard_deviations_from_summaries(summaries)

Return posterior standard deviations in summary order.

Parameters:

Name	Type	Description	Default
summaries	list[PosteriorParameterSummary]	Posterior summaries in parameter order.	required

Returns:

Type	Description
np.ndarray	Standard deviations in the same order.

metrics

R-factor and reduced chi-square fit-quality metrics.

Functions:

Name	Description
calculate_r_factor	Calculate the R-factor between observed and calculated data.
calculate_weighted_r_factor	Calculate weighted R-factor between observed and calculated data.
calculate_rb_factor	Calculate the Bragg R-factor between observed and calculated data.
calculate_r_factor_squared	Calculate the R-factor squared between observed and calculated data.
calculate_reduced_chi_square	Calculate the reduced chi-square statistic.
get_reliability_inputs	Collect observed and calculated data for reliability calculations.

Classes

Functions:

calculate_r_factor(y_obs, y_calc)

Calculate the R-factor between observed and calculated data.

Parameters:

Name	Type	Description	Default
y_obs	np.ndarray	Observed data points.	required
y_calc	np.ndarray	Calculated data points.	required

Returns:

Type	Description
float	R-factor value.

calculate_weighted_r_factor(y_obs, y_calc, weights)

Calculate weighted R-factor between observed and calculated data.

Parameters:

Name	Type	Description	Default
y_obs	np.ndarray	Observed data points.	required
y_calc	np.ndarray	Calculated data points.	required
weights	np.ndarray	Weights for each data point.	required

Returns:

Type	Description
float	Weighted R-factor value.

calculate_rb_factor(y_obs, y_calc)

Calculate the Bragg R-factor between observed and calculated data.

Parameters:

Name	Type	Description	Default
y_obs	np.ndarray	Observed data points.	required
y_calc	np.ndarray	Calculated data points.	required

Returns:

Type	Description
float	Bragg R-factor value.

calculate_r_factor_squared(y_obs, y_calc)

Calculate the R-factor squared between observed and calculated data.

Parameters:

Name	Type	Description	Default
y_obs	np.ndarray	Observed data points.	required
y_calc	np.ndarray	Calculated data points.	required

Returns:

Type	Description
float	R-factor squared value.

calculate_reduced_chi_square(residuals, num_parameters)

Calculate the reduced chi-square statistic.

Parameters:

Name	Type	Description	Default
residuals	np.ndarray	Residuals between observed and calculated data.	required
num_parameters	int	Number of free parameters used in the model.	required

Returns:

Type	Description
float	Reduced chi-square value.

get_reliability_inputs(structures, experiments)

Collect observed and calculated data for reliability calculations.

Parameters:

Name	Type	Description	Default
structures	Structures	Collection of structures.	required
experiments	list[ExperimentBase]	List of experiments.	required

Returns:

Type	Description
np.ndarray	Observed values.
np.ndarray	Calculated values.
np.ndarray | None	Error values, or None if not available.

reporting

Least-squares fit-result container and summary rendering.

Classes:

Name	Description
FitResults	Container for results of a single optimization run.

Classes

FitResults(*, success=False, parameters=None, reduced_chi_square=None, engine_result=None, starting_parameters=None, fitting_time=None, **kwargs)

Container for results of a single optimization run.

Holds success flag, chi-square metrics, iteration counts, timing, and parameter objects. Provides a printer to summarize key indicators and a table of fitted parameters.

Parameters:

Name	Type	Description	Default
success	bool	Indicates if the fit was successful.	False
parameters	list[object] | None	List of parameters used in the fit.	None
reduced_chi_square	float | None	Reduced chi-square value of the fit.	None
engine_result	object | None	Result from the fitting engine.	None
starting_parameters	list[object] | None	Initial parameters for the fit.	None
fitting_time	float | None	Time taken for the fitting process.	None
**kwargs	object	Additional engine-specific fields. If redchi is provided and reduced_chi_square is not set, it is used as the reduced chi-square value.	{}

Methods:

Name	Description
display_results	Render a human-readable summary of the fit.

Methods:

display_results(y_obs=None, y_calc=None, y_err=None, f_obs=None, f_calc=None)

Render a human-readable summary of the fit.

Parameters:

Name	Type	Description	Default
y_obs	list[float] | None	Observed intensities for pattern R-factor metrics.	None
y_calc	list[float] | None	Calculated intensities for pattern R-factor metrics.	None
y_err	list[float] | None	Standard deviations of observed intensities for wR.	None
f_obs	list[float] | None	Observed structure-factor magnitudes for Bragg R.	None
f_calc	list[float] | None	Calculated structure-factor magnitudes for Bragg R.	None

Functions:

tracking

Track and display fit and sampler progress during optimization.

Classes:

Name	Description
SamplerProgressUpdate	Normalized sampler progress payload forwarded by monitor hooks.
FitProgressTracker	Track and report reduced chi-square during optimization.

Classes

SamplerProgressUpdate(iteration, total_iterations, phase, progress_percent, log_posterior, reduced_chi2, elapsed_time, force_report=False) dataclass

Normalized sampler progress payload forwarded by monitor hooks.

FitProgressTracker()

Track and report reduced chi-square during optimization.

The tracker keeps iteration counters, remembers the best observed reduced chi-square and when it occurred, and can display progress as a table in notebooks or a text UI in terminals.

Methods:

Name	Description
reset	Reset internal state before a new optimization run.
track	Update progress with current residuals and parameters.
track_fit_progress	Update fit progress from a backend iteration callback.
track_sampler_progress	Update progress from a sampler monitor.
start_sampler_pre_processing	Mark sampler setup so a status row appears on update.
start_sampler_post_processing	Switch the activity indicator to post-processing.
start_timer	Begin timing of a fit run.
stop_timer	Stop timing and store elapsed time for the run.
start_tracking	Initialize display and headers and announce the minimizer.
add_tracking_info	Append a formatted row to the progress display.
finish_tracking	Finalize progress display and print best result summary.

Attributes:

Name	Type	Description
best_chi2	float | None	Best recorded reduced chi-square value or None.
best_iteration	int | None	Iteration index at which the best chi-square was observed.
iteration	int	Current iteration counter.
fitting_time	float | None	Elapsed time of the last run in seconds, if available.

Attributes

best_chi2 property

Best recorded reduced chi-square value or None.

best_iteration property

Iteration index at which the best chi-square was observed.

iteration property

Current iteration counter.

fitting_time property

Elapsed time of the last run in seconds, if available.

Methods:

reset()

Reset internal state before a new optimization run.

track(residuals, parameters)

Update progress with current residuals and parameters.

Parameters:

Name	Type	Description	Default
residuals	np.ndarray	Residuals between measured and calculated data.	required
parameters	list[float]	Current free parameters being fitted.	required

Returns:

Type	Description
np.ndarray	Residuals unchanged, for optimizer consumption.

track_fit_progress(*, iteration, reduced_chi2, elapsed_time)

Update fit progress from a backend iteration callback.

track_sampler_progress(update)

Update progress from a sampler monitor.

Parameters:

Name	Type	Description	Default
update	SamplerProgressUpdate	Sampler iteration, phase, timing, and fit-quality payload.	required

start_sampler_pre_processing(*, total_iterations)

Mark sampler setup so a status row appears on update.

start_sampler_post_processing(*, log_posterior=None)

Switch the activity indicator to post-processing.

start_timer()

Begin timing of a fit run.

stop_timer()

Stop timing and store elapsed time for the run.

start_tracking(minimizer_name, *, mode=TRACKING_MODE_FIT)

Initialize display and headers and announce the minimizer.

Parameters:

Name	Type	Description	Default
minimizer_name	str	Name of the minimizer used for the run.	required
mode	str	Tracking mode for the run.	TRACKING_MODE_FIT

add_tracking_info(row)

Append a formatted row to the progress display.

Parameters:

Name	Type	Description	Default
row	list[str]	Columns corresponding to the active tracking headers.	required

finish_tracking()

Finalize progress display and print best result summary.

Functions:

fitting

Fitter orchestrating model refinement via a pluggable minimizer.

Classes:

Name	Description
FitterFitOptions	Execution options for one fitter run.
Fitter	Handles the fitting workflow using a pluggable minimizer.

Classes

FitterFitOptions(use_physical_limits=False, random_seed=None, resume=False, extra_steps=None) dataclass

Execution options for one fitter run.

Methods:

Name	Description
as_minimizer_options	Return equivalent minimizer options for this fitter run.

Methods:

as_minimizer_options()

Return equivalent minimizer options for this fitter run.

Fitter(selection=MinimizerTypeEnum.default())

Handles the fitting workflow using a pluggable minimizer.

Methods:

Name	Description
fit	Run the fitting process.

Methods:

fit(structures, experiments, weights=None, analysis=None, verbosity=VerbosityEnum.FULL, *, options=None)

Run the fitting process.

This method performs the optimization but does not display results. Use :meth:show_fit_results on the Analysis object to display the fit results after fitting is complete.

Parameters:

Name	Type	Description	Default
structures	Structures	Collection of structures.	required
experiments	list[ExperimentBase]	List of experiments to fit.	required
weights	np.ndarray | None	Per-experiment weights as a 1-D array (length must match experiments). When None, equal weights are used.	None
analysis	object	Optional Analysis object to update its categories during fitting.	None
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	FitterFitOptions | None	Execution options controlling limits, randomness and resume.	None

Raises:

Type	Description
ValueError	If resume is requested without the same free parameter set used by the saved emcee chain, or if the joint-fit weights are not a 1-D array of one finite, non-negative value per experiment whose total is finite and positive.

Functions:

minimizers

Minimizer adapters for lmfit, bumps, dfo-ls and emcee.

Modules:

Name	Description
base	Abstract base class for pluggable least-squares minimizers.
bumps	Minimizer using the bumps package.
bumps_amoeba	Bumps minimizer variant using the Nelder-Mead simplex method.
bumps_de	Bumps minimizer variant using the differential evolution method.
bumps_dream	Bumps minimizer variant using the DREAM sampler.
bumps_lm	Bumps minimizer variant using the Levenberg-Marquardt method.
dfols	Derivative-free least-squares minimizer built on DFO-LS.
emcee	Minimizer using the emcee ensemble sampler.
emcee_defaults	Shared defaults for the emcee minimizer.
enums	Enumerations for minimizer types.
factory	Minimizer factory — delegates to FactoryBase.
lmfit	Least-squares minimizer adapter built on lmfit.
lmfit_least_squares	LMFIT minimizer variant using trust region reflective method.
lmfit_leastsq	LMFIT minimizer variant using the Levenberg-Marquardt (leastsq) method.

Classes

Modules

base

Abstract base class for pluggable least-squares minimizers.

Classes:

Name	Description
MinimizerFitOptions	Execution options for one minimizer run.
MinimizerBase	Abstract base for concrete minimizers.

Classes

MinimizerFitOptions(finalize_tracking=True, use_physical_limits=False, random_seed=None, resume=False, extra_steps=None) dataclass

Execution options for one minimizer run.

MinimizerBase(name=None, method=None, max_iterations=None)

Abstract base for concrete minimizers.

Contract: - Subclasses must implement _prepare_solver_args, _run_solver, _sync_result_to_parameters and _check_success. - The fit method orchestrates the full workflow and returns :class:FitResults.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

bumps

Minimizer using the bumps package.

Classes:

Name	Description
BumpsMinimizer	Minimizer using the BUMPS package.

Classes

BumpsMinimizer(name=MinimizerTypeEnum.BUMPS, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Minimizer using the BUMPS package.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

bumps_amoeba

Bumps minimizer variant using the Nelder-Mead simplex method.

Classes:

Name	Description
BumpsAmoebaMinimizer	Bumps minimizer using the Nelder-Mead simplex method.

Classes

BumpsAmoebaMinimizer(name=MinimizerTypeEnum.BUMPS_AMOEBA, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Bumps minimizer using the Nelder-Mead simplex method.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

bumps_de

Bumps minimizer variant using the differential evolution method.

Classes:

Name	Description
BumpsDEMinimizer	Bumps minimizer using the differential evolution method.

Classes

BumpsDEMinimizer(name=MinimizerTypeEnum.BUMPS_DE, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Bumps minimizer using the differential evolution method.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

bumps_dream

Bumps minimizer variant using the DREAM sampler.

Classes:

Name	Description
BumpsDreamMinimizer	Bumps minimizer using the DREAM Bayesian sampler.

Classes

BumpsDreamMinimizer(name=MinimizerTypeEnum.BUMPS_DREAM, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Bumps minimizer using the DREAM Bayesian sampler.

Methods:

Name	Description
fit	Run DREAM sampling and return Bayesian fit results.

Attributes:

Name	Type	Description
max_iterations	int	DREAM exposes sampler length through steps instead.
steps	int	Number of DREAM generations retained after burn-in.
burn	int | None	Explicit DREAM burn-in generations or None for auto.
thin	int	DREAM thinning interval.
pop	int	DREAM population multiplier.
chains	int	Friendly alias for pop, the DREAM population scale factor.
parallel	int	DREAM parallel worker count; 0 uses all CPUs.
init	DreamPopulationInitializationEnum	DREAM population initializer.

Attributes

max_iterations property writable

DREAM exposes sampler length through steps instead.

steps property writable

Number of DREAM generations retained after burn-in.

burn property writable

Explicit DREAM burn-in generations or None for auto.

thin property writable

DREAM thinning interval.

pop property writable

DREAM population multiplier.

chains property writable

Friendly alias for pop, the DREAM population scale factor.

DREAM runs ceil(chains * n_parameters) parallel chains, so chains is a per-parameter multiplier rather than an absolute chain count.

parallel property writable

DREAM parallel worker count; 0 uses all CPUs.

init property writable

DREAM population initializer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run DREAM sampling and return Bayesian fit results.

Overrides the base fit so bumps-DREAM supports resume: resume and extra_steps are threaded into the solver, which extends the saved chain instead of starting cold.

Functions:

bumps_lm

Bumps minimizer variant using the Levenberg-Marquardt method.

Classes:

Name	Description
BumpsLmMinimizer	Bumps minimizer explicitly using the Levenberg-Marquardt method.

Classes

BumpsLmMinimizer(name=MinimizerTypeEnum.BUMPS_LM, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Bumps minimizer explicitly using the Levenberg-Marquardt method.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

dfols

Derivative-free least-squares minimizer built on DFO-LS.

Classes:

Name	Description
DfolsMinimizer	Minimizer using DFO-LS (derivative-free least-squares).

Classes

DfolsMinimizer(name=MinimizerTypeEnum.DFOLS, max_iterations=DEFAULT_MAX_ITERATIONS, **kwargs)

Minimizer using DFO-LS (derivative-free least-squares).

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

emcee

Minimizer using the emcee ensemble sampler.

Classes:

Name	Description
EmceeMinimizer	emcee affine-invariant ensemble Bayesian sampler.

Classes

EmceeMinimizer(name=MinimizerTypeEnum.EMCEE, method=DEFAULT_METHOD, max_iterations=DEFAULT_NSTEPS)

emcee affine-invariant ensemble Bayesian sampler.

Methods:

Name	Description
fit	Run emcee sampling and return Bayesian fit results.

Attributes:

Name	Type	Description
nsteps	int	Number of emcee steps to run per walker.
nburn	int	Number of initial emcee steps discarded as burn-in.
thin	int	Emcee thinning interval.
nwalkers	int	Number of emcee walkers.
parallel_workers	int	Worker count; 0 asks for all CPUs and 1 runs serially.
initialization_method	InitializationMethodEnum	Emcee walker initialization method.
proposal_moves	str	Emcee proposal move name.
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

nsteps property writable

Number of emcee steps to run per walker.

nburn property writable

Number of initial emcee steps discarded as burn-in.

thin property writable

Emcee thinning interval.

nwalkers property writable

Number of emcee walkers.

parallel_workers property writable

Worker count; 0 asks for all CPUs and 1 runs serially.

initialization_method property writable

Emcee walker initialization method.

proposal_moves property writable

Emcee proposal move name.

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run emcee sampling and return Bayesian fit results.

Functions:

emcee_defaults

Shared defaults for the emcee minimizer.

Classes

enums

Enumerations for minimizer types.

Classes:

Name	Description
MinimizerTypeEnum	Supported minimizer types.
InitializationMethodEnum	Supported Bayesian sampler initialization methods.
DreamPopulationInitializationEnum	Supported DREAM population initializers.

Classes

MinimizerTypeEnum

Supported minimizer types.

Methods:

Name	Description
default	Return the default minimizer type.
description	Return a human-readable description of this minimizer type.

Methods:

default() classmethod

Return the default minimizer type.

description()

Return a human-readable description of this minimizer type.

InitializationMethodEnum

Supported Bayesian sampler initialization methods.

DreamPopulationInitializationEnum

Supported DREAM population initializers.

factory

Minimizer factory — delegates to FactoryBase.

Classes:

Name	Description
MinimizerFactory	Factory for creating minimizer instances.

Classes

MinimizerFactory

Factory for creating minimizer instances.

Methods:

Name	Description
__init_subclass__	Give each subclass its own independent registry and rules.
register	Class decorator to register a concrete class.
supported_tags	Return list of all supported tags.
default_tag	Resolve the default tag for a given experimental context.
create	Instantiate a registered class by tag.
create_default_for	Instantiate the default class for a given context.
supported_for	Return classes matching conditions and/or calculator.
show_supported	Pretty-print a table of supported types.

Methods:

__init_subclass__(**kwargs)

Give each subclass its own independent registry and rules.

register(klass) classmethod

Class decorator to register a concrete class.

Usage::

@SomeFactory.register class MyClass(SomeBase): type_info = TypeInfo(...)

Returns the class unmodified.

supported_tags() classmethod

Return list of all supported tags.

default_tag(**conditions) classmethod

Resolve the default tag for a given experimental context.

Uses largest-subset matching: the rule whose key is the biggest subset of the given conditions wins. A rule with an empty key (frozenset()) acts as a universal fallback.

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values, e.g. scattering_type=ScatteringTypeEnum.BRAGG.	{}

Returns:

Type	Description
str	The resolved default tag string.

Raises:

Type	Description
ValueError	If no rule matches the given conditions.

create(tag, **kwargs) classmethod

Instantiate a registered class by tag.

Parameters:

Name	Type	Description	Default
tag	str	type_info.tag value.	required
**kwargs	object	Forwarded to the class constructor.	{}

Returns:

Type	Description
object	A new instance of the registered class.

Raises:

Type	Description
ValueError	If tag is not in the registry.

create_default_for(**conditions) classmethod

Instantiate the default class for a given context.

Combines default_tag(**conditions) with create(tag).

Parameters:

Name	Type	Description	Default
**conditions	object	Experimental-axis values.	{}

Returns:

Type	Description
object	A new instance of the default class.

supported_for(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Return classes matching conditions and/or calculator.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum value.	None
sample_form	object	Optional SampleFormEnum value.	None
scattering_type	object	Optional ScatteringTypeEnum value.	None
beam_mode	object	Optional BeamModeEnum value.	None
radiation_probe	object	Optional RadiationProbeEnum value.	None

Returns:

Type	Description
list[type]	Classes matching the given conditions.

show_supported(*, calculator=None, sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None) classmethod

Pretty-print a table of supported types.

Parameters:

Name	Type	Description	Default
calculator	object	Optional CalculatorEnum filter.	None
sample_form	object	Optional SampleFormEnum filter.	None
scattering_type	object	Optional ScatteringTypeEnum filter.	None
beam_mode	object	Optional BeamModeEnum filter.	None
radiation_probe	object	Optional RadiationProbeEnum filter.	None

lmfit

Least-squares minimizer adapter built on lmfit.

Classes:

Name	Description
LmfitMinimizer	Minimizer using the lmfit package.

Classes

LmfitMinimizer(name=MinimizerTypeEnum.LMFIT, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

Minimizer using the lmfit package.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

lmfit_least_squares

LMFIT minimizer variant using trust region reflective method.

Classes:

Name	Description
LmfitLeastSquaresMinimizer	LMFIT minimizer using SciPy's trust region reflective algorithm.

Classes

LmfitLeastSquaresMinimizer(name=MinimizerTypeEnum.LMFIT_LEAST_SQUARES, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

LMFIT minimizer using SciPy's trust region reflective algorithm.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

lmfit_leastsq

LMFIT minimizer variant using the Levenberg-Marquardt (leastsq) method.

Classes:

Name	Description
LmfitLeastsqMinimizer	LMFIT minimizer explicitly using the Levenberg-Marquardt method.

Classes

LmfitLeastsqMinimizer(name=MinimizerTypeEnum.LMFIT_LEASTSQ, method=DEFAULT_METHOD, max_iterations=DEFAULT_MAX_ITERATIONS)

LMFIT minimizer explicitly using the Levenberg-Marquardt method.

Methods:

Name	Description
fit	Run the full minimization workflow.

Attributes:

Name	Type	Description
max_iterations	int | None	User-facing iteration limit for the current minimizer.

Attributes

max_iterations property writable

User-facing iteration limit for the current minimizer.

Methods:

fit(parameters, objective_function, verbosity=VerbosityEnum.FULL, *, options=None)

Run the full minimization workflow.

Parameters:

Name	Type	Description	Default
parameters	list[object]	Free parameters to optimize.	required
objective_function	Callable[..., object]	Callable returning residuals for a given set of engine arguments.	required
verbosity	VerbosityEnum	Console output verbosity.	VerbosityEnum.FULL
options	MinimizerFitOptions | None	Execution options controlling limits, randomness, resume, and tracker finalization.	None

Returns:

Type	Description
FitResults	FitResults with success flag, best chi2 and timing.

Raises:

Type	Description
NotImplementedError	If resume is requested for a minimizer that does not support it.

sequential

Sequential fitting infrastructure: template, worker, CSV, recovery.

Classes:

Name	Description
SequentialFitExtractRule	Picklable sequential-fit extract rule for worker execution.
SequentialFitTemplate	Snapshot of everything a worker needs to recreate and fit a project.
SequentialProgressState	Mutable live progress rows for sequential fitting.
SequentialProgressContext	Mutable sequential-fit progress handles and state.
SequentialRunPlan	Resolved sequential-fit inputs and bookkeeping.

Functions:

Name	Description
fit_sequential	Run sequential fitting over all data files in a directory.

Classes

SequentialFitExtractRule(id, field_name, pattern, required) dataclass

Picklable sequential-fit extract rule for worker execution.

SequentialFitTemplate(structure_cifs, experiment_cif, initial_params, free_parameter_unique_names, alias_defs, constraint_defs, constraints_enabled, minimizer_tag, calculator_tag, diffrn_extract_rules, diffrn_field_names) dataclass

Snapshot of everything a worker needs to recreate and fit a project.

All fields are plain Python types (str, dict, list) so that the template can be pickled for ProcessPoolExecutor.

SequentialProgressState(chunk_rows, file_rows) dataclass

Mutable live progress rows for sequential fitting.

SequentialProgressContext(verbosity, state, indicator=None) dataclass

Mutable sequential-fit progress handles and state.

SequentialRunPlan(verbosity, template, csv_path, header, remaining, chunks, max_workers, processed_count) dataclass

Resolved sequential-fit inputs and bookkeeping.

Functions:

fit_sequential(analysis, data_dir, max_workers=1, chunk_size=None, file_pattern='*', *, reverse=False)

Run sequential fitting over all data files in a directory.

Parameters:

Name	Type	Description	Default
analysis	object	The Analysis instance (owns project reference).	required
data_dir	str	Path to directory containing data files.	required
max_workers	int | str	Number of parallel worker processes. 1 = sequential (no subprocess overhead). 'auto' = physical CPU count. Uses ProcessPoolExecutor with spawn context when > 1.	1
chunk_size	int | None	Files per chunk. Default None uses max_workers.	None
file_pattern	str	Glob pattern to filter files in data_dir.	'*'
reverse	bool	When True, process data files in reverse order. Useful when starting values are better matched to the last file (e.g. highest-temperature dataset in a cooling scan).	False

verification

Helpers for the documentation cross-engine verification pages.

These utilities back the Verification notebooks: they load externally calculated reference profiles (for example FullProf output), populate an experiment grid from a reference pattern, score how closely two calculated patterns agree, and render a pass/fail agreement table for the regression checks. They are deliberately kept out of the headline public API and imported explicitly by the verification notebooks so those pages stay short and readable.

Classes:

Name	Description
ClosenessMetrics	Closeness scores between a reference and a candidate pattern.
AgreementTolerances	Tolerance bounds for cross-pattern agreement checks.

Functions:

Name	Description
bundled_reference_dir	Return the bundled FullProf reference directory.
load_columned_profile	Load a two-column x y reference profile.
load_fullprof_calc_profile	Load the Bragg-only profile from FullProf calculated + background.
fullprof_version	Return the FullProf version that produced a reference.
fullprof_label	Return a FullProf plot-legend label, e.g. 'FullProf 8.40'.
engine_label	Return the candidate label for a verification comparison.
load_fullprof_sc_f2calc	Extract calculated F² per reflection from a FullProf SC output.
align_reflections	Match two per-reflection maps over their common (h, k, l).
set_reference_as_measured	Use a reference profile as an experiment's measured pattern.
calculate_pattern	Calculate one experiment's pattern with a chosen engine.
set_reference_reflections	Seed a single-crystal experiment with reference reflections.
calculate_reflections	Calculate per-reflection intensities with a chosen engine.
restrict_to_included	Restrict a full-grid array to the experiment's included points.
pattern_closeness	Score how closely a candidate pattern matches a reference.
closeness_annotation	Return in-plot metric lines with pass/fail icons.
assert_patterns_agree	Assert one or more pattern pairs meet their documented expectation.
report_refinement_closeness	Tabulate closeness to a reference before and after refinement.

Classes

ClosenessMetrics(profile_difference_percent, max_deviation_percent, intensity_ratio, correlation) dataclass

Closeness scores between a reference and a candidate pattern.

AgreementTolerances(max_profile_difference_percent=2.5, max_deviation_percent=6.0, min_intensity_ratio=0.99, max_intensity_ratio=1.01, min_correlation=0.999) dataclass

Tolerance bounds for cross-pattern agreement checks.

Defaults expect the calculated areas to agree to about one percent once the FullProf scale is seeded: the integrated-intensity ratio must sit within 1 % of one, the profile difference under 2.5 %, the worst point-wise deviation under 6 %, and the shape correlation above 0.999. Tighten further as multi-platform spreads are characterised.

Functions:

bundled_reference_dir()

Return the bundled FullProf reference directory.

Resolves correctly whether called from the repository root (the script-test working directory) or from the verification notebook directory (the notebook-test working directory). Temporary: the bundled files move to the diffraction data repository later.

Returns:

Type	Description
Path	Directory holding the FullProf reference profiles.

load_columned_profile(project_dir, profile_file, *, skip_rows=1, columns=(0, 1))

Load a two-column x y reference profile.

Parentheses are stripped so values carrying bracketed uncertainties parse cleanly.

Parameters:

Name	Type	Description	Default
project_dir	str	Reference sub-folder name (under the bundled reference directory) holding the FullProf project files.	required
profile_file	str	File name of the column-formatted reference file.	required
skip_rows	int	Number of header rows to skip.	1
columns	tuple[int, int]	Indices of the x and y columns.	(0, 1)

Returns:

Type	Description
tuple[np.ndarray, np.ndarray]	The x and y arrays.

load_fullprof_calc_profile(project_dir, profile_file, background_file, zero_shift)

Load the Bragg-only profile from FullProf calculated + background.

The .prf (preferably the higher-precision Prf=2 IGOR export) holds the calculated profile Icalc on the corrected 2θ grid — the Zero/SyCos/SySin systematic peak-position shift is applied, so the peaks sit at their observed positions. The Ppl=2 .bac holds the real background (the refined polynomial, not the display-shifted Backg column the .prf carries) on the uncorrected 2θ grid. Subtracting the background from Icalc gives the clean Bragg profile, with no pedestal estimate.

Both files are resolved inside the bundled reference directory, so the caller passes only the project sub-folder and the two file names. The .bac 2θ omits the zero shift, so it is realigned onto the profile axis by adding zero_shift (the FullProf Zero) and interpolated onto the profile grid before subtraction (the background is smooth, so interpolation is lossless and Icalc is left exact).

Parameters:

Name	Type	Description	Default
project_dir	str	Reference sub-folder name (under the bundled reference directory) holding the FullProf project files.	required
profile_file	str	File name of the FullProf calculated-profile .prf file.	required
background_file	str	File name of the FullProf .bac background file.	required
zero_shift	float	The FullProf Zero offset (degrees 2θ) that realigns the .bac 2θ onto the profile axis.	required

Returns:

Type	Description
tuple[np.ndarray, np.ndarray]	The corrected 2θ grid and the clean Bragg intensities.

fullprof_version(project_dir, summary_file)

Return the FullProf version that produced a reference.

Reads the version from the banner a FullProf run writes near the top of its .sum (or .out) output — the line ** PROGRAM FullProf.2k (Version 8.40 - Feb2026-ILL JRC) ** — and returns just the version number (for example '8.40'), suited to a plot legend such as f'FullProf {version}'.

Resolved inside the bundled reference directory, so the caller passes the project sub-folder and the summary file name.

Parameters:

Name	Type	Description	Default
project_dir	str	Reference sub-folder name (under the bundled reference directory) holding the FullProf project files.	required
summary_file	str	File name of a FullProf .sum or .out output file.	required

Returns:

Type	Description
str	The FullProf version number (for example '8.40').

Raises:

Type	Description
ValueError	If no version banner is found in the file.

fullprof_label(project_dir, summary_file)

Return a FullProf plot-legend label, e.g. 'FullProf 8.40'.

Convenience wrapper over :func:fullprof_version so verification pages set reference_label in one line rather than repeating the f'FullProf {...}' formatting.

Parameters:

Name	Type	Description	Default
project_dir	str	Reference sub-folder name (under the bundled reference directory) holding the FullProf project files.	required
summary_file	str	File name of a FullProf .sum or .out output file.	required

Returns:

Type	Description
str	The legend label f'FullProf {version}'.

engine_label(engine, note=None)

Return the candidate label for a verification comparison.

Builds the EasyDiffraction-plus-engine candidate string with live versions, for example 'edi 1.2.3 (cryspy 2.4.1)' or, with a note, 'edi 1.2.3 (cryspy 2.4.1, refined)'. The engine is named explicitly (not read from the active calculator) so a stored result keeps the version of the engine that produced it. An unresolvable version renders a visible ? marker rather than being omitted.

Parameters:

Name	Type	Description	Default
engine	str	Calculation engine tag, for example 'cryspy' or 'crysfml'.	required
note	str | None	Optional annotation appended inside the parentheses, for example 'refined' or 'scale only'.	None

Returns:

Type	Description
str	The candidate label string.

Raises:

Type	Description
ValueError	If engine is not in the shared engine-to-package map.

load_fullprof_sc_f2calc(project_dir, out_file)

Extract calculated F² per reflection from a FullProf SC output.

Resolved inside the bundled reference directory, so the caller passes the project sub-folder and the file name.

Reads the integrated-intensity reflection table — the one whose header carries the F2obs and F2cal columns — and returns a mapping from each (h, k, l) to its F2cal. FullProf reports F2cal = scale * Corr * |F|² (scaled and extinction-corrected), a different absolute scale from the engines, so the verification page refines a single scale to bring the two onto a common basis.

Parameters:

Name	Type	Description	Default
project_dir	str	Reference sub-folder name (under the bundled reference directory) holding the FullProf project files.	required
out_file	str	File name of the FullProf single-crystal .out file.	required

Returns:

Type	Description
dict[tuple[int, int, int], float]	{(h, k, l): F2cal} for every tabulated reflection.

align_reflections(reference, candidate)

Match two per-reflection maps over their common (h, k, l).

Parameters:

Name	Type	Description	Default
reference	dict[tuple[int, int, int], float]	Reference values keyed by reflection.	required
candidate	dict[tuple[int, int, int], float]	Candidate values keyed by reflection.	required

Returns:

Type	Description
tuple[np.ndarray, np.ndarray]	Reference and candidate arrays over the shared reflections, in a common order. Ready for :func:pattern_closeness.

set_reference_as_measured(experiment, x, y)

Use a reference profile as an experiment's measured pattern.

Populates the experiment data grid from x and stores y as the measured intensities, so every engine calculates on exactly the reference x grid. Standard uncertainties default to ones. Works for both constant-wavelength and time-of-flight powder experiments.

Parameters:

Name	Type	Description	Default
experiment	object	Powder experiment to populate.	required
x	np.ndarray	Measurement x grid (2θ in degrees or time-of-flight in μs).	required
y	np.ndarray	Reference intensities aligned with x.	required

calculate_pattern(project, experiment, engine)

Calculate one experiment's pattern with a chosen engine.

Selects the calculation engine, refreshes the structure and experiment categories, and returns the calculated intensities on the experiment's x grid.

Parameters:

Name	Type	Description	Default
project	object	Project owning the structures linked to the experiment.	required
experiment	object	Experiment to calculate.	required
engine	str	Calculation engine tag (for example 'cryspy' or 'crysfml').	required

Returns:

Type	Description
np.ndarray	Calculated intensities aligned with the experiment x grid.

set_reference_reflections(experiment, reflections)

Seed a single-crystal experiment with reference reflections.

Creates one reflection per (h, k, l) in reflections and stores the reference values as the measured intensities, so the chosen engine calculates intensity_calc for exactly those reflections. Standard uncertainties default to ones.

Parameters:

Name	Type	Description	Default
experiment	object	Single-crystal experiment to populate.	required
reflections	dict[tuple[int, int, int], float]	Reference values keyed by reflection, for example FullProf F2cal.	required

calculate_reflections(project, experiment, engine)

Calculate per-reflection intensities with a chosen engine.

Selects the calculation engine, refreshes the structure and experiment categories, and returns intensity_calc keyed by (h, k, l).

Parameters:

Name	Type	Description	Default
project	object	Project owning the structures linked to the experiment.	required
experiment	object	Single-crystal experiment to calculate.	required
engine	str	Calculation engine tag (for example 'cryspy').	required

Returns:

Type	Description
dict[tuple[int, int, int], float]	{(h, k, l): intensity_calc} for every reflection.

restrict_to_included(experiment, values)

Restrict a full-grid array to the experiment's included points.

Excluded regions drop points from the calculated/measured arrays the experiment exposes (intensity_calc and friends iterate the included points only), but an external reference loaded onto the full grid still spans every point. This filters such a full-length reference down to the same included points so it can be compared with or plotted against the experiment's arrays.

Arrays that are not full-length (already restricted) and the no-exclusion case are returned unchanged, so the call is safe to apply unconditionally.

Parameters:

Name	Type	Description	Default
experiment	object	Experiment whose intensity category supplies the inclusion mask.	required
values	np.ndarray	Values on the full x grid (for example a FullProf reference).	required

Returns:

Type	Description
np.ndarray	The values restricted to the included points, or unchanged when no restriction applies.

pattern_closeness(reference, candidate)

Score how closely a candidate pattern matches a reference.

Metrics are computed on the absolute intensities, so a page that seeds the FullProf scale sees a real scale comparison: the integrated-intensity ratio is one only when the calculated areas agree, and a scale mismatch widens the profile difference rather than being normalised away. The RMS and maximum differences are expressed as a percentage of the reference (its RMS and its peak), so the tolerances are dataset-independent.

Parameters:

Name	Type	Description	Default
reference	np.ndarray	Reference intensities (for example FullProf or another engine).	required
candidate	np.ndarray	Candidate intensities to compare against the reference.	required

Returns:

Type	Description
ClosenessMetrics	Profile difference (%), maximum point-wise deviation (% of the reference peak), integrated-intensity ratio, and Pearson correlation.

Raises:

Type	Description
ValueError	If the two patterns have different lengths.

closeness_annotation(metrics, tolerances=None)

Return in-plot metric lines with pass/fail icons.

Each line carries a check or cross icon and shows an out-of-tolerance value in red, mirroring the agreement table. The text uses the limited HTML that Plotly annotations support.

Parameters:

Name	Type	Description	Default
metrics	ClosenessMetrics	Scores to annotate.	required
tolerances	AgreementTolerances | None	Tolerance bounds; the documented defaults are used when omitted.	None

Returns:

Type	Description
list[str]	One formatted line per metric.

assert_patterns_agree(comparisons, *, tolerances=None, known_discrepancy=False, reason=None)

Assert one or more pattern pairs meet their documented expectation.

Each comparison is scored with :func:pattern_closeness and checked against tolerances. A single table summarises every metric with a check/cross icon; an out-of-bounds actual value is shown in red.

The assertion is two-sided and driven by known_discrepancy:

• known_discrepancy=False (default) asserts the patterns agree — the page is a regression test, and any out-of-tolerance metric raises AssertionError.
• known_discrepancy=True asserts that every listed comparison still disagrees — the documented known-bad state. The expected out-of-tolerance result passes (the discrepancy stays visible); if any comparison has started agreeing within tolerance it raises AssertionError so the now-fixed comparison fails CI and must be re-gated by hand. A known-bad comparison cannot mask a regression in an expected-good one: keep expected-good comparisons in their own default (gated) call.

Parameters:

Name	Type	Description	Default
comparisons	list[tuple[str, np.ndarray, np.ndarray]]	(label, reference, candidate) triples to compare.	required
tolerances	AgreementTolerances | None	Tolerance bounds; the documented defaults are used when omitted.	None
known_discrepancy	bool	When True, assert the documented disagreement persists instead of asserting agreement (see above).	False
reason	str | None	Required when known_discrepancy=True: a short explanation of the known-bad state, shown on the published page.	None

Returns:

Type	Description
bool	True when the page met its expectation (a default page that agrees, or a known_discrepancy page that still disagrees).

Raises:

Type	Description
ValueError	If known_discrepancy=True is given without a non-empty reason.
AssertionError	If the expectation is not met: a default page whose patterns disagree, or a known_discrepancy call in which any comparison now agrees within tolerance.

report_refinement_closeness(reference, before, after)

Tabulate closeness to a reference before and after refinement.

Scores before and after against the same reference with :func:pattern_closeness and renders a compact before/after table, so a page can show whether refining the disputed parameters moved the candidate closer to the reference. This is a display helper: it renders the table and returns nothing, so a notebook cell ending in this call shows only the table and not an echoed return value. Call :func:pattern_closeness directly for the metrics programmatically.

Parameters:

Name	Type	Description	Default
reference	np.ndarray	Reference intensities (for example FullProf).	required
before	np.ndarray	Candidate intensities before refinement.	required
after	np.ndarray	Candidate intensities after refinement.	required