Utilities

mockdock.utils.detect_gpus()

Detect available NVIDIA GPUs via nvidia-smi.

Return type:

int

mockdock.utils.effective_cpu_count()

Return CPUs this job may use (Slurm / Linux cgroup aware).

multiprocessing.cpu_count() often reports every logical CPU on the host (for example 128) even when Slurm grants --cpus-per-task=2. Mockdock uses this value for multiprocessing.Pool sizing, so the raw host count can spawn far too many workers and trigger OOM.

Return type:

int

mockdock.utils.resolve_backend(requested_backend, n_gpus, adgpu_executable='adgpu')

Resolve which docking backend to use based on request and availability.

Parameters:

• requested_backend (str) – ‘autodock_gpu’, ‘vina’, or ‘auto’.

• n_gpus (int) – Number of GPUs available (used for ‘auto’).

• adgpu_executable (str) – Name or path of the AutoDock-GPU executable.

Returns:

The resolved backend string (‘autodock_gpu’ or ‘vina’).

Return type:

str

mockdock.utils.standardize_smiles(smiles)

Strip salts, neutralize, and return a canonical SMILES string.

Steps applied in order: 1. Parse the SMILES — returns None if invalid. 2. Keep the largest fragment (removes counter-ions like [Na+], [Cl-]). 3. Neutralize charges where chemically sensible. 4. Return RDKit canonical SMILES.

Parameters:

smiles (str) – Input SMILES string.

Returns:

Canonical SMILES, or None if the input is invalid or standardization fails.

Return type:

str | None

mockdock.utils.get_robust_match(target_mol, query_mol)

Substructure match robust to kekulization / bond-order differences.

Tries an exact match first; if that fails, relaxes bond-order constraints via AdjustQueryProperties before giving up.

Parameters:

• target_mol (Mol) – The molecule to search in.

• query_mol (Mol) – The fragment/pattern to look for.

Returns:

A tuple of atom indices (non-empty on success, empty on failure).

Return type:

tuple[int, …]

mockdock.utils.check_2d_match(mol, fragment_mol)

Check whether mol contains fragment_mol as a 2-D substructure.

Uses get_robust_match() for kekulization-tolerant matching.

Parameters:

• mol (Mol) – A valid RDKit Mol to search in. The caller is responsible for obtaining it via check_validity().

• fragment_mol (Mol | None) – The fragment pattern to look for. Returns True immediately when None (no constraint configured).

Returns:

True if the fragment is found (or no constraint is configured).

Return type:

bool

mockdock.utils.plot_docking_results(df, score_col='docking_score', activity_col='pchembl_value', valid_col='valid_pose_found', output_path=None)

Plot docking scores vs pChEMBL values. Assumes activity_col is already log-scaled (e.g., pchembl_value).

Parameters:

• df (DataFrame)

• score_col (str)

• activity_col (str)

• valid_col (str)

• output_path (str | None)

mockdock.utils.plot_activity_distribution(df, activity_col='pchembl_value', output_path=None)

Plot the distribution of bioactivity values.

Parameters:

• df (DataFrame) – Polars DataFrame containing activity data.

• activity_col (str) – Column name for activity values.

• output_path (str | None) – If provided, save the plot to this path.

async mockdock.utils.fetch_ligand_expo_sdf(resname, output_dir, session=None)

Fetch the ideal SDF for a ligand from RCSB Ligand Expo.

Parameters:

• resname (str) – The 3-letter ligand residue name (e.g., ‘ATP’).

• output_dir (Path) – Directory where the SDF file should be saved.

• session (ClientSession | None) – Optional aiohttp ClientSession to reuse connections.

Return type:

Path | None

mockdock.utils.assign_bond_orders_from_template(pdb_mol, template_mol)

Assign bond orders to a PDB molecule using a template molecule (with bond orders).

Parameters:

• pdb_mol (Mol)

• template_mol (Mol)

Return type:

Mol | None