MMFFBatchedForcefield#

class nvmolkit.batchedForcefield.MMFFBatchedForcefield( molecules: list[Mol], properties: RDKitMMFFMolProperties | Sequence[RDKitMMFFMolProperties | None] | None = None, nonBondedThreshold: float | Sequence[float] = 100.0, ignoreInterfragInteractions: bool | Sequence[bool] = True, hardwareOptions: HardwareOptions | None = None, )#

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

Properties and 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 = MMFFBatchedForcefield([mol_a, mol_b])
energies = ff.compute_energy()  # [[...], [...]]

ff = MMFFBatchedForcefield(
    [mol_a, mol_b],
    properties=[props_a, None],
    nonBondedThreshold=[100.0, 20.0],
)
ff[0].add_distance_constraint(0, 4, False, 1.8, 2.2, 50.0)
opt_energies, converged = ff.minimize()

Create a batched MMFF forcefield wrapper.

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

Parameters:

molecules – RDKit molecules to evaluate.
properties – RDKit MMFFMolProperties object, a per-molecule list of those objects, or None to use default MMFF94 settings. A single object is broadcast to all molecules.
nonBondedThreshold – Non-bonded cutoff distance or per-molecule values.
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.

minimize( maxIters: int = 200, 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 = 200, 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 MMFFOptimizeMoleculesConfs(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

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.