nvalchemi.csp.RigidMoleculeASUBatch#
- class nvalchemi.csp.RigidMoleculeASUBatch(*, packing_input, structure_molecule_ptr, conformer_indices, rotations, fractional_centers, cells, space_groups, z, z_prime, structure_ids, properties=<factory>)[source]#
Rigid-molecule ASU representations sharing one molecular formula input.
Each structure stores independent molecular placements with its cell and symmetry metadata, rather than full-cell atom coordinates. Different structures may hold different numbers of independent placements.
Pis the number of structures,Zis the number of formula units in the full cell, andZ-primeis the number independently placed in the asymmetric unit (ASU).ASU representation tensors and property values are copied into contiguous storage on one device. Direct in-place mutation of exposed tensors is unsupported.
- Parameters:
packing_input (MolecularPackingInput) – Shared ordered formula-unit state. Public construction retains this already validated object by identity.
structure_molecule_ptr (torch.Tensor, int32
[P + 1]) – Start and end positions of each structure’s independent molecules in the ASU representation arrays.conformer_indices (torch.Tensor, int32
[Q]) – Global conformer-pool indices for each ASU molecule.rotations (torch.Tensor, float32
[Q, 3, 3]) – Cartesian molecular rotations.fractional_centers (torch.Tensor, float32
[Q, 3]) – Fractional molecular centers.cells (torch.Tensor, float32
[P, 3, 3]) – Row-vector lattice cells in angstroms.space_groups (torch.Tensor, int32
[P]) – International space-group numbers, full-cell formula-unit counts (Z), and independently placed ASU formula-unit counts (Z-prime), respectively.z (torch.Tensor, int32
[P]) – International space-group numbers, full-cell formula-unit counts (Z), and independently placed ASU formula-unit counts (Z-prime), respectively.z_prime (torch.Tensor, int32
[P]) – International space-group numbers, full-cell formula-unit counts (Z), and independently placed ASU formula-unit counts (Z-prime), respectively.properties (Mapping[str, torch.Tensor], optional) – One value per crystal structure, with leading dimension
P, on the shared tensor device; trailing dimensions may vary by property. Names cannot collide with Toolkit or CSP output fields.structure_ids (torch.Tensor, int64
[P, 2], optional) –[run_id, structure_ordinal]identifiers. When omitted, a random nonnegative run ID and sequential ordinals are generated. Storage requires nonnegative identifiers.
Notes
Each structure contains
z_primeindependent copies of the formula unit inpacking_input. Molecules follow the same order as that input and select conformers from their respective pools.to_batch()applies the space-group symmetry to generate the full crystal.The unit cell must be compatible with the selected space group, whose number of symmetry operations must equal
z / z_prime. Fractional molecular centers may lie outside[0, 1); expansion wraps them periodically.For externally prepared data, call
check_integrity()before expansion to check molecule assignments and symmetry multiplicities. This check does not validate molecular orientations or cell geometry.selectsharespacking_inputand preserves repeated row indices.- check_integrity()[source]#
Check compact ASU pointer, multiplicity, symmetry, and pool indices.
This explicit check copies only the integer metadata needed for these relationships to CPU. Calling it for device-resident data may synchronize the device. It does not inspect rotations, fractional centers, cells, or other geometry; finite coordinates, proper rotations, nonsingular positive-volume cells, and cell/symmetry compatibility remain caller preconditions. Success therefore does not certify scientific geometry.
The check does not mutate this batch, consume RNG state, or cache a validated flag. Constructors, readers, selection, concatenation, expansion, and packing do not call it automatically.
The operation performs O(P + Q) integer-metadata work plus a transfer of formula-molecule pool metadata. Its cost is unmeasured.
- Raises:
ValueError – If the structure pointer, multiplicity, operation count, or conformer-pool membership relationship is invalid.
- Return type:
None
- classmethod concatenate(batches)[source]#
Concatenate ASU batches with equivalent packing inputs.
- Parameters:
batches (Sequence[RigidMoleculeASUBatch]) – Batches to append in sequence order.
- Returns:
A new ASU batch. Mixed
zandz_primevalues are supported.- Return type:
- Raises:
ValueError – If the sequence is empty, formula inputs differ, devices differ, or property schemas do not match.
- model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True, 'revalidate_instances': 'never'}#
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- property num_structures: int#
Number of ASU structures, including zero for an empty batch.
- select(indices)[source]#
Select ASU rows in requested order, preserving repeated indices.
- Parameters:
indices (torch.Tensor, int32 or int64
[S]) – CPU indices or indices on this ASU batch’s device.- Returns:
A new ASU batch sharing the same formula-unit input object.
- Return type:
- Raises:
TypeError – If
indicesis not a one-dimensional int32/int64 tensor.ValueError – If indices are on an unrelated device.
Examples
[2, 0, 2]returns rows in that order, including the repeated last row. An empty integer tensor returns a valid zero-structure ASU batch.
- to(device)[source]#
Return newly owned ASU representation and formula tensors on
device.- Parameters:
device (torch.device or str) – Target device.
- Returns:
An independent copy of the ASU fields, properties, and formula input on the requested device.
- Return type:
- to_batch(indices=None, *, device=None)[source]#
Expand selected ASU rows into a full-cell periodic Toolkit
Batch.- Parameters:
indices (torch.Tensor, int32 or int64
[S], optional) – Ordered ASU row selection. Repeated indices produce repeated structures.Noneexpands every ASU row.device (torch.device or str, optional) – Output device. Defaults to this ASU batch’s device.
- Returns:
A periodic Toolkit Batch with explicit full-cell atoms and fields recording their ASU source.
- Return type:
Notes
Expansion assumes valid index relationships and geometry. It does not automatically call
check_integrity(); the explicit checker covers indices only, and geometry remains a caller precondition.Cells must be compatible with their space-group operations. Molecular centers are wrapped in fractional space before their unwrapped rigid atomic displacements are added. Provenance describes source state and remains unchanged if a later optimizer changes geometry.