nvalchemi.csp.chem.build_molecular_packing_input#

nvalchemi.csp.chem.build_molecular_packing_input(molecules, *, contact_distances=None, formula_unit_volume=None, component_index=None, metadata=None)[source]#

Prepare molecular conformers and contact limits required by the Packer.

Parameters:
  • molecules (sequence of rdkit.Chem.rdchem.Mol) – One connected formula-unit molecule per entry, in the order retained by the resulting input. Every attached conformer must be finite and marked 3D. Existing atom, hydrogen, and conformer order is preserved; implicit hydrogens are not added. generate_conformers_from_smiles() adds explicit hydrogens before embedding.

  • contact_distances (torch.Tensor, shape [A, A], optional) – Custom atom-pair contact cutoffs in angstroms. Accepted structures may fall below these distances by the configured overlap tolerance. When omitted, experimental topology-derived contact rules are used. Supplied values are copied, converted to float32, checked for positivity and symmetry, and symmetrized within tolerance.

  • formula_unit_volume (float, optional) – Positive formula-unit volume in cubic angstroms. When omitted, the Toolkit atomic volume estimate is used.

  • component_index (torch.Tensor, int32 [F], optional) – Contiguous component IDs, one per molecule. Defaults to 0..F-1; repeated IDs can group molecules that belong to the same component. The total RDKit formal charge of each molecule is stored once for its component ID; molecules sharing an ID must have the same formal charge.

  • metadata (Mapping[str, JSONValue], optional) – JSON-compatible provenance retained by the formula input.

Returns:

Owned canonical CPU tensors. The formula-input constructor centers each conformer once by its unweighted Cartesian mean.

Return type:

MolecularPackingInput

Raises:
  • OptionalDependencyError – If RDKit is unavailable. Install nvalchemi-toolkit[rdkit].

  • TypeError – If the molecule sequence, custom contact matrix, or component IDs have an invalid type.

  • ValueError – If a molecule lacks a conformer, coordinates are malformed, or any formula-input invariant is violated.

Notes

This helper does not mutate RDKit molecules. Callers that already have tensors or use another chemistry toolkit can construct MolecularPackingInput directly. The returned input stores each component’s total formal charge in elementary charge units and warns if the formula-unit sum is nonzero.

Examples

>>> molecule = generate_conformers_from_smiles(
...     "CO", config=RDKitConformerConfig(num_conformers=1, random_seed=7)
... )
>>> packing_input = build_molecular_packing_input([molecule])
>>> packing_input.num_molecules
1