UFFBatchedForcefield#

class nvmolkit.batchedForcefield.UFFBatchedForcefield( molecules: list[Mol], vdwThreshold: float | Sequence[float] = 10.0, ignoreInterfragInteractions: bool | Sequence[bool] = True, hardwareOptions: HardwareOptions | None = None, )#

Evaluate UFF energies and gradients, or run BFGS minimization, for a batch of molecules with all their conformers.

Constraints are per-molecule and are shared across all conformers of that molecule. Results are nested as list[list[...]] — outer per-molecule, inner per-conformer.

Examples:

ff = UFFBatchedForcefield([mol_a, mol_b])
energies = ff.compute_energy()  # [[...], [...]]

ff = UFFBatchedForcefield([mol_a, mol_b])
ff[0].add_position_constraint(0, 0.1, 50.0)
opt_energies, converged = ff.minimize()

__init__( molecules: list[Mol], vdwThreshold: float | Sequence[float] = 10.0, ignoreInterfragInteractions: bool | Sequence[bool] = True, hardwareOptions: HardwareOptions | None = None, )#

Create a batched UFF forcefield wrapper.

All conformers of each molecule are included in the batch automatically.

Parameters:

molecules – RDKit molecules to evaluate.
vdwThreshold – Van der Waals threshold, scalar or per-molecule.
ignoreInterfragInteractions – Whether to omit interfragment non-bonded interactions, as a scalar or per-molecule list.
hardwareOptions – GPU device and batching configuration. Uses reasonable defaults when None.

compute_energy() → list[list[float]]#

Return forcefield energies for all conformers of all molecules.

Returns:: result[mol_idx][conf_idx] – one energy per conformer.

compute_gradients() → list[list[list[float]]]#

Return forcefield gradients for all conformers of all molecules.

Returns:: result[mol_idx][conf_idx] – one flattened [x0, y0, z0, ...] gradient vector per conformer.

rebuild() → None#: Rebuild the forcefield after changing constraints or settings.

minimize( maxIters: int = 1000, forceTol: float = 0.0001, output: Literal[CoordinateOutput.RDKIT_CONFORMERS] = CoordinateOutput.RDKIT_CONFORMERS, target_gpu: int | None = None, ) → tuple[list[list[float]], list[list[bool]]]#

minimize( maxIters: int = 1000, forceTol: float = 0.0001, *, output: Literal[CoordinateOutput.DEVICE], target_gpu: int | None = None, ) → Device3DResult

Run BFGS minimization on all conformers of all molecules.

In RDKIT_CONFORMERS mode, optimized coordinates are written back into the RDKit conformers in-place. In DEVICE mode, optimized coordinates and energies stay on the GPU, the wrapper’s persistent on-device positions buffer is updated in-place (no host roundtrip), and a Device3DResult is returned.

Parameters:

maxIters – Maximum number of BFGS iterations.
forceTol – Gradient convergence tolerance.
output – RDKIT_CONFORMERS (default) or DEVICE.
target_gpu – In DEVICE mode, the GPU to consolidate the result on. None (the default) selects the wrapper’s own GPU. The wrapper is single-GPU - the only supported value is the wrapper’s GPU id; passing a different GPU raises invalid_argument. For cross-GPU consolidation use the standalone UFFOptimizeMoleculesConfs(output=DEVICE, targetGpu=...) API.

Returns:

(energies, converged) nested host lists. For DEVICE mode: a Device3DResult whose values field holds the optimized coordinates, energies holds final energies, and converged holds per-conformer convergence flags.

Return type:

For RDKit mode