nvalchemi.csp.RigidMoleculeASUZarrWriter#
- class nvalchemi.csp.RigidMoleculeASUZarrWriter(store, config=None)[source]#
Write and maintain rigid-molecule ASU representations in a Zarr store.
Custom property names must not contain
/or equal.,.., orzarr.json, which Zarr reserves or interprets as path/metadata keys. These additional naming restrictions apply when writing to Zarr.Use one active writer per store. Reopen a writer after another writer changes the store; cached IDs and property schema are not refreshed automatically. Readers must refresh after any store mutation.
- Parameters:
store (StoreLike) – Filesystem path or Zarr-compatible store.
config (ZarrWriteConfig or mapping, optional) – Toolkit chunking and compression settings.
- append(structures)[source]#
Append new ASU rows or skip rows already stored with identical IDs and values.
Appending the same stored row again has no effect. A reused ID with different values fails before any mutation. IDs of deleted rows may be reused. Recovery from interrupted storage I/O is outside this API’s guarantees. The input batch is not modified.
- Parameters:
structures (RigidMoleculeASUBatch) – Rows to append, with the same packing input and property names, dtypes, and per-structure shapes.
- Raises:
ValueError – If IDs conflict, are negative, or the packing input or property names, dtypes, or per-structure shapes differ from the store.
OverflowError – If the resulting molecule pointers exceed the on-disk int32 range.
- Return type:
None
- defragment(config=None)[source]#
Rewrite active rows densely in their current logical order.
Deleted rows are removed, so physical row indices may change. Existing readers should call
RigidMoleculeASUZarrReader.refresh()after defragmentation. The packing input and property schema are retained.configreplaces this writer’s settings after the new store has been installed. Only local filesystem stores are supported; callers must provide exclusive access.- Parameters:
config (ZarrWriteConfig or mapping, optional) – Chunking and compression settings for the rewritten arrays.
- Raises:
ValueError – If any configured array layout is invalid.
TypeError – If the store is not a local filesystem path.
RuntimeError – If replacement fails, including when rollback restores the original. Backup-cleanup failure raises after replacement succeeds; the new store and writer configuration remain active.
- Return type:
None
- delete(indices)[source]#
Remove rows from the active set and overwrite their stored values with zeros.
- Parameters:
indices (torch.Tensor) – One-dimensional int32/int64 indices in the current sequence of undeleted rows. Deleting logical row 0 makes the old row 1 the new row 0; repeated indices delete a row once.
- Raises:
IndexError – If any index is outside the active logical row range.
TypeError – If
indicesis not a one-dimensional int32/int64 tensor.
- Return type:
None
- write(structures)[source]#
Create a new store from rigid-molecule ASU structures.
Identical repeated structure IDs in the input are stored once. Conflicting rows with the same ID fail before the store is created. This method does not modify
structures.- Parameters:
structures (RigidMoleculeASUBatch) – ASU structures and their versioned packing input.
- Raises:
FileExistsError – If the target filesystem path already exists, including an empty directory, or an existing store is found.
ValueError – If duplicate IDs conflict, an ID is negative, or a custom property name is unsupported by Zarr.
OverflowError – If molecule pointers exceed the on-disk int32 range.
- Return type:
None