httk.atomistic.models.species

Submodules

• httk.atomistic.models.species.api
• httk.atomistic.models.species.backend
• httk.atomistic.models.species.like
• httk.atomistic.models.species.plain
• httk.atomistic.models.species.plain_view
• httk.atomistic.models.species.record
• httk.atomistic.models.species.species
• httk.atomistic.models.species.view
• httk.atomistic.models.species.view_base

Attributes

SpeciesLike

Classes

SpeciesAPI	Abstract base class for the canonical single-species interface.
SpeciesBackend	Abstract base class for all backends of single-species data.
PlainSpecies	Backend for a species backed by an OPTIMADE species dict.
PlainSpeciesView	A view presenting an underlying species backend as an OPTIMADE species dict.
Species	A chemical species occupying one or more sites, mirroring the OPTIMADE species object.
SpeciesView	A view presenting an underlying species backend as a Species.
SpeciesViewBase	Abstract base class for all views of single-species data.

Package Contents

class httk.atomistic.models.species.SpeciesAPI

Bases: abc.ABC

Abstract base class for the canonical single-species interface.

It declares the accessors mirroring the OPTIMADE species fields that every species backend produces from its own native representation and every species view builds its presentation from: name, chemical_symbols, concentration, and the optional mass, attached, nattached, and original_name.

property name: str

Abstractmethod:

property chemical_symbols: tuple[str, Ellipsis]

Abstractmethod:

property charges: tuple[fractions.Fraction | None, Ellipsis] | None

Assigned charge numbers for the constituents, or None if unstated.

A None element means the charge of that constituent is unstated; whole- None means no constituent charges are stated. Values use elementary-charge units, for example a formal oxidation state.

Returns:

The constituent charges, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property spins: tuple[fractions.Fraction | None, Ellipsis] | None

Idealized signed spins assigned to the constituents, or None if unstated.

A None element means the spin of that constituent is unstated; whole-None means no constituent spins are stated. This is distinct from a calculated site magnetic moment.

Returns:

The constituent spins, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property labels: tuple[str | None, Ellipsis] | None

Free-form per-constituent labels, or None if unstated.

A None element means that constituent has no stated label; whole-None means no constituent labels are stated.

Returns:

The constituent labels, or None when unstated.

Return type:

tuple[str | None, Ellipsis] | None

property concentration: tuple[fractions.Fraction, Ellipsis]

Abstractmethod:

property is_ordered: bool

Return whether every constituent has unit concentration.

Returns:

True when all concentrations are exactly Fraction(1).

Return type:

bool

property concentration_precision: tuple[fractions.Fraction | None, Ellipsis] | None

Abstractmethod:

property mass: tuple[float, Ellipsis] | None

Abstractmethod:

property attached: tuple[str, Ellipsis] | None

Abstractmethod:

property nattached: tuple[int, Ellipsis] | None

Abstractmethod:

property original_name: str | None

Abstractmethod:

class httk.atomistic.models.species.SpeciesBackend(backend, **hints)

Bases: httk.core.Backend[SpeciesBackend], httk.atomistic.models.species.api.SpeciesAPI

Abstract base class for all backends of single-species data.

Concrete backends carry a native representation and produce the canonical OPTIMADE species accessors declared by SpeciesAPI from it.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]

type httk.atomistic.models.species.SpeciesLike = httk.atomistic.models.species.backend.SpeciesBackend | httk.atomistic.models.species.view_base.SpeciesViewBase | httk.atomistic.models.species.species.Species | dict[str, Any] | str | int

class httk.atomistic.models.species.PlainSpecies(obj, **hints)

Bases: httk.atomistic.models.species.backend.SpeciesBackend

Backend for a species backed by an OPTIMADE species dict.

The native representation is a mapping with the OPTIMADE species fields; the required name/chemical_symbols/concentration are validated conservatively on construction. The accessors read the corresponding fields (optional fields absent from the dict read as None), and unwrap returns the original dict.

Parameters:

• obj (dict[str, Any]) – The species mapping.

• **hints (Any) – Backend-selection hints.

property name: str

Return the species name.

Returns:

The species name.

Return type:

str

property chemical_symbols: tuple[str, Ellipsis]

Return the constituent symbols.

Returns:

The chemical symbols in constituent order.

Return type:

tuple[str, Ellipsis]

property concentration: tuple[fractions.Fraction, Ellipsis]

Return the constituent concentrations.

Returns:

The concentrations in constituent order.

Return type:

tuple[fractions.Fraction, Ellipsis]

property concentration_precision: tuple[fractions.Fraction | None, Ellipsis] | None

Return the concentration precision metadata.

Returns:

Per-constituent precision, or None when unavailable.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property mass: tuple[float, Ellipsis] | None

Return the constituent masses, if stated.

Returns:

The masses, or None when unstated.

Return type:

tuple[float, Ellipsis] | None

property attached: tuple[str, Ellipsis] | None

Return the attached constituent symbols, if stated.

Returns:

The attached symbols, or None when unstated.

Return type:

tuple[str, Ellipsis] | None

property nattached: tuple[int, Ellipsis] | None

Return the attached counts, if stated.

Returns:

The attached counts, or None when unstated.

Return type:

tuple[int, Ellipsis] | None

property original_name: str | None

Return the original source name, if stated.

Returns:

The original name, or None when unstated.

Return type:

str | None

property charges: tuple[fractions.Fraction | None, Ellipsis] | None

Return the constituent charges, if stated.

Returns:

The charges, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property spins: tuple[fractions.Fraction | None, Ellipsis] | None

Return the constituent spins, if stated.

Returns:

The spins, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property labels: tuple[str | None, Ellipsis] | None

Return the constituent labels, if stated.

Returns:

The labels, or None when unstated.

Return type:

tuple[str | None, Ellipsis] | None

unwrap()

Return the original species mapping.

Returns:

The raw mapping.

Return type:

Any

class httk.atomistic.models.species.PlainSpeciesView(obj, **hints)

Bases: httk.atomistic.models.species.view_base.SpeciesViewBase, dict

A view presenting an underlying species backend as an OPTIMADE species dict.

This view is a genuine dict carrying the OPTIMADE species fields (optional fields that are None are omitted; list-valued fields are plain lists). Unlike the immutable-subclass views, a dict is mutable, so this view is a detached copy: mutating it does not affect the underlying backend.

Parameters:

• obj (httk.atomistic.models.species.like.SpeciesLike) – The species-like object to present.

• **hints (Any) – Backend-selection hints.

unwrap()

Return the raw object behind the backend.

Returns:

The unwrapped source object.

Return type:

Any

unview()

Return the presented species as a plain mapping.

Returns:

The detached presentation mapping.

Return type:

dict[str, Any]

class httk.atomistic.models.species.Species(name, chemical_symbols, concentration, mass=None, original_name=None, attached=None, nattached=None, concentration_precision=None, charges=None, spins=None, labels=None)

Bases: httk.atomistic.models.species.backend.SpeciesBackend

A chemical species occupying one or more sites, mirroring the OPTIMADE species object.

A species has a name (unique within a structure; it need not be a chemical symbol), a list of chemical_symbols composing it, and a matching list of concentration values. Each chemical symbol is an element symbol, or one of the pseudo-symbols "X" (unknown) or "vacancy". The optional mass, attached, nattached, and original_name fields carry the remaining OPTIMADE species information; attached and nattached must be given together and share their length.

charges, spins, and labels are optional aligned decorations. An all-None decoration is canonicalized to None. Repeated chemical symbols are accepted only when the complete decoration distinguishes them.

Parameters:

• name (str) – The species name.

• chemical_symbols (collections.abc.Sequence[str]) – The constituent chemical symbols.

• concentration (collections.abc.Sequence[ExactInput]) – The constituent occupancies.

• mass (collections.abc.Sequence[float | int] | None) – The constituent masses, if stated.

• original_name (str | None) – The source name, if stated.

• attached (collections.abc.Sequence[str] | None) – The attached constituent symbols, if stated.

• nattached (collections.abc.Sequence[int] | None) – The counts corresponding to attached, if stated.

• concentration_precision (collections.abc.Sequence[PrecisionInput] | None) – The precision of each occupancy, if stated.

• charges (collections.abc.Sequence[DecorationInput] | None) – The charge decoration, if stated.

• spins (collections.abc.Sequence[DecorationInput] | None) – The spin decoration, if stated.

• labels (collections.abc.Sequence[str | None] | None) – The label decoration, if stated.

name: str = ''

chemical_symbols: tuple[str, Ellipsis] = ()

concentration: tuple[fractions.Fraction, Ellipsis] = ()

mass: tuple[float, Ellipsis] | None = None

original_name: str | None = None

attached: tuple[str, Ellipsis] | None = None

nattached: tuple[int, Ellipsis] | None = None

concentration_precision: tuple[fractions.Fraction | None, Ellipsis] | None = None

charges: tuple[fractions.Fraction | None, Ellipsis] | None = None

Assigned charge numbers for the constituents, or None if unstated.

A None element means the charge of that constituent is unstated; whole- None means no constituent charges are stated. Values use elementary-charge units, for example a formal oxidation state.

Returns:

The constituent charges, or None when unstated.

spins: tuple[fractions.Fraction | None, Ellipsis] | None = None

Idealized signed spins assigned to the constituents, or None if unstated.

A None element means the spin of that constituent is unstated; whole-None means no constituent spins are stated. This is distinct from a calculated site magnetic moment.

Returns:

The constituent spins, or None when unstated.

labels: tuple[str | None, Ellipsis] | None = None

Free-form per-constituent labels, or None if unstated.

A None element means that constituent has no stated label; whole-None means no constituent labels are stated.

Returns:

The constituent labels, or None when unstated.

property normalized: bool

Whether the stated concentration interval contains one.

Returns:

Whether the concentrations are normalized within their precision.

Return type:

bool

property normalization_status: str

Report the concentration normalization status.

Returns:

exact, within_precision, or outside_precision.

Return type:

str

property normalization_diagnostic: Any

Return a structured normalization diagnostic when needed.

Returns:

The diagnostic, or None when the concentrations are normalized.

Return type:

Any

property is_single_element: bool

Whether this species is a single, unattached, real chemical element.

True only for a species composed of exactly one element symbol (not "X" or "vacancy") with no attached particles. Such species are the ones that can be represented as a bare atomic number in the primitive representation.

Returns:

Whether this is a single real element.

Return type:

bool

without_charges()

Return an EXPLICIT lossy projection that drops declared oxidation states.

The other species fields, including spins and labels, are preserved. A species without declared charges is returned by identity.

Returns:

A charge-free species, or this species when already charge-free.

Return type:

Species

classmethod from_object(obj, **hints)

Return a Species from an existing Species, bare symbol or atomic number, or OPTIMADE species dict.

A bare element symbol, "X", or "vacancy" denotes a fully occupied single-symbol species. A bare atomic number denotes the corresponding element.

Parameters:

• obj (Species | dict[str, Any] | str | int) – An existing species, symbol, atomic number, or species mapping.

• **hints (Any) – Backend-selection hints.

Returns:

The canonical species.

Raises:

ValueError – If an atomic number is boolean or the input is invalid.

Return type:

Species

class httk.atomistic.models.species.SpeciesView(obj, **hints)

Bases: httk.atomistic.models.species.view_base.SpeciesViewBase, httk.atomistic.models.species.species.Species

A view presenting an underlying species backend as a Species.

This view is a genuine frozen Species, so it can be passed anywhere a Species is accepted. Its fields are built eagerly from the backend on construction, with full Species validation applied at that point.

Parameters:

• obj (httk.atomistic.models.species.like.SpeciesLike) – The species-like object to present.

• **hints (Any) – Backend-selection hints.

unwrap()

Return the raw object behind the backend.

Returns:

The unwrapped source object.

Return type:

Any

unview()

Return this presentation as standalone species.

Returns:

The exact species representation.

Return type:

httk.atomistic.models.species.species.Species

class httk.atomistic.models.species.SpeciesViewBase

Bases: httk.core.View[httk.atomistic.models.species.backend.SpeciesBackend]

Abstract base class for all views of single-species data.