httk.atomistic.models.structure.api

The minimal canonical structure interface for httk-atomistic.

Classes

StructureAPI

Define the canonical structure interface.

Module Contents

class httk.atomistic.models.structure.api.StructureAPI

Bases: abc.ABC

Define the canonical structure interface.

It declares the Unitcell quartet that every structure backend produces from its own native representation and every structure view builds its presentation from: cell, sites, species, and species_at_sites. This is the single interchange format; there is no pairwise conversion between backends.

property cell: httk.atomistic.models.cell.cell.Cell

Abstractmethod:

Expose the structure’s cell.

property sites: httk.atomistic.models.sites.sites.Sites

Abstractmethod:

Expose the structure’s site coordinates.

property species: tuple[httk.atomistic.models.species.species.Species, Ellipsis]

Abstractmethod:

Expose the structure’s distinct species.

property species_at_sites: tuple[str, Ellipsis]

Abstractmethod:

Expose the species occupying each site.

property charge: fractions.Fraction | None

Expose the explicitly assigned net charge of the cell content.

None means unstated and is never derived from the species; it is distinct from an explicit zero.

Returns:

The assigned charge, or None when it is unstated.

Return type:

fractions.Fraction | None

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose optional per-site magnetic moments in sites order.

None means “nothing stated”, not “zero moments”.

Returns:

The site moments, or None when they are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

without_charges()

Return an EXPLICIT lossy projection that drops declared oxidation states.

The canonical structure components and semantic metadata are preserved. A structure without species charges is returned by identity; charged structures are rebuilt in the canonical unit-cell family.

Returns:

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

Return type:

StructureAPI

property composition: httk.atomistic.models.formula.composition.Composition

Project the canonical components into an elemental composition.

property elements: tuple[str, Ellipsis] | None

Expose the complete composition’s element symbols, if available.

property nelements: int | None

Expose the complete composition’s element count, if available.

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

Expose complete composition ratios, if available.

property chemical_formula_reduced: str | None

Expose the reduced formula derived from a complete composition.

property chemical_formula_anonymous: str | None

Expose the anonymous formula derived from a complete composition.

property chemical_formula_descriptive: str | None

Expose an explicitly supplied descriptive formula, when available.

property chemical_formula_hill: str | None

Expose an explicitly supplied Hill formula, when available.

property dimension_types: tuple[int, Ellipsis] | None

Expose cell periodicity as OPTIMADE dimension flags.

property nperiodic_dimensions: int | None

Expose the number of periodic cell directions.

property nsites: int | None

Expose the number of canonical site-coordinate rows.

multiplicities()

Return how many unit-cell sites each represented site contributes.

The canonical structure interface presents a unit cell, so each row contributes once. Symmetry-reduced representations override this with their orbit counts.

Returns:

One multiplicity per represented site.

Return type:

tuple[int, Ellipsis]

property structure_features: tuple[str, Ellipsis] | None

Expose composition-related features derived from canonical components.