MolecularDiffusion.utils.geom_stability¶

Molecular Stability Assessment Module for 3D Molecular Generation Evaluation.

This module provides aromatic-aware stability validation by separating aromatic and non-aromatic bond contributions. Ported from geom-drugs-3dgen-evaluation.

Functions¶

`bond_type_to_symbol`(→ str)	Convert bond type numeric to chemical symbol.
`compute_bond_angles_diff`(→ Dict)	Compute bond angle differences between initial and optimized structures.
`compute_bond_lengths_diff`(→ Dict)	Compute bond length differences between initial and optimized structures.
`compute_differences`(→ Dict)	Compute geometry differences using a specific compute_function.
`compute_mmff_energy_drop`(→ Optional[float])	Compute MMFF energy drop after optimization.
`compute_molecules_stability`(→ Tuple[torch.Tensor, ...)	Compute stability metrics for RDKit molecules.
`compute_molecules_stability_from_graph`(...)	Compute molecular stability from graph representations.
`compute_rmsd`(→ float)	Compute RMSD between initial and optimized molecule coordinates.
`compute_statistics`(→ Dict)	Compute statistics: average difference, standard deviation, and weight.
`compute_torsion_angles_diff`(→ Dict)	Compute torsion angle differences using SMARTS-based rotatable bond identification.
`generate_canonical_key`(→ tuple)	Generate canonical key for molecular components (order-independent).
`get_default_valencies`(→ Dict[str, Any])	Get default aromatic-aware valency table (lazy loading).
`get_simple_valencies`(→ Dict[str, Any])	Get simple valency table for 1.5 aromatic mode (lazy loading).
`is_valid`(→ bool)	Validate molecule for single fragment and successful sanitization.
`load_valency_table`(→ Dict[str, Any])	Load valency table from package JSON data.

Module Contents¶

MolecularDiffusion.utils.geom_stability.bond_type_to_symbol(bond_type_numeric: int) → str¶: Convert bond type numeric to chemical symbol.

MolecularDiffusion.utils.geom_stability.compute_bond_angles_diff(pair: Tuple) → Dict¶: Compute bond angle differences between initial and optimized structures.

MolecularDiffusion.utils.geom_stability.compute_bond_lengths_diff(pair: Tuple) → Dict¶

Compute bond length differences between initial and optimized structures.

Parameters:: pair – (initial_mol, optimized_mol) RDKit molecule objects
Returns:: Dict mapping bond type keys to (diff_list, count)

MolecularDiffusion.utils.geom_stability.compute_differences(pairs: List[Tuple], compute_function, show_progress: bool = False) → Dict¶

Compute geometry differences using a specific compute_function.

Parameters:

pairs – List of (init_mol, opt_mol) pairs
compute_function – Function that computes differences for a molecule pair
show_progress – Whether to show a tqdm progress bar

Returns:

Dict with geometry difference stats

MolecularDiffusion.utils.geom_stability.compute_mmff_energy_drop(mol, max_iters: int = 1000) → float | None¶

Compute MMFF energy drop after optimization.

Returns:: Energy difference (E_before - E_after), or None if failed.

MolecularDiffusion.utils.geom_stability.compute_molecules_stability(rdkit_molecules: List, aromatic: bool = True, allowed_bonds: Dict | None = None) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]¶

Compute stability metrics for RDKit molecules.

Parameters:

rdkit_molecules – List of RDKit Mol objects
aromatic – Whether aromatic bonds are expected
allowed_bonds – Custom valency table (defaults to aromatic-aware tuple table)

Returns:

(validity, stability, n_stable_atoms, n_atoms)

MolecularDiffusion.utils.geom_stability.compute_molecules_stability_from_graph(adjacency_matrices: torch.Tensor, numbers: torch.Tensor, charges: torch.Tensor, allowed_bonds: Dict | None = None, aromatic: bool = True) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]¶

Compute molecular stability from graph representations.

Parameters:

adjacency_matrices – Bond matrices [batch, n_atoms, n_atoms] Values: 1=single, 2=double, 3=triple, 1.5=aromatic
numbers – Atomic numbers [batch, n_atoms]
charges – Formal charges [batch, n_atoms]
allowed_bonds – Valency lookup table
aromatic – If True, use tuple valencies (n_aromatic, v_other). If False, sum all bonds (MS 1.5 Arom mode)

Returns:

(stable_mask, n_stable_atoms, n_atoms)

MolecularDiffusion.utils.geom_stability.compute_rmsd(init_mol, opt_mol, hydrogens: bool = True) → float¶: Compute RMSD between initial and optimized molecule coordinates.

MolecularDiffusion.utils.geom_stability.compute_statistics(diff_sums: Dict) → Dict¶

Compute statistics: average difference, standard deviation, and weight.

Parameters:: diff_sums – Dict mapping keys to (diff_list, count)
Returns:: Dict mapping keys to (avg_diff, std_dev, weight)

MolecularDiffusion.utils.geom_stability.compute_torsion_angles_diff(pair: Tuple) → Dict¶: Compute torsion angle differences using SMARTS-based rotatable bond identification.

MolecularDiffusion.utils.geom_stability.generate_canonical_key(*components) → tuple¶: Generate canonical key for molecular components (order-independent).

MolecularDiffusion.utils.geom_stability.get_default_valencies() → Dict[str, Any]¶: Get default aromatic-aware valency table (lazy loading).

MolecularDiffusion.utils.geom_stability.get_simple_valencies() → Dict[str, Any]¶: Get simple valency table for 1.5 aromatic mode (lazy loading).

MolecularDiffusion.utils.geom_stability.is_valid(mol, verbose: bool = False) → bool¶

Validate molecule for single fragment and successful sanitization.

Parameters:

mol – RDKit molecule object
verbose – Print error messages if validation fails

Returns:

True if valid, otherwise False

MolecularDiffusion.utils.geom_stability.load_valency_table(name: str = 'tuple', validate_schema: bool = False) → Dict[str, Any]¶

Load valency table from package JSON data.

Parameters:

name – Table name - “tuple” (aromatic-aware) or “legacy” (backward compat)
validate_schema – Whether to validate against JSON schema (requires jsonschema)

Returns:

Valency table mapping element -> charge -> allowed valencies

Return type:

dict