xtructure.io package
Submodules
xtructure.io.io module
Module for saving and loading xtructure dataclasses.
- xtructure.io.io.load(path: str) Xtructurable[source]
Loads an xtructure dataclass instance from a .npz file.
This function reads the .npz file, reconstructs the dataclass type from metadata, and populates a new instance with the saved data.
- xtructure.io.io.save(path: str, instance: Xtructurable, *, packed: bool = True)[source]
Saves an xtructure dataclass instance to a compressed .npz file.
This function serializes the instance by flattening its structure and saving each field as a NumPy array. It also stores metadata to enable reconstruction of the original dataclass type upon loading.
xtructure.io.bitpack module
Bitpacking utilities for compact serialization.
This module packs arrays whose values use only a small number of active bits into a compact uint8 stream, and unpacks them back to arrays.
Design notes: - Supports 1..8 bits per value (inclusive). - Uses JAX-compatible primitives (jnp/jax.vmap) so it can run on device.
- xtructure.io.bitpack.from_uint8(packed_bytes: Array | ndarray | bool | number, target_shape: tuple[int, ...], active_bits: int = 1) Array | ndarray | bool | number[source]
Unpack a uint8 stream back into an array of shape target_shape.
Notes: - For active_bits==1, returns bool. - For active_bits>1, returns uint8 values in [0, 2**active_bits - 1].
Caller can cast to a desired integer dtype.
- xtructure.io.bitpack.packed_num_bytes(num_values: int, active_bits: int) int[source]
Return the number of uint8 bytes required to pack num_values values.
This mirrors the packing strategy of
xtructure.io.bitpack.to_uint8()(block-aligned for 3/5/6/7/etc. bit widths).
- xtructure.io.bitpack.to_uint8(values: Array | ndarray | bool | number, active_bits: int = 1) Array | ndarray | bool | number[source]
Pack an array into a uint8 stream using active_bits per value.
- Parameters:
values – Input array. For active_bits==1, can be bool or integer (0/!=0). For active_bits>1, must be integer.
active_bits – Bits per value in [1, 8].
- Returns:
A 1D uint8 array of packed bytes.
Module contents
Make save and load functions available for direct import from xtructure.io.
- xtructure.io.load(path: str) Xtructurable[source]
Loads an xtructure dataclass instance from a .npz file.
This function reads the .npz file, reconstructs the dataclass type from metadata, and populates a new instance with the saved data.
- xtructure.io.save(path: str, instance: Xtructurable, *, packed: bool = True)[source]
Saves an xtructure dataclass instance to a compressed .npz file.
This function serializes the instance by flattening its structure and saving each field as a NumPy array. It also stores metadata to enable reconstruction of the original dataclass type upon loading.