httk.atomistic.io.optimade_jsonl

Streaming OPTIMADE partial-data JSON Lines trajectories.

The stable httk-trajectory-jsonl 0.1 format is one JSON object per line. The first line is the header:

{
  "optimade-partial-data": {"format": "1.2.0"},
  "layout": "dense",
  "x-httk-trajectory": {
    "format": "httk-trajectory-jsonl", "version": "0.1",
    "species": [{"name": "Si", "chemical_symbols": ["Si"],
                 "concentration": [1.0]}],
    "species_at_sites": ["Si"],
    "constant_cell": [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0],
                       [0.0, 0.0, 1.0]],
    "nframes": 3,
    "observable_names": ["energy"],
    "reference_frames": [0],
    "line_schema": {"...": "see below"}
  }
}

Each following line is a frame object with exactly these semantic members:

{"index": 0,
 "fractional_site_positions": [[0.0, 0.0, 0.0]],
 "observables": {"energy": -1.25}}

index is the zero-based frame number. fractional_site_positions is an N-by-3 array of floating-point presentation values. observables contains every name declared by the header, with null allowed. If constant_cell is null, each frame additionally contains lattice_vectors as a 3-by-3 array of floating-point presentation values. If it is non-null, a frame may include that member only when it is equal to the declared constant cell. The writer emits the compact form and the reader accepts either form. No exact-token channel exists: JSON numbers intentionally follow the floating-point presentation, like the numeric layer.

This is a holding/container format, not a database representation. It follows the OPTIMADE partial-data JSON Lines framing (OPTIMADE 1.2, dense layout), but uses the x-httk-trajectory member because one line carries a complete frame and several properties. A binary framing variant is deliberately deferred pending a separate design decision.

Attributes

FORMAT
VERSION

Classes

TrajectoryJsonlFile

A handle-free, re-scanning, lazy trajectory JSONL reader.

Functions

write_trajectory_jsonl(destination, header, frames)	Write a validated header and frame iterator without buffering frames.
read_trajectory_jsonl(source)	Read a trajectory JSONL path into a lazy neutral payload.

Package Contents

httk.atomistic.io.optimade_jsonl.FORMAT = 'httk-trajectory-jsonl'

httk.atomistic.io.optimade_jsonl.VERSION = '0.1'

class httk.atomistic.io.optimade_jsonl.TrajectoryJsonlFile(filename)

A handle-free, re-scanning, lazy trajectory JSONL reader.

The reader opens short-lived streams for each access and retains no open handle. Header access is lazy, frame iteration streams the file, and full-pass properties cache the count and issue summary. close() is terminal; access after closing is rejected.

Parameters:

filename (str | os.PathLike[str]) – Filesystem path to a trajectory JSONL file, optionally compressed.

property path: str

Return the source filename used to construct this lazy reader.

property closed: bool

Whether this lazy reader has been closed.

close()

Close this reader; future access raises an error.

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

Return the validated header, loading it on first access.

property issues: tuple[str, Ellipsis]

Return issues collected by the full frame scan.

frames()

Stream validated frames without buffering the trajectory.

Yield:

One validated frame mapping at a time.

property nframes: int

Return the declared frame count or determine it by scanning lazily.

frame(i)

Return one frame, rescanning from the start when necessary.

Parameters:

i (int) – Zero-based frame index; negative values count backward from the end.

Returns:

The selected validated frame mapping.

Raises:

IndexError – If i is outside the available frames.

Return type:

collections.abc.Mapping[str, Any]

httk.atomistic.io.optimade_jsonl.write_trajectory_jsonl(destination, header, frames)

Write a validated header and frame iterator without buffering frames.

JSON numbers are normalized to floating-point presentation values while each frame is written, and compressed output is selected from the filename suffix when applicable.

Parameters:

• destination (str | os.PathLike[str] | TextIO) – Filesystem path or open text stream for the output.

• header (collections.abc.Mapping[str, Any]) – Trajectory header describing sites, observables, and cell policy.

• frames (collections.abc.Iterable[collections.abc.Mapping[str, Any]]) – Iterable of frame mappings to validate and write in order.

Raises:

ValueError – If the header, a frame, or the declared frame count is invalid.

httk.atomistic.io.optimade_jsonl.read_trajectory_jsonl(source)

Read a trajectory JSONL path into a lazy neutral payload.

Parameters:

source (str | os.PathLike[str]) – Filesystem path to a trajectory JSONL file, optionally compressed.

Returns:

A neutral payload containing the lazy trajectory reader.

Raises:

• TypeError – If source is not a filesystem path.

• FileNotFoundError – If the path does not exist.

Return type:

dict[str, Any]