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.

P is the number of structures, Z is the number of formula units in the full cell, and Z-prime is 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_prime independent copies of the formula unit in packing_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.

select shares packing_input and 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 z and z_prime values are supported.

Return type:

RigidMoleculeASUBatch

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:

RigidMoleculeASUBatch

Raises:
  • TypeError – If indices is 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:

RigidMoleculeASUBatch

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. None expands 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:

Batch

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.