schrodinger.application.jaguar.csmiles.collation module

Utility functions for grouping conformers by their CSMILES hash.

Provides O(N) conformer grouping by encoding each conformer as a canonical CSMILES string and bucketing by string equality, as opposed to an O(N^2) pairwise comparison approach.

schrodinger.application.jaguar.csmiles.collation.nearest_valid_precision(threshold: float) → int

Find the divisor of 360 closest to the requested threshold.

CSMILES precision must be a positive integer divisor of 360. This function finds the nearest valid value to an arbitrary numeric threshold. When two divisors are equidistant, the smaller (finer-grained) one is chosen.

Parameters:

threshold – the desired bin size in degrees.

Returns:

the nearest valid precision value.

schrodinger.application.jaguar.csmiles.collation.group_conformers_by_csmiles(structs: Sequence[Structure], precision: int = 1, representation: Representation = Representation.INSET) → tuple[dict[str, list[int]], list[rdkit.Chem.rdchem.Mol], set[int]]

Group conformers by their canonical CSMILES string.

Each structure is checked for CSMILES compatibility, converted to an RDKit Mol, then encoded into a canonical CSMILES at the given precision. Structures that produce the same string are placed in the same bucket, achieving O(N) grouping.

Structures that are incompatible with CSMILES (e.g. metals, disconnected fragments), that fail RDKit conversion, or that fail CSMILES encoding are recorded in the returned failed_indices set using their index into the original structs sequence.

Parameters:

  • structs – Structure objects with 3D conformers.

  • precision – bin size in degrees for dihedral angles; must be a positive integer divisor of 360.

  • representation – CSMILES representation format.

Returns:

a tuple of (groups, mols, failed_indices) where groups maps CSMILES strings to lists of indices into mols, mols is the list of successfully converted Mol objects, and failed_indices is the set of indices into structs that were dropped.

schrodinger.application.jaguar.csmiles.collation.csmiles_max_torsion_difference(mol1: Mol, mol2: Mol, precision: int) → float

Compute the maximum torsion-angle difference between two conformers using the CSMILES canonical graph.

This is a scalar summary suitable for populating a comparison matrix element. It returns the largest absolute dihedral difference across all bonds in the canonical CSMILES representation.

Parameters:

  • mol1 – first conformer as an RDKit Mol.

  • mol2 – second conformer as an RDKit Mol.

  • precision – CSMILES precision (bin size in degrees).

Returns:

maximum absolute dihedral difference in degrees, or 0.0 if the conformers are identical.