tools_io — structure files¶

Structure files: XYZ, PDB, and the reference a path collective variable reads.

The formats a reaction path passes through on its way from a band of images to something PLUMED will bias. A band comes out of reactiontools.tools_reaction as ASE images and is written as XYZ; PATHMSD wants a multi-model PDB whose atom serials match, to the number, the template the run is aligned against with FIT_TO_TEMPLATE. convert_xyz_to_plumed_ref() is what bridges the two, and pdb_remove_ter_index() is why it can promise the numbering agrees.

The PDB reading here is deliberately by column rather than through ASE. PLUMED identifies atoms by serial, so the atom records have to survive the round trip with their names, residues and numbering exactly as written – and a parser that understands a PDB well enough to rebuild it is a parser that will quietly normalise something. Reading columns 31-54 and putting them back is the whole job.

Coordinates are in angstrom throughout, which is what both formats use.

convert_pdb_to_xyz(input_file: str | Path, output_file: str | Path, comment: str | None = None) → int[source]¶

Convert a PDB file to an XYZ file.

Every ATOM and HETATM record contributes one atom, in file order. Multi-model PDB files (MODEL/ENDMDL) produce one XYZ frame per model; files without model records produce a single frame. Coordinates are passed through unchanged, both formats using angstrom.

Parameters:

input_file (str) – Path to the input PDB file.
output_file (str) – Path to the output XYZ file.
comment (str, optional) – Text for the comment line of every frame. If None, a comment naming the source file (and frame number, when there is more than one) is generated. Default is None.

Returns:

int – The number of frames written.

Raises:

ValueError – If the input file contains no ATOM or HETATM records.

See also

convert_xyz_to_pdb: The inverse conversion.

convert_xyz_to_pdb(input_file: str | Path, output_file: str | Path, cutoff_multiplier: float = 1.1, index: int = -1) → int[source]¶

Convert an XYZ file to a PDB file with connectivity and residue assignment.

Molecules (clusters) are identified using distance-based connectivity and assigned unique chain IDs, residue IDs, and three-letter residue names. Atoms within each cluster are reordered following Hill-system convention (C, H, then remaining elements alphabetically). CONECT records are written for all bonds.

Parameters:

input_file (str) – Path to the input XYZ file, or any other structure file ASE can read.
output_file (str) – Path to the output PDB file.
cutoff_multiplier (float, optional) – Multiplier applied to natural covalent-radius cutoffs when determining bonded neighbours. Default is 1.1.
index (int, optional) – Which frame to convert when the input holds a trajectory. Default is -1 (the last frame). Only a single frame is written.

Returns:

int – The number of molecular clusters (connected components) found.

See also

convert_pdb_to_xyz: The inverse conversion.

convert_xyz_to_plumed_ref(xyz_file: str | Path, template_pdb: str | Path, output_file: str | Path, atom_line: str | Sequence[str] = 'HETATM') → None[source]¶

Convert a reaction path from XYZ into the reference PLUMED’s PATHMSD reads.

Each XYZ frame becomes one model of a multi-model PDB, written by taking the template’s atom records and substituting the frame’s coordinates into the columns that hold them. Going through a template rather than writing fresh records is what keeps the atom names, residues and numbering identical to the structure the simulation will be aligned against; PLUMED matches the two by atom serial, and any disagreement is fatal. Both files are renumbered on the way out to guarantee that.

Parameters:

xyz_file (str) – Path to the input XYZ file, holding one frame per path image.
template_pdb (str) – Path to the template PDB, holding only the atoms the collective variable is built from. Renumbered in place.
output_file (str) – Path to write the multi-model PDB to.
atom_line (str or tuple of str, optional) – Record type the template’s atoms are written under; only these lines are carried into the output. Default is 'HETATM', which is what OpenMM writes for ligand-like residues. ASE writes 'ATOM'.

See also

reactiontools.tools_path.path_from_steered_md: Builds the path from steered MD.
estimate_path_lambda: Sizes the LAMBDA the reference should be given.

element_from_pdb_line(line: str) → str[source]¶

Determine the element symbol for a PDB ATOM/HETATM line.

The element column (77-78) is used when present. Otherwise the symbol is inferred from the atom name in columns 13-16, which by convention starts in column 13 for two-character symbols and column 14 for one-character ones.

Parameters:: line (str) – A single ATOM or HETATM record.
Returns:: str – The element symbol, or 'X' if none could be determined.

Notes

The atom-name fallback relies on the name being correctly aligned, which is what distinguishes calcium (CA ``) from an alpha carbon ( CA ). Hydrogen names that collide with two-letter symbols -- ``HE, HF, HG, HO, HS – are resolved as hydrogen, since a PDB with no element column is far likelier to hold a gamma hydrogen than mercury.

format_pdb_atom_name(symbol: str, count: int) → str[source]¶

Format a unique atom name for the PDB atom-name field (columns 13-16).

Single-character elements are indented by one column, following the PDB convention, and names longer than four characters are truncated so that column alignment is preserved.

Parameters:

symbol (str) – The element symbol.
count (int) – Occurrence index of this element within its residue.

Returns:

str – A four-character atom name.

pdb_remove_ter_index(input_path: str | Path, output_path: str | Path) → None[source]¶

Renumber the atom serials of a PDB file, keeping TER and CONECT in step.

Atoms are renumbered sequentially from 1, restarting at each model, and CONECT records are rewritten to point at the new serials. PLUMED insists that a reference and its template agree on numbering, which an edited PDB usually does not, so both are put through this before being handed over. Records other than these are copied out unchanged.

Parameters:

input_path (str) – Path to the input PDB file.
output_path (str) – Path to write the renumbered PDB to. May be the input path.

strip_hydrogens_keep_indices(input_pdb: str | Path, output_pdb: str | Path, keep: Iterable[int] | None = None) → None[source]¶

Remove hydrogen atoms from a PDB file, except for a chosen subset.

A path collective variable built over every atom of a reacting group spends most of its resolution on hydrogens that only rattle. Stripping all but the ones actually being transferred leaves PATHMSD measuring the reaction rather than the thermal noise around it.

Parameters:

input_pdb (str) – Path to the input PDB file.
output_pdb (str) – Path to write the filtered PDB file. Must not be input_pdb: the two files are open at once, so writing in place would truncate the input before it had been read.
keep (iterable of int, optional) – 0-based atom indices (matching PDB serial number minus one) of hydrogens to retain even though they would otherwise be stripped. If None, all hydrogens are removed. Default is None.

write_xyz_frame(fh: TextIO, symbols: Sequence[str], positions: Sequence[Sequence[float]] | ndarray, comment: str = '') → None[source]¶

Write a single frame to an open XYZ file handle.

Parameters:

fh (file-like object) – An open, writable text handle.
symbols (sequence of str) – Element symbol for each atom.
positions (sequence of sequence of float) – Cartesian coordinates in angstrom, one (x, y, z) triple per atom.
comment (str, optional) – Text for the frame’s comment line. Default is an empty string.