httk.atomistic.models.trajectory

Expose trajectory models and views.

Submodules

• httk.atomistic.models.trajectory.api
• httk.atomistic.models.trajectory.backend
• httk.atomistic.models.trajectory.jsonl
• httk.atomistic.models.trajectory.like
• httk.atomistic.models.trajectory.plain
• httk.atomistic.models.trajectory.record
• httk.atomistic.models.trajectory.trajectory
• httk.atomistic.models.trajectory.view

Attributes

TrajectoryLike

Classes

TrajectoryAPI	Define the common, frame-oriented trajectory interface.
TrajectoryBackend	Define the backend base for all trajectory representations.
JsonlTrajectory	Stream a neutral httk-trajectory-jsonl payload or path lazily.
PlainTrajectory	Represent a mapping whose structure properties have a frame axis.
Trajectory	Store an immutable trajectory in the native backend.
TrajectoryView	Present any trajectory backend through the canonical trajectory API.

Package Contents

class httk.atomistic.models.trajectory.TrajectoryAPI

Bases: abc.ABC

Define the common, frame-oriented trajectory interface.

A trajectory has one constant composition for all frames. Trajectories whose number or identity of sites changes are intentionally outside this interface.

property nframes: int

Count frames by streaming them in O(n) time.

Each call requires frames() to provide a fresh traversal; a one-shot backend must override this default or cache its frames. Random-access backends override this default.

Returns:

The number of frames.

Return type:

int

frame(i)

Stream to and return one frame in O(n) time.

Each call requires frames() to provide a fresh traversal; a one-shot backend must override this default or cache its frames. Random-access backends override this default.

Parameters:

i (int) – Frame index.

Returns:

The requested UnitcellStructure.

Raises:

• IndexError – If i is before the first frame or past the end.

• TypeError – If i is not an integer.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

abstractmethod frames()

Iterate over the frames with a fresh traversal on every call.

A one-shot backend must override the streaming defaults or cache its frames.

Returns:

A fresh iterator of unit-cell structures.

Return type:

collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

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

Abstractmethod:

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]

Abstractmethod:

Return the constant species name at each site.

property reference_frames: tuple[int, Ellipsis] | None

Return stored reference-frame indexes, or None.

property observable_names: tuple[str, Ellipsis]

Return the names of available per-frame observables.

observable(name)

Return one observable’s values by frame.

Parameters:

name (str) – Observable name.

Returns:

The observable values in frame order.

Raises:

KeyError – If the observable is unavailable.

Return type:

tuple[Any, Ellipsis]

class httk.atomistic.models.trajectory.TrajectoryBackend(backend, **hints)

Bases: httk.core.Backend[TrajectoryBackend], httk.atomistic.models.trajectory.api.TrajectoryAPI

Define the backend base for all trajectory representations.

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

class httk.atomistic.models.trajectory.JsonlTrajectory(source, **hints)

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

Stream a neutral httk-trajectory-jsonl payload or path lazily.

Frame data remains in the JSONL container and is read as requested.

Parameters:

• source (Any) – A JSONL payload or path to one.

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

kind: ClassVar[str] = 'jsonl'

property nframes: int

Return the number of frames in the container.

property header: collections.abc.Mapping[str, Any]

Return the neutral JSONL header mapping.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]

Return the constant species name at each site.

property reference_frames: tuple[int, Ellipsis] | None

Return stored reference-frame indexes, or None.

property observable_names: tuple[str, Ellipsis]

Return the names of available per-frame observables.

observable(name)

Read one observable’s values in frame order.

Parameters:

name (str) – Observable name.

Returns:

The observable values.

Raises:

KeyError – If the observable is unavailable.

Return type:

tuple[Any, Ellipsis]

frame(i)

Read one frame from the JSONL container.

Parameters:

i (int) – Frame index.

Returns:

The requested unit-cell structure.

Raises:

IndexError – If the frame index is out of range.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()

Stream all frames from the JSONL container.

Yields:

Unit-cell structures in container order.

unwrap()

Return the original JSONL source payload or path.

property source_locator: str | None

Return the JSONL path, if the source has one.

type httk.atomistic.models.trajectory.TrajectoryLike = TrajectoryBackend | TrajectoryView | Trajectory | PlainTrajectory | Mapping[str, Any]

class httk.atomistic.models.trajectory.PlainTrajectory(obj, **hints)

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

Represent a mapping whose structure properties have a frame axis.

A compact constant property is represented by a one-element leading axis, e.g. nelements=[2] for any number of frames. Only properties declaring constant on that axis accept this compact form.

Parameters:

• obj (collections.abc.Mapping[str, Any]) – A trajectory property mapping.

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

kind: ClassVar[str] = 'plain'

frame(i)

Return one frame from the property mapping.

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.

• KeyError – If a required trajectory property is absent.

• TypeError – If the frame index is not an integer.

• ValueError – If the frame cannot be represented as a structure.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()

Iterate over all frames in source order.

Returns:

An iterator of unit-cell structures.

Return type:

collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property nframes: int

Return the number of frames.

property reference_frames: tuple[int, Ellipsis] | None

Return normalized reference-frame indexes, or None.

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

Return the constant distinct species from the first frame.

property species_at_sites: tuple[str, Ellipsis]

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]

Return names outside the recognized trajectory and structure properties.

observable(name)

Return one mapped observable’s values in frame order.

Parameters:

name (str) – Observable property name.

Returns:

The observable values.

Raises:

KeyError – If the property is not an observable.

Return type:

tuple[Any, Ellipsis]

unwrap()

Return the original property mapping.

class httk.atomistic.models.trajectory.Trajectory(frames, observables=None, reference_frames=None)

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

Store an immutable trajectory in the native backend.

A trajectory requires at least one frame and keeps one constant composition across all frames.

Parameters:

• frames (collections.abc.Sequence[httk.atomistic.models.structure.like.StructureLike]) – Unit-cell structures to coerce and store.

• observables (collections.abc.Mapping[str, collections.abc.Sequence[Any]] | None) – Optional per-frame observable values.

• reference_frames (collections.abc.Sequence[int] | None) – Optional indexes of bounded reference frames.

kind: ClassVar[str] = 'native'

property nframes: int

Return the number of stored frames.

frame(i)

Return one stored frame by index.

Parameters:

i (int) – Frame index.

Returns:

The requested unit-cell structure.

Raises:

IndexError – If the index is out of range.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()

Iterate over the stored frames.

Returns:

An iterator of unit-cell structures.

Return type:

collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property reference_frames: tuple[int, Ellipsis] | None

Return the bounded reference-frame indexes, or None.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]

Return the names of stored observables.

observable(name)

Return one observable’s values in frame order.

Parameters:

name (str) – Observable name.

Returns:

The observable values.

Raises:

KeyError – If the observable is unavailable.

Return type:

tuple[Any, Ellipsis]

class httk.atomistic.models.trajectory.TrajectoryView(obj, **hints)

Bases: httk.core.View[httk.atomistic.models.trajectory.backend.TrajectoryBackend], httk.atomistic.models.trajectory.api.TrajectoryAPI

Present any trajectory backend through the canonical trajectory API.

Parameters:

• obj (Any) – A trajectory backend or another accepted trajectory value.

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

property nframes: int

Return the number of frames.

frame(i)

Return one frame by index.

Parameters:

i (int) – Frame index.

Returns:

The requested unit-cell structure.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()

Iterate over the frames.

Returns:

An iterator of unit-cell structures.

Return type:

collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property reference_frames: tuple[int, Ellipsis] | None

Return stored reference-frame indexes, or None.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]

Return the names of available per-frame observables.

property observable_summaries: tuple[Any, Ellipsis]

Return backend-provided observable summaries, if any.

property immutable_id: str | None

Return the backend immutable identifier, if available.

property last_modified: Any

Return the backend modification marker, if available.

property source_locator: str | None

Return the source locator, if available.

observable(name)

Return one observable’s values 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()

Return the original value wrapped by the backend.