httk.atomistic.integrations¶

Expose external-library integration bridges.

Submodules¶

Classes¶

`ASEAtoms`	Import ASE `Atoms` and compatible duck-typed objects.
`ASEAtomsProtocol`	Describe the minimal method surface needed to read ASE `Atoms`.
`PymatgenStructure`	Import a pymatgen-compatible structure eagerly.
`PymatgenStructureProtocol`	The three native attributes that identify a pymatgen structure.
`VASPStructure`	Load a VASP POSCAR structure lazily.
`VASPTrajectory`	Read VASP OUTCAR and/or XDATCAR data lazily.

Package Contents¶

class httk.atomistic.integrations.ASEAtoms(obj, **hints)[source]¶

Bases: httk.atomistic.models.structure.backend.StructureBackend

Import ASE Atoms and compatible duck-typed objects.

Conversion is eager because reading the four methods and normalizing their values is real work. The original object remains available through unwrap().

Initial magnetic moments become site moments and nonzero initial charges become charged single-element species. All-zero ASE defaults remain unstated.

Parameters:

obj (ASEAtomsProtocol) – An ASE Atoms object or compatible duck-typed object.
**hints (Any) – Backend-selection hints.

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

Return the exact cell converted from native cell rows.

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

Return the exact reduced coordinates converted from native positions.

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

Return distinct single-element species in first-appearance order.

property species_at_sites: tuple[str, Ellipsis]¶

Return the species name occupying each site.

property site_moments: Any¶

Return per-site moments, or None for absent and all-zero ASE defaults.

unwrap()[source]¶

Return the original Atoms-like object.

class httk.atomistic.integrations.ASEAtomsProtocol[source]¶

Bases: Protocol

Describe the minimal method surface needed to read ASE Atoms.

This is a runtime-checkable, duck-typed protocol. ASE is not required: any object providing these four methods qualifies for ASEAtoms.

get_cell()[source]¶

Return the cell vectors as rows.

Returns:: The native cell rows.
Return type:: Any

get_scaled_positions()[source]¶

Return the reduced positions.

Returns:: One reduced coordinate row per site.
Return type:: Any

get_atomic_numbers()[source]¶

Return one atomic number per site.

Returns:: The atomic numbers.
Return type:: Any

get_pbc()[source]¶

Return one periodicity flag per cell row.

Returns:: The periodicity flags.
Return type:: Any

class httk.atomistic.integrations.PymatgenStructure(obj, **hints)[source]¶

Bases: httk.atomistic.models.structure.backend.StructureBackend

Import a pymatgen-compatible structure eagerly.

Pymatgen properties, site labels, and site properties other than magmom are intentionally discarded because they have no exact httk structure-family counterpart. Pymatgen DummySpecies values with the default zero oxidation state are imported with an unstated charge because pymatgen cannot distinguish that default from an explicitly supplied zero; nonzero dummy oxidation states remain exact charges.

Partial occupancy and its exact Fraction values are retained. An occupancy shortfall becomes an explicit vacancy constituent, which views omit when exporting to pymatgen. The original object remains available through unwrap().

Parameters:

obj (PymatgenStructureProtocol) – A pymatgen Structure object or compatible duck-typed object.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'pymatgen'¶

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

Return the converted cell and periodicity.

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

Return the converted reduced coordinates.

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

Return the imported distinct species and occupancies.

property species_at_sites: tuple[str, Ellipsis]¶

Return the imported species name at each site.

property site_moments: Any¶

Return imported collinear or Cartesian site moments, if present.

property charge: fractions.Fraction | None¶

Return the exact structure charge, or None when unstated.

unwrap()[source]¶

Return the original pymatgen-compatible object.

class httk.atomistic.integrations.PymatgenStructureProtocol[source]¶

Bases: Protocol

The three native attributes that identify a pymatgen structure.

lattice supplies the cell and periodicity, frac_coords supplies the reduced coordinates, and species_and_occu supplies one per-site composition mapping. This small surface is disjoint from ASE Atoms and httk structure objects while allowing pymatgen-compatible duck-typed inputs without importing pymatgen.

lattice: Any¶

frac_coords: Any¶

species_and_occu: Any¶

class httk.atomistic.integrations.VASPStructure(obj, **hints)[source]¶

Bases: httk.atomistic.models.structure.backend.StructureBackend

Load a VASP POSCAR structure lazily.

This backend is explicitly constructed because a generic structure source should not silently claim every POSCAR path.

It is not registered in backend_classes. Constructing it from a view whose unwrapped value is already a VASPStructure returns that backend by identity. The payload’s raw channel preserves the source representation for byte-exact saving.

Parameters:

obj (Any) – A POSCAR path, neutral payload, or serializer-supported source.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'vasp'¶

property payload: collections.abc.Mapping[str, Any]¶

Return the original, loaded, or synthesized neutral POSCAR payload.

property comment: Any¶

Return the POSCAR comment, if present.

property selective_dynamics: Any¶

Return selective-dynamics flags, if present.

resolve()[source]¶

Build and memoize the canonical structure from the POSCAR payload.

Returns:: The resolved unit-cell structure.
Return type:: httk.atomistic.models.structure.unitcell.UnitcellStructure

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

Return the resolved cell.

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

Return the resolved reduced coordinates.

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

Return the resolved distinct species.

property species_at_sites: tuple[str, Ellipsis]¶

Return the resolved species name at each site.

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

Return resolved site moments, or None.

property charge: Any¶

Return the resolved structure charge, if present.

unwrap()[source]¶

Return the original POSCAR source.

class httk.atomistic.integrations.VASPTrajectory(source, **hints)[source]¶

Bases: httk.atomistic.models.trajectory.backend.TrajectoryBackend

Read VASP OUTCAR and/or XDATCAR data lazily.

XDATCAR supplies geometry when present. OUTCAR observables use the per-frame energy_sigma0, parsed as a float, plus temperature and stress_gpa_voigt(). One bounded pass caches those three scalar/6-tuple sequences; frame geometry is never cached.

XDATCAR geometry is preferred when both files are available. Cartesian coordinates are reduced exactly against the frame cell. A mismatch between OUTCAR and XDATCAR frame counts raises an error.

Parameters:

source (Any) – A VASP trajectory path, directory, payload, or VASP-outputs-like object.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'vasp'¶

property nframes: int¶

Return the validated number of frames.

property species: tuple[Any, Ellipsis]¶

Return the composition inferred from POSCAR, XDATCAR, or OUTCAR.

property species_at_sites: tuple[str, Ellipsis]¶

Return the species name at each site.

property reference_frames: None¶

Return None because VASP frames are not bounded references.

frame(i)[source]¶

Read one VASP frame by index.

Parameters:

i (int) – Frame index; negative indexes count from the end.

Returns:

The requested unit-cell structure.

Raises:

IndexError – If the frame index is out of range.
ValueError – If the source has no complete frame geometry.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Stream VASP frame geometry without caching full frames.

Yields:: Unit-cell structures in source order.

property observable_names: tuple[str, Ellipsis]¶

Return available OUTCAR observable names.

observable(name)[source]¶

Return one OUTCAR observable in frame order.

Parameters:: name (str) – Observable name.
Returns:: The observable values.
Raises:: KeyError – If the observable is unavailable.
Return type:: tuple[Any, Ellipsis]

unwrap()[source]¶

Return the original VASP trajectory source.

property source_locator: str | None¶

Return the source path, if one is available.