httk.atomistic.models.species.species

Species definition for httk-atomistic, mirroring the OPTIMADE species entry.

Attributes

ExactInput
PrecisionInput
DecorationInput

Classes

Species

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

Module Contents

type httk.atomistic.models.species.species.ExactInput = fractions.Fraction | int | float | decimal.Decimal | str

type httk.atomistic.models.species.species.PrecisionInput = ExactInput | None

type httk.atomistic.models.species.species.DecorationInput = fractions.Fraction | int | str | None

class httk.atomistic.models.species.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 non-negative concentration values. Concentrations on represented sites must lie in [0, 1]; an unrepresented species may instead carry an aggregate implicit-atom count. 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, ...] = ()

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

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

original_name: str | None = None

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

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

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

charges: tuple[fractions.Fraction | None, ...] | 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, ...] | 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, ...] | 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