haddock.libs.libligand module

Ligand topology utilities.

haddock.libs.libligand.extract_ligand(pdb_file: str | Path, resnames: list[str], dest: str | Path) → Path[source]

Write a PDB with a single copy of each of the given residue names.

prodrg can only handle a single small molecule. When the ligand is part of a larger system (e.g. a protein/ligand complex), the surrounding macromolecule must be stripped out before prodrg is run, otherwise it fails to generate topology and parameter files.

When a ligand is present in several copies (same residue name, different residue numbers/chains), all copies share the same topology, so only the first copy of each residue name is kept to avoid feeding prodrg redundant (and potentially too many) atoms.

Atoms that CNS mislabelled as a two-letter metal element (e.g. a phosphate PB written with element Pb) are corrected back to their real single-letter element so prodrg can parametrise them.

Parameters:
  • pdb_file (FilePath) – Path to the input PDB file (may contain a full system).

  • resnames (list[str]) – Residue names to keep (typically the unknown ligand residues).

  • dest (FilePath) – Path to the PDB file to write with only the selected residues.

Returns:

Path – Path to the written ligand-only PDB file (dest).

haddock.libs.libligand.find_chain_residues(pdb_file: str | Path, resnames: list[str], cutoff: float = 2.0) → list[str][source]

Find the residues covalently linked to their neighbours in a chain.

Such residues (e.g. a modified amino acid within a protein) cannot be parameterised by prodrg, which treats every residue as a free molecule and does not create the bonds to the rest of the chain.

A residue is linked when its N (or P) is within cutoff of the C (or O3’) of the previous residue in the same chain, or its C (or O3’) within cutoff of the N (or P) of the next one.

Parameters:
  • pdb_file (FilePath) – PDB file containing the residues.

  • resnames (list[str]) – Names of the residues to check.

  • cutoff (float) – Maximum bond length, in Angstrom.

Returns:

list[str] – The linked residues, as "<resname> (chain <chain>, residue <resid>)".

haddock.libs.libligand.find_linked_sugars(pdb_file: str | Path, resnames: list[str], cutoff: float = 2.0) → list[str][source]

Find the sugars linked to another residue by a glycosidic bond.

Like residues within a chain, such sugars (e.g. an unsupported glycan unit bound to a protein) cannot be parameterised by prodrg, which does not create the glycosidic bonds.

A residue is a sugar when it has the ring atoms of a pyranose or a furanose (see _SUGAR_RINGS). It is linked when its anomeric carbon (C1, or C2 for ketoses such as sialic acids) is within cutoff of an O, N or S atom of another residue (e.g. ASN ND2, or O4 of another sugar), or when one of its O atoms is within cutoff of the anomeric carbon of another sugar.

Parameters:
  • pdb_file (FilePath) – PDB file containing the residues.

  • resnames (list[str]) – Names of the residues to check.

  • cutoff (float) – Maximum bond length, in Angstrom.

Returns:

list[str] – The linked sugars and their partners, as "<resname> (chain <chain>, residue <resid>) linked to <partner>".

haddock.libs.libligand.identify_unknown_hetatms(pdb_file: str | Path) → list[str][source]

Return residue names in a PDB that are not in the supported residues.

Parameters:

pdb_file (FilePath) – Path to the PDB file to inspect.

Returns:

list[str] – Unique residue names not found in the supported residues set, in order of first appearance.

haddock.libs.libligand.ion_naming_hint(pdb_file: str | Path, resnames: list[str]) → str[source]

Explain the ion naming for unknown residues that look like ions.

A residue looks like an ion when it consists of a single atom, or when its name is an ion element followed by a charge that is not defined (e.g. CU3, or LI without a charge).

Parameters:
  • pdb_file (FilePath) – PDB file containing the residues.

  • resnames (list[str]) – Names of the unknown residues.

Returns:

str – The explanation, or an empty string if no residue looks like an ion.

haddock.libs.libligand.run_prodrg(pdb_file: str | Path, output_dir: str | Path, ligand_resnames: list[str] | None = None) → tuple[Path, Path][source]

Run prodrg on a ligand PDB and write CNS topology and parameter files.

The resulting files are written to output_dir named after the input PDB stem.

prodrg can only process a single small molecule at a time. When ligand_resnames lists several distinct ligands, prodrg is run once per ligand (on a single extracted copy of each) and the resulting topology and parameter files are concatenated into one .top and one .param. Each ligand is given a unique CNSSEP character so that prodrg generates non-overlapping atom type names across the concatenated files; the characters used are also chosen to avoid the separators already present in the built-in cofactors.top topology, so a single auto-generated ligand likewise cannot clash with the cofactor atom types.

Parameters:
  • pdb_file (FilePath) – Path to the ligand PDB file. It may also be a full system (e.g. a protein/ligand complex), in which case ligand_resnames must be provided so that only the ligand residues are passed to prodrg.

  • output_dir (FilePath) – Directory where the named .top and .param files are written.

  • ligand_resnames (Optional[list[str]]) – Residue names of the ligand(s) to extract before running prodrg. When provided, each distinct ligand is extracted (a single copy) and passed to prodrg separately, stripping out the rest of the system (e.g. the protein). When None, the whole pdb_file is passed to prodrg unchanged.

Returns:

tuple[Path, Path] – Paths to the written <stem>_prodrg.top and <stem>_prodrg.param files.

Raises:

RuntimeError – If prodrg exits with a non-zero return code or the expected output files are not created.