core

Modules:

Name	Description
category
category_owner
collection	Lightweight container for guarded items with name-based indexing.
datablock
diagnostic	Diagnostics helpers for logging validation messages.
display_handler	Display metadata for descriptor labels and units.
errors	Project exception types.
factory	Base factory with registration, lookup, and context-dependent defaults.
guard
identity	Identity helpers to build CIF-like hierarchical names.
metadata	Metadata dataclasses for factory-created classes.
posterior	Core posterior summary value objects.
singleton
switchable
units_vocabulary	Validated unit codes for descriptor metadata.
validation	Lightweight runtime validation utilities.
variable

Classes

Functions

Modules

category

Classes:

Name	Description
CategoryItem	Base class for items in a category collection.
CategoryCollection	Handles loop-style category containers (e.g. AtomSites).

Classes

CategoryItem()

Base class for items in a category collection.

Methods:

Name	Description
__str__	Human-readable representation of this component.
from_cif	Populate this item from a CIF block.
help	Print parameters, other properties, and methods.
__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
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

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.

Functions

__str__()

Human-readable representation of this component.

from_cif(block, idx=0)

Populate this item from a CIF block.

help()

Print parameters, other properties, and methods.

__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.

CategoryCollection(item_type)

Handles loop-style category containers (e.g. AtomSites).

Each item is a CategoryItem (component).

Methods:

Name	Description
__str__	Human-readable representation of this component.
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.
__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.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.

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.
scalar_descriptors	list	Collection-level descriptors serialized outside the loop.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all items in this collection.

scalar_descriptors property

Collection-level descriptors serialized outside the loop.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

Functions

__str__()

Human-readable representation of this component.

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.	{}

__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

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

Functions

category_owner

Classes:

Name	Description
CategoryOwner	Base class for objects that own flat CIF-like categories.

Classes

CategoryOwner()

Base class for objects that own flat CIF-like categories.

Methods:

Name	Description
help	Print a summary of public attributes and categories.
__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
categories	list	All category objects owned by this object, sorted by priority.
parameters	list	All parameters from all owned categories.
unique_name	str	Fallback unique name: the class name.
as_cif	str	Return CIF representation (implemented by subclasses).

Attributes

categories property

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

parameters property

All parameters from all owned categories.

unique_name property

Fallback unique name: the class name.

as_cif abstractmethod property

Return CIF representation (implemented by subclasses).

Functions

help()

Print a summary of public attributes and categories.

__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.

collection

Lightweight container for guarded items with name-based indexing.

CollectionBase maintains an ordered list of items and a lazily rebuilt index by the item's identity key. It supports dict-like access for get, set and delete, along with iteration over the items.

Classes:

Name	Description
CollectionBase	A minimal collection with stable iteration and name indexing.

Classes

CollectionBase(item_type)

A minimal collection with stable iteration and name indexing.

Parameters:

Name	Type	Description	Default
item_type	type	Type of items accepted by the collection. Used for validation and tooling; not enforced at runtime here.	required

Methods:

Name	Description
__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.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.
help	Print a summary of public attributes and contained items.
__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
names	list[str | None]	List of all item keys in the collection.
unique_name	str	Fallback unique name: the class name.
parameters	list	Return a list of parameters (implemented by subclasses).
as_cif	str	Return CIF representation (implemented by subclasses).

Attributes

names property

List of all item keys in the collection.

unique_name property

Fallback unique name: the class name.

parameters abstractmethod property

Return a list of parameters (implemented by subclasses).

as_cif abstractmethod property

Return CIF representation (implemented by subclasses).

Functions

__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

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

help()

Print a summary of public attributes and contained items.

__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.

datablock

Classes:

Name	Description
DatablockItem	Base class for items in a datablock collection.
DatablockCollection	Collection of top-level datablocks (e.g. Structures, Experiments).

Classes

DatablockItem()

Base class for items in a datablock collection.

Methods:

Name	Description
__str__	Human-readable representation of this component.
__repr__	Developer-oriented representation of this component.
__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 categories.

Attributes:

Name	Type	Description
unique_name	str | None	Unique name of this datablock item (from identity).
as_cif	str	Return CIF representation of this object.
parameters	list	All parameters from all owned categories.
categories	list	All category objects owned by this object, sorted by priority.

Attributes

unique_name property

Unique name of this datablock item (from identity).

as_cif property

Return CIF representation of this object.

parameters property

All parameters from all owned categories.

categories property

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

Functions

__str__()

Human-readable representation of this component.

__repr__()

Developer-oriented representation of this component.

__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 categories.

DatablockCollection(item_type)

Collection of top-level datablocks (e.g. Structures, Experiments).

Each item is a DatablockItem.

Subclasses provide explicit add_from_* convenience methods that delegate to the corresponding factory classmethods, then call :meth:add with the resulting item.

Methods:

Name	Description
add	Add a pre-built item to the collection.
__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.
keys	Yield keys for all items in insertion order.
values	Yield items in insertion order.
items	Yield (key, item) pairs in insertion order.

Attributes:

Name	Type	Description
unique_name	str | None	Return None; collections have no unique name.
parameters	list	All parameters from all datablocks in this collection.
fittable_parameters	list	All Parameters not blocked by constraints or symmetry.
free_parameters	list	All fittable parameters that are currently marked as free.
as_cif	str	Return CIF representation of this object.
names	list[str | None]	List of all item keys in the collection.

Attributes

unique_name property

Return None; collections have no unique name.

parameters property

All parameters from all datablocks in this collection.

fittable_parameters property

All Parameters not blocked by constraints or symmetry.

free_parameters property

All fittable parameters that are currently marked as free.

as_cif property

Return CIF representation of this object.

names property

List of all item keys in the collection.

Functions

add(item)

Add a pre-built item to the collection.

Parameters:

Name	Type	Description	Default
item	object	A DatablockItem instance (e.g. a Structure or ExperimentBase subclass).	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

keys()

Yield keys for all items in insertion order.

values()

Yield items in insertion order.

items()

Yield (key, item) pairs in insertion order.

diagnostic

Diagnostics helpers for logging validation messages.

This module centralizes human-friendly error and debug logs for attribute validation and configuration checks.

Classes:

Name	Description
Diagnostics	Centralized logger for attribute errors and validation hints.

Classes

Diagnostics

Centralized logger for attribute errors and validation hints.

Methods:

Name	Description
type_override_error	Report an invalid DataTypes override.
readonly_error	Log an attempt to change a read-only attribute.
attr_error	Log unknown attribute access and suggest closest key.
type_mismatch	Log a type mismatch and keep current or default value.
range_mismatch	Log range violation for a numeric value.
choice_mismatch	Log an invalid choice against allowed values.
regex_mismatch	Log a regex mismatch with the expected pattern.
no_value	Log that default will be used due to missing value.
none_value	Log explicit None provided by a user.
none_value_skip_range	Log that range validation is skipped due to None.
validated	Log that a value passed a validation stage.

Functions

type_override_error(cls_name, expected, got) staticmethod

Report an invalid DataTypes override.

Used when descriptor and AttributeSpec types conflict.

readonly_error(name, key=None) staticmethod

Log an attempt to change a read-only attribute.

attr_error(name, key, allowed, label='Allowed') staticmethod

Log unknown attribute access and suggest closest key.

type_mismatch(name, value, expected_type, current=None, default=None) staticmethod

Log a type mismatch and keep current or default value.

range_mismatch(name, value, ge, le, current=None, default=None) staticmethod

Log range violation for a numeric value.

choice_mismatch(name, value, allowed, current=None, default=None) staticmethod

Log an invalid choice against allowed values.

regex_mismatch(name, value, pattern, current=None, default=None) staticmethod

Log a regex mismatch with the expected pattern.

no_value(name, default) staticmethod

Log that default will be used due to missing value.

none_value(name) staticmethod

Log explicit None provided by a user.

none_value_skip_range(name) staticmethod

Log that range validation is skipped due to None.

validated(name, value, stage=None) staticmethod

Log that a value passed a validation stage.

display_handler

Display metadata for descriptor labels and units.

Classes:

Name	Description
DisplayHandler	Display metadata for descriptor labels and units.

Classes

DisplayHandler(display_name=None, display_units=None, latex_name=None, latex_units=None) dataclass

Display metadata for descriptor labels and units.

Attributes:

Name	Type	Description
display_name	str | None, default=None	Human-readable label for HTML and GUI contexts.
display_units	str | None, default=None	Human-readable units for HTML and GUI contexts.
latex_name	str | None, default=None	TeX label for LaTeX report contexts.
latex_units	str | None, default=None	TeX units for LaTeX report contexts.

errors

Project exception types.

Classes:

Name	Description
EasyDiffractionError	Base class for EasyDiffraction exceptions.
EasyDiffractionWriterError	Raised when EasyDiffraction cannot write a valid file.

Classes

EasyDiffractionError

Base class for EasyDiffraction exceptions.

EasyDiffractionWriterError

Raised when EasyDiffraction cannot write a valid file.

factory

Base factory with registration, lookup, and context-dependent defaults.

Concrete factories inherit from FactoryBase and only need to define _default_rules.

Classes:

Name	Description
FactoryBase	Shared base for all factories.

Classes

FactoryBase

Shared base for all factories.

Subclasses must set:

• _default_rules -- mapping of frozenset conditions to tag strings. Use frozenset(): 'tag' for a universal default.

The __init_subclass__ hook ensures every subclass gets its own independent _registry list.

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.

Functions

__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

Functions

guard

Classes:

Name	Description
GuardedBase	Base class enforcing controlled attribute access and linkage.

Classes

GuardedBase()

Base class enforcing controlled attribute access and linkage.

Methods:

Name	Description
__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.
help	Print a summary of public properties and methods.

Attributes:

Name	Type	Description
unique_name	str	Fallback unique name: the class name.
parameters	list	Return a list of parameters (implemented by subclasses).
as_cif	str	Return CIF representation (implemented by subclasses).

Attributes

unique_name property

Fallback unique name: the class name.

parameters abstractmethod property

Return a list of parameters (implemented by subclasses).

as_cif abstractmethod property

Return CIF representation (implemented by subclasses).

Functions

__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.

help()

Print a summary of public properties and methods.

identity

Identity helpers to build CIF-like hierarchical names.

Used by containers and items to expose datablock/category/entry names without tight coupling.

Classes:

Name	Description
Identity	Resolve datablock/category/entry relationships lazily.

Classes

Identity(*, owner, datablock_entry=None, category_code=None, category_entry=None)

Resolve datablock/category/entry relationships lazily.

Attributes:

Name	Type	Description
datablock_entry_name	str | None	Datablock entry name or None if not set.
category_code	str | None	Category code like 'atom_site' or 'background'.
category_entry_name	str | None	Category entry name or None if not set.

Attributes

datablock_entry_name property writable

Datablock entry name or None if not set.

category_code property writable

Category code like 'atom_site' or 'background'.

category_entry_name property writable

Category entry name or None if not set.

metadata

Metadata dataclasses for factory-created classes.

Three frozen dataclasses describe a concrete class:

• TypeInfo — stable tag and human-readable description. - Compatibility — experimental conditions (multiple fields). - CalculatorSupport — which calculation engines can handle it.

Classes:

Name	Description
TypeInfo	Stable identity and description for a factory-created class.
Compatibility	Experimental conditions under which a class can be used.
CalculatorSupport	Which calculation engines can handle this class.

Classes

TypeInfo(tag, description='') dataclass

Stable identity and description for a factory-created class.

Attributes:

Name	Type	Description
tag	str	Short, stable string identifier used for serialization, user-facing selection, and factory lookup. Must be unique within a factory's registry. Examples: 'line-segment', 'pseudo-voigt', 'cryspy'.
description	str, default=''	One-line human-readable explanation. Used in show_supported() tables and documentation.

Compatibility(sample_form=frozenset(), scattering_type=frozenset(), beam_mode=frozenset(), radiation_probe=frozenset()) dataclass

Experimental conditions under which a class can be used.

Each field is a frozenset of enum values representing the set of supported values for that axis. An empty frozenset means "compatible with any value of this axis" (i.e. no restriction).

Methods:

Name	Description
supports	Check if this compatibility matches the given conditions.

Functions

supports(sample_form=None, scattering_type=None, beam_mode=None, radiation_probe=None)

Check if this compatibility matches the given conditions.

Each argument is an optional enum member. Returns True if every provided value is in the corresponding frozenset (or the frozenset is empty, meaning any).

Example::

compat.supports( scattering_type=ScatteringTypeEnum.BRAGG, beam_mode=BeamModeEnum.CONSTANT_WAVELENGTH, )

CalculatorSupport(calculators=frozenset()) dataclass

Which calculation engines can handle this class.

Attributes:

Name	Type	Description
calculators	frozenset, default=frozenset()	Frozenset of CalculatorEnum values. Empty means "any calculator" (no restriction).

Methods:

Name	Description
supports	Check if a specific calculator can handle this class.

Functions

supports(calculator)

Check if a specific calculator can handle this class.

Parameters:

Name	Type	Description	Default
calculator	object	A CalculatorEnum value.	required

Returns:

Type	Description
bool	True if the calculator is in the set, or if the set is empty (meaning any calculator is accepted).

posterior

Core posterior summary value objects.

Classes:

Name	Description
PosteriorParameterSummary	Posterior summary statistics for one fitted parameter.

Classes

PosteriorParameterSummary(unique_name, display_name, best_sample_value, median, standard_deviation, interval_68, interval_95, ess_bulk=None, r_hat=None) dataclass

Posterior summary statistics for one fitted parameter.

Attributes:

Name	Type	Description
unique_name	str	Unique parameter name used across EasyDiffraction.
display_name	str	Human-readable label used in plots and tables.
best_sample_value	float	Highest-posterior sampled parameter value.
median	float	Posterior median value.
standard_deviation	float	Posterior standard deviation.
interval_68	tuple[float, float]	Central 68% interval.
interval_95	tuple[float, float]	Central 95% interval.
ess_bulk	float | None, default=None	Bulk effective sample size when available.
r_hat	float | None, default=None	Rank-normalized split-\(\hat{R}\) when available.

singleton

Classes:

Name	Description
SingletonBase	Base class to implement Singleton pattern.
ConstraintsHandler	Manage parameter constraints using aliases and expressions.

Classes

SingletonBase

Base class to implement Singleton pattern.

Ensures only one shared instance of a class is ever created. Useful for managing shared state across the library.

Methods:

Name	Description
get	Return the shared instance, creating it if needed.

Functions

get() classmethod

Return the shared instance, creating it if needed.

ConstraintsHandler()

Manage parameter constraints using aliases and expressions.

Uses the asteval interpreter for safe evaluation of mathematical expressions. Constraints are defined as: lhs_alias = expression(rhs_aliases).

Methods:

Name	Description
set_aliases	Set the alias map (name → alias wrapper).
set_constraints	Set the constraints and triggers parsing into internal format.
apply	Evaluate constraints and apply them to dependent parameters.
get	Return the shared instance, creating it if needed.

Functions

set_aliases(aliases)

Set the alias map (name → alias wrapper).

Called when user registers parameter aliases like: alias='biso_La', param=model.atom_sites['La'].adp_iso

set_constraints(constraints)

Set the constraints and triggers parsing into internal format.

Called when user registers expressions like: lhs_alias='occ_Ba', rhs_expr='1 - occ_La'

apply()

Evaluate constraints and apply them to dependent parameters.

For each constraint: - Evaluate RHS using current values of aliased parameters - Locate the dependent parameter via direct alias reference - Update its value and mark it as user constrained

get() classmethod

Return the shared instance, creating it if needed.

switchable

Classes:

Name	Description
SwitchableCategoryBase	Behavior-only mixin for category-owned selectors.

Classes

SwitchableCategoryBase

Behavior-only mixin for category-owned selectors.

Methods:

Name	Description
show_supported	Print supported types and mark the active one.

Attributes:

Name	Type	Description
type	str	Active factory tag for this category.

Attributes

type property writable

Active factory tag for this category.

Functions

show_supported()

Print supported types and mark the active one.

Functions

units_vocabulary

Validated unit codes for descriptor metadata.

Functions:

Name	Description
normalize_units_code	Return the canonical units code for a descriptor.
validate_units_code	Validate one descriptor units code.

Functions

normalize_units_code(code)

Return the canonical units code for a descriptor.

Parameters:

Name	Type	Description	Default
code	str	Units code. Empty strings are treated as 'none'.	required

Returns:

Type	Description
str	Canonical units code.

validate_units_code(code)

Validate one descriptor units code.

Parameters:

Name	Type	Description	Default
code	str	Units code to validate.	required

Raises:

Type	Description
ValueError	If code is not a known units code.

validation

Lightweight runtime validation utilities.

Provides DataTypes, type/content validators, and AttributeSpec used by descriptors and parameters. Only documentation was added here.

Classes:

Name	Description
DataTypeHints	Type hint aliases for numeric, string, and boolean types.
DataTypes	Enumeration of supported data types for descriptors.
ValidationStage	Phases of validation for diagnostic logging.
ValidatorBase	Abstract base class for all validators.
TypeValidator	Ensure a value is of the expected data type.
RangeValidator	Ensure a numeric value lies within [ge, le] and (gt, lt).
MembershipValidator	Ensure that a value is among allowed choices.
PermissiveMembershipValidator	Membership validator accepting any value when choices are empty.
RegexValidator	Ensure that a string matches a given regular expression.
AttributeSpec	Hold metadata and validators for a single attribute.

Classes

DataTypeHints

Type hint aliases for numeric, string, and boolean types.

DataTypes

Enumeration of supported data types for descriptors.

Methods:

Name	Description
__str__	Return the lowercase name of the data type.

Attributes:

Name	Type	Description
expected_type	tuple	Convenience alias for tuple of allowed Python types.

Attributes

expected_type property

Convenience alias for tuple of allowed Python types.

Functions

__str__()

Return the lowercase name of the data type.

ValidationStage

Phases of validation for diagnostic logging.

Methods:

Name	Description
__str__	Return the lowercase name of the validation stage.

Functions

__str__()

Return the lowercase name of the validation stage.

ValidatorBase

Abstract base class for all validators.

Methods:

Name	Description
validated	Return a validated value or fallback.

Functions

validated(value, name, default=None, current=None) abstractmethod

Return a validated value or fallback.

Subclasses must implement this method.

TypeValidator(expected_type)

Ensure a value is of the expected data type.

Methods:

Name	Description
validated	Validate type and return value or fallback.

Functions

validated(value, name, default=None, current=None, *, allow_none=False)

Validate type and return value or fallback.

If allow_none is True, None bypasses content checks.

RangeValidator(*, ge=-np.inf, le=np.inf, gt=-np.inf, lt=np.inf)

Ensure a numeric value lies within [ge, le] and (gt, lt).

Methods:

Name	Description
validated	Validate range and return value or fallback.

Functions

validated(value, name, default=None, current=None)

Validate range and return value or fallback.

MembershipValidator(allowed)

Ensure that a value is among allowed choices.

allowed may be an iterable or a callable returning a collection.

Methods:

Name	Description
validated	Validate membership and return value or fallback.

Functions

validated(value, name, default=None, current=None)

Validate membership and return value or fallback.

PermissiveMembershipValidator(allowed)

Membership validator accepting any value when choices are empty.

Used where the allowed set is derived dynamically and may legitimately be empty (for example a Wyckoff letter under an untabulated space group, or before a parent context is available): an empty allowed set stores the value verbatim instead of rejecting it. A non-empty allowed set validates membership as usual.

Methods:

Name	Description
validated	Accept any value when allowed is empty, else check membership.

Functions

validated(value, name, default=None, current=None)

Accept any value when allowed is empty, else check membership.

RegexValidator(pattern)

Ensure that a string matches a given regular expression.

Methods:

Name	Description
validated	Validate regex and return value or fallback.

Functions

validated(value, name, default=None, current=None)

Validate regex and return value or fallback.

AttributeSpec(*, default=_MISSING_DEFAULT, data_type=None, validator=None, allow_none=False)

Hold metadata and validators for a single attribute.

Methods:

Name	Description
default_value	Return the resolved static default value.
validated	Validate through type and content validators.

Functions

default_value()

Return the resolved static default value.

validated(value, name, current=None)

Validate through type and content validators.

Returns validated value, possibly default or current if errors occur. None may short-circuit further checks when allowed.

variable

Classes:

Name	Description
GenericDescriptorBase	Base class for all parameter-like descriptors.
GenericStringDescriptor	Base descriptor that constrains values to strings.
GenericBoolDescriptor	Base descriptor that constrains values to booleans.
GenericNumericDescriptor	Base descriptor that constrains values to numbers.
GenericIntegerDescriptor	Base descriptor that constrains values to integers.
GenericParameter	Numeric descriptor extended with fitting-related attributes.
StringDescriptor	String descriptor bound to a CIF handler.
EnumDescriptor	String descriptor bound to a closed (str, Enum) value set.
BoolDescriptor	Boolean descriptor bound to a CIF handler.
NumericDescriptor	Numeric descriptor bound to a CIF handler.
IntegerDescriptor	Integer descriptor bound to a CIF handler.
Parameter	Fittable parameter bound to a CIF handler.

Classes

GenericDescriptorBase(*, value_spec, name, description=None, display_handler=None)

Base class for all parameter-like descriptors.

A descriptor encapsulates a typed value with validation, human-readable name/description and a globally unique identifier that is stable across the session. Concrete subclasses specialize the expected data type and can extend the public API with additional behavior (e.g. units).

Parameters:

Name	Type	Description	Default
value_spec	AttributeSpec	Validation specification for the value.	required
name	str	Local name of the descriptor within its category.	required
description	str | None	Optional human-readable description.	None
display_handler	DisplayHandler | None	Optional labels and units for display contexts.	None

Methods:

Name	Description
__str__	Return the string representation of this descriptor.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.
__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 properties and methods.

Attributes:

Name	Type	Description
name	str	Local name of the descriptor (without category/datablock).
unique_name	str	Fully qualified name: datablock, category and entry.
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.

Attributes

name property

Local name of the descriptor (without category/datablock).

unique_name property

Fully qualified name: datablock, category and entry.

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

Functions

__str__()

Return the string representation of this descriptor.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

__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 properties and methods.

GenericStringDescriptor(**kwargs)

Base descriptor that constrains values to strings.

Methods:

Name	Description
__str__	Return the string representation of this descriptor.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

__str__()

Return the string representation of this descriptor.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

GenericBoolDescriptor(*, value_spec=None, **kwargs)

Base descriptor that constrains values to booleans.

Methods:

Name	Description
__str__	Return the string representation of this descriptor.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

__str__()

Return the string representation of this descriptor.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

GenericNumericDescriptor(*, units='', **kwargs)

Base descriptor that constrains values to numbers.

Methods:

Name	Description
__str__	Return the string representation including units.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
units	str	Units associated with the numeric value, if any.
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

units property

Units associated with the numeric value, if any.

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

__str__()

Return the string representation including units.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

GenericIntegerDescriptor(*, units='', **kwargs)

Base descriptor that constrains values to integers.

Methods:

Name	Description
__str__	Return the string representation including units.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
units	str	Units associated with the numeric value, if any.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

units property

Units associated with the numeric value, if any.

Functions

__str__()

Return the string representation including units.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

GenericParameter(**kwargs)

Numeric descriptor extended with fitting-related attributes.

Adds standard attributes used by minimizers: "free" flag, uncertainty, bounds and an optional starting value. Subclasses can integrate with specific backends while preserving this interface.

Methods:

Name	Description
__str__	Return string representation with uncertainty and free.
set_fit_bounds_from_uncertainty	Set fit bounds from the current standard uncertainty.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
user_constrained	bool	Whether this parameter is part of a constraint expression.
free	bool	Whether this parameter is currently varied during fitting.
symmetry_constrained	bool	Return whether symmetry constrains this parameter.
uncertainty	float | None	Estimated standard uncertainty of the fitted value.
posterior	PosteriorParameterSummary | None	Posterior summary from a Bayesian fit, if available.
fit_min	float	Lower fitting bound.
fit_max	float	Upper fitting bound.
fit_bounds_uncertainty_multiplier	float | None	Multiplier used for uncertainty-derived fit bounds, if known.
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
units	str	Units associated with the numeric value, if any.

Attributes

user_constrained property

Whether this parameter is part of a constraint expression.

free property writable

Whether this parameter is currently varied during fitting.

symmetry_constrained property

Return whether symmetry constrains this parameter.

uncertainty property writable

Estimated standard uncertainty of the fitted value.

posterior property

Posterior summary from a Bayesian fit, if available.

fit_min property writable

Lower fitting bound.

fit_max property writable

Upper fitting bound.

fit_bounds_uncertainty_multiplier property

Multiplier used for uncertainty-derived fit bounds, if known.

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

units property

Units associated with the numeric value, if any.

Functions

__str__()

Return string representation with uncertainty and free.

set_fit_bounds_from_uncertainty(multiplier=DEFAULT_FIT_BOUNDS_MULTIPLIER, *, clip_to_limits=True)

Set fit bounds from the current standard uncertainty.

Parameters:

Name	Type	Description	Default
multiplier	float	Positive finite factor applied symmetrically to the current parameter uncertainty.	DEFAULT_FIT_BOUNDS_MULTIPLIER
clip_to_limits	bool	Whether to clip the resolved fit bounds to the parameter's physical lower and upper limits when those are finite.	True

Raises:

Type	Description
ValueError	If the current value, uncertainty, or multiplier is missing, invalid, or produces non-increasing bounds.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

StringDescriptor(*, cif_handler, **kwargs)

String descriptor bound to a CIF handler.

Parameters:

Name	Type	Description	Default
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
**kwargs	object	Forwarded to GenericStringDescriptor.	{}

Methods:

Name	Description
__str__	Return the string representation of this descriptor.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

__str__()

Return the string representation of this descriptor.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

EnumDescriptor(*, name, enum, cif_handler, description=None, default=None, display_handler=None)

String descriptor bound to a closed (str, Enum) value set.

Derives validation and the default from enum and exposes show_supported() listing the members with the active one marked, matching the switchable-category table (value-selector-discovery ADR).

Parameters:

Name	Type	Description	Default
name	str	Local name of the descriptor within its category.	required
enum	type[StrEnum]	The (str, Enum) class whose members are the allowed values.	required
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
description	str | None	Optional human-readable description.	None
default	str | None	Default value; falls back to enum.default() when omitted.	None
display_handler	DisplayHandler | None	Optional labels and units for display contexts.	None

Methods:

Name	Description
show_supported	List the accepted values, marking the active one.
__str__	Return the string representation of this descriptor.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
enum	type[StrEnum]	Return the (str, Enum) class backing this selector.
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

enum property

Return the (str, Enum) class backing this selector.

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

show_supported()

List the accepted values, marking the active one.

__str__()

Return the string representation of this descriptor.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

BoolDescriptor(*, cif_handler, **kwargs)

Boolean descriptor bound to a CIF handler.

Parameters:

Name	Type	Description	Default
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
**kwargs	object	Forwarded to GenericBoolDescriptor.	{}

Methods:

Name	Description
__str__	Return the string representation of this descriptor.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

Functions

__str__()

Return the string representation of this descriptor.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

NumericDescriptor(*, cif_handler, **kwargs)

Numeric descriptor bound to a CIF handler.

Parameters:

Name	Type	Description	Default
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
**kwargs	object	Forwarded to GenericNumericDescriptor.	{}

Methods:

Name	Description
__str__	Return the string representation including units.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
units	str	Units associated with the numeric value, if any.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

units property

Units associated with the numeric value, if any.

Functions

__str__()

Return the string representation including units.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

IntegerDescriptor(*, cif_handler, **kwargs)

Integer descriptor bound to a CIF handler.

Parameters:

Name	Type	Description	Default
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
**kwargs	object	Forwarded to GenericIntegerDescriptor.	{}

Methods:

Name	Description
__str__	Return the string representation including units.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
units	str	Units associated with the numeric value, if any.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

units property

Units associated with the numeric value, if any.

Functions

__str__()

Return the string representation including units.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

Parameter(*, cif_handler, **kwargs)

Fittable parameter bound to a CIF handler.

Parameters:

Name	Type	Description	Default
cif_handler	CifHandler	Object that tracks CIF identifiers.	required
**kwargs	object	Forwarded to GenericParameter.	{}

Methods:

Name	Description
__str__	Return string representation with uncertainty and free.
__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 properties and methods.
resolve_display_name	Return the display label for the requested context.
resolve_display_units	Return the display units for the requested context.
from_cif	Populate this parameter from a CIF block.
set_fit_bounds_from_uncertainty	Set fit bounds from the current standard uncertainty.

Attributes:

Name	Type	Description
unique_name	str	Fully qualified name: datablock, category and entry.
parameters	list[GenericDescriptorBase]	Return a flat list of parameters contained by this object.
as_cif	str	Serialize this descriptor to a CIF-formatted string.
name	str	Local name of the descriptor (without category/datablock).
value	object	Current validated value.
description	str | None	Optional human-readable description.
display_handler	DisplayHandler | None	Optional labels and units for display contexts.
units	str	Units associated with the numeric value, if any.
user_constrained	bool	Whether this parameter is part of a constraint expression.
free	bool	Whether this parameter is currently varied during fitting.
symmetry_constrained	bool	Return whether symmetry constrains this parameter.
uncertainty	float | None	Estimated standard uncertainty of the fitted value.
posterior	PosteriorParameterSummary | None	Posterior summary from a Bayesian fit, if available.
fit_min	float	Lower fitting bound.
fit_max	float	Upper fitting bound.
fit_bounds_uncertainty_multiplier	float | None	Multiplier used for uncertainty-derived fit bounds, if known.

Attributes

unique_name property

Fully qualified name: datablock, category and entry.

parameters property

Return a flat list of parameters contained by this object.

For a single descriptor, it returns a one-element list with itself. Composite objects override this to flatten nested structures.

as_cif property

Serialize this descriptor to a CIF-formatted string.

name property

Local name of the descriptor (without category/datablock).

value property writable

Current validated value.

description property

Optional human-readable description.

display_handler property

Optional labels and units for display contexts.

units property

Units associated with the numeric value, if any.

user_constrained property

Whether this parameter is part of a constraint expression.

free property writable

Whether this parameter is currently varied during fitting.

symmetry_constrained property

Return whether symmetry constrains this parameter.

uncertainty property writable

Estimated standard uncertainty of the fitted value.

posterior property

Posterior summary from a Bayesian fit, if available.

fit_min property writable

Lower fitting bound.

fit_max property writable

Upper fitting bound.

fit_bounds_uncertainty_multiplier property

Multiplier used for uncertainty-derived fit bounds, if known.

Functions

__str__()

Return string representation with uncertainty and free.

__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 properties and methods.

resolve_display_name(context)

Return the display label for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display label.

resolve_display_units(context)

Return the display units for the requested context.

Parameters:

Name	Type	Description	Default
context	str	One of 'latex', 'html', or 'gui'.	required

Returns:

Type	Description
str	Resolved display units.

from_cif(block, idx=0)

Populate this parameter from a CIF block.

set_fit_bounds_from_uncertainty(multiplier=DEFAULT_FIT_BOUNDS_MULTIPLIER, *, clip_to_limits=True)

Set fit bounds from the current standard uncertainty.

Parameters:

Name	Type	Description	Default
multiplier	float	Positive finite factor applied symmetrically to the current parameter uncertainty.	DEFAULT_FIT_BOUNDS_MULTIPLIER
clip_to_limits	bool	Whether to clip the resolved fit bounds to the parameter's physical lower and upper limits when those are finite.	True

Raises:

Type	Description
ValueError	If the current value, uncertainty, or multiplier is missing, invalid, or produces non-increasing bounds.

Functions