jaxdem.writers.h5_writer#

Asynchronous HDF5 snapshots using the existing serialization format.

Classes

H5Writer([directory, save_every, clean, ...])

Write complete State/System pairs in background workers.

class jaxdem.writers.h5_writer.H5Writer(directory: Path = PosixPath('h5'), save_every: int = 1, clean: bool = False, max_workers: int = 8, max_queue_size: int = 512)#

Bases: BaseAsyncWriter

Write complete State/System pairs in background workers.

Each selected save call produces snapshot_XXXXXXXX.h5 in directory. Files contain the original arrays, including any leading batch or trajectory axes, without wrapping or otherwise changing geometry. Read them with jaxdem.utils.h5.load(), which returns (state, system).

Numbering follows submission order and continues after existing snapshots when reopening a directory. Completed files are published atomically and never replace an existing file. Only complete snapshots appear under the final names; failed writes remove their temporary files.

The inherited queue limits, save_every, context management, and completion/error reporting work like VTKWriter. Call block_until_ready before reading pending files, or use a context manager to wait and close. HDF5 support requires JaxDEM[io].

directory: Path#: The root directory where the writer saves simulation frames.

save(state: State, system: System) → None[source]#

Capture a snapshot and queue its host transfer and HDF5 write.

JAX buffers are immutable and retained until writing completes. Mutable NumPy buffers are copied before submission, and the State and System trees are detached from later attribute assignments.

save_every: int#: Save frequency. The writer pushes a frame to the queue on the first call and on every save_every-th call to the subclass’s save method.

clean: bool#: If True, the writer deletes and recreates directory on initialization. Safety checks prevent deleting the current working directory or the system root.

max_workers: int#: The number of background worker threads to use for parallel I/O.

max_queue_size: int#: Maximum number of pending tasks in the background queue. When the queue is full, submit blocks until a worker frees a slot. This backpressure keeps memory bounded when the simulation outruns disk I/O. Set to 0 for an unbounded queue.