nvalchemi.csp.MolecularPackingInput#
- class nvalchemi.csp.MolecularPackingInput(*, conformer_positions, conformer_ptr, molecule_conformer_ptr, molecule_atom_ptr, atomic_numbers, contact_distances, component_index, component_charge, formula_unit_volume, metadata=None)[source]#
Input data for one ordered molecular formula unit.
Constructor tensors are copied to contiguous CPU storage. Each conformer is centered by its unweighted Cartesian mean. Contact matrix entries are intermolecular contact cutoffs used to measure overlap; the
OverlapReliefPackermay accept residual overlap up toOverlapReliefConfig.overlap_tolerance.formula_unit_volumeis a positive volume estimate in cubic angstroms.Direct in-place mutation of exposed tensors is unsupported. Use
state_dict()for independent CPU copies orto()for owned tensor storage on another device.- Parameters:
conformer_positions (torch.Tensor, float32
[K, 3]) – Concatenated Cartesian atom coordinates in angstroms. Conformers are stored in the order described byconformer_ptrand centered independently by their unweighted Cartesian means at construction.conformer_ptr (torch.Tensor, int32
[C + 1]) – Start and end positions of each conformer’s atoms inconformer_positions. The pointer starts at zero, ends atK, and delimits nonempty conformers.molecule_conformer_ptr (torch.Tensor, int32
[M + 1]) – Start and end conformer indices for each formula-unit molecule’s nonempty conformer pool.molecule_atom_ptr (torch.Tensor, int32
[M + 1]) – Start and end positions of each molecule’s atoms inatomic_numbers. Each molecule is nonempty, and every conformer in its pool has the same atom count.atomic_numbers (torch.Tensor, int64
[A]) – Atomic numbers from 1 through 118 in formula-unit molecule order.contact_distances (torch.Tensor, float32
[A, A]) – Symmetric, finite, positive intermolecular contact cutoffs in angstroms used to measure overlap between atoms in different molecular copies.component_index (torch.Tensor, int32
[M]) – Contiguous nonnegative component IDs, one per formula-unit molecule.component_charge (torch.Tensor, int32
[num_components]) – Formal charge in elementary charge units for each component ID.formula_unit_volume (float) – Positive formula-unit volume estimate in cubic angstroms.
metadata (Mapping[str, object], optional) – JSON-compatible provenance copied into recursively immutable containers.
Notes
All constructor tensors are detached, copied to contiguous CPU storage, and validated once. Pointer tensors describe distinct levels: atom ranges in
molecule_atom_ptr, conformer ranges inmolecule_conformer_ptr, and coordinate ranges inconformer_ptr. The formula input owns the canonical CPU state;to()makes an independent full tensor copy.Examples
This synthetic two-carbon pair illustrates array layout and centering; it is not a chemically prepared molecule.
>>> import torch >>> packing_input = MolecularPackingInput( ... conformer_positions=torch.tensor([[0., 0., 0.], [2., 0., 0.]]), ... conformer_ptr=torch.tensor([0, 2], dtype=torch.int32), ... molecule_conformer_ptr=torch.tensor([0, 1], dtype=torch.int32), ... molecule_atom_ptr=torch.tensor([0, 2], dtype=torch.int32), ... atomic_numbers=torch.tensor([6, 6], dtype=torch.int64), ... contact_distances=torch.ones((2, 2)), ... component_index=torch.tensor([0], dtype=torch.int32), ... component_charge=torch.tensor([0], dtype=torch.int32), ... formula_unit_volume=25.0, ... ) >>> packing_input.conformer_positions.mean(dim=0) tensor([0., 0., 0.])
- property formula_unit_charge: int#
Sum molecule formal charges in the formula unit.
- classmethod from_state_dict(state)[source]#
Construct from an independently owned version-1 state mapping.
- Parameters:
state (Mapping[str, object]) – Mapping returned by
state_dict().- Returns:
A validated and independently owned formula-unit input.
- Return type:
- Raises:
ValueError – If the version, keys, or tensor invariants are invalid.
- 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 molecule_charge: Tensor#
Formal charge for each formula-unit molecule.
The returned tensor follows formula-unit molecule order, including repeated component IDs that represent stoichiometric copies.
- property num_atoms: int#
Number of atoms in the ordered formula unit.
- property num_components: int#
Number of contiguous component IDs represented in the formula unit.
- property num_conformers: int#
Number of conformers in all molecule pools.
- property num_molecules: int#
Number of molecules in the ordered formula unit.
- property sha256: str#
Return the SHA-256 identity of the exact formula-input representation.
The established encoding hashes the ordered tensor field names, dtypes, shapes, and contiguous bytes, followed by recursively JSON-compatible metadata and
repr(float(formula_unit_volume)). This identifies the exact input representation rather than chemical equivalence. The digest is recomputed on every access and is not part ofstate_dict().Reading device-resident tensors copies them to CPU and may synchronize the device, so use this property for input identity or startup checks, not inside a packing loop. Direct in-place tensor mutation remains unsupported.
- Returns:
Lowercase 64-character SHA-256 hexadecimal digest.
- Return type:
str
- state_dict()[source]#
Return version-1 canonical CPU tensors and an independent JSON copy.
- Returns:
A new mapping containing cloned CPU tensors and mutable JSON metadata.
- Return type:
dict[str, object]
- to(device)[source]#
Return newly owned tensor storage on
devicewithout revalidation.- Parameters:
device (torch.device or str) – Target device for formula tensors.
- Returns:
An independent copy of every input tensor on the requested device, including the contact matrix.
- Return type: