pestifer.charmmff.charmmfftop module

This module defines classes and methods that facilitate reading and parsing of CHARMM RESI and MASS records from top, rtp, and str files from the force field.

class pestifer.charmmff.charmmfftop.CharmmAngle(name1: str = '', name2: str = '', name3: str = '', degrees: float = 0.0)

Bases: object

This class represents a single angle record from a CHARMM topology file. It contains the names of the three atoms that form the angle and the angle in degrees. The names are stored in uppercase, and the angle is stored as a float.

degrees: float = 0.0

The angle in degrees; only relevant in an IC

name1: str = ''

The name of the first atom in the angle, stored in uppercase.

name2: str = ''

The name of the second atom in the angle, stored in uppercase.

name3: str = ''

The name of the third atom in the angle, stored in uppercase.

class pestifer.charmmff.charmmfftop.CharmmAngleList(data: list[CharmmAngle])

Bases: UserList[CharmmAngle]

This class is a list-like object that stores CharmmAngle objects. It allows for easy iteration over the angles and provides methods to retrieve angles by atom names.

data

A list of CharmmAngle objects representing the angles in a CHARMM topology file.

Type:

list

classmethod from_card(card: str) → CharmmAngleList

class pestifer.charmmff.charmmfftop.CharmmAtom(name: str = '', type: str = '', charge: float = 0.0, mass: float = 0.0, element: str = '?', inpatch: bool = False)

Bases: object

This class represents a single atom record from a CHARMM topology file. It contains the atom name, type, charge, mass, and optionally the element symbol. The atom name is stored in uppercase, and the type is also stored in uppercase. If the atom name starts with a digit, it is marked as an inpatch atom.

charge: float = 0.0

The charge of the atom, stored as a float.

element: str = '?'

The element symbol, if provided, otherwise set to ‘?’.

classmethod from_card(card: str) → CharmmAtom

inpatch: bool = False

A flag indicating whether the atom is part of a patch, set to True if the name starts with a digit.

mass: float = 0.0

The mass of the atom, stored as a float.

name: str = ''

The name of the atom, stored in uppercase.

set_mass(massdict: CharmmMassDict) → CharmmAtom

This method retrieves the mass record for the atom type from the provided CharmmMassDict object. If the atom type is found, it sets the mass and element attributes of the atom. If the atom type is not found, it logs an error and exits.

Parameters:

massdict (CharmmMassDict) – A CharmmMassDict object containing mass records for atom types.

Raises:

• ValueError – If the atom type is not found in the CharmmMassDict object.

• TypeError – If the masses parameter is not a CharmmMasses object.

type: str = ''

The type of the atom, stored in uppercase.

class pestifer.charmmff.charmmfftop.CharmmAtomDict(*args, **kwargs)

Bases: UserDict[str, CharmmAtom]

This class represents a dictionary mapping atom names to their corresponding CharmmAtom objects.

from_list(atom_list: CharmmAtomList)

to_list() → CharmmAtomList

class pestifer.charmmff.charmmfftop.CharmmAtomList(data: list[CharmmAtom])

Bases: UserList[CharmmAtom]

This class is a list-like object that stores CharmmAtom objects. It allows for easy iteration over the atoms and provides methods to retrieve atoms by name, mass, serial number, and element.

append(atom: CharmmAtom)

This method appends a CharmmAtom object to the caller. If the atom does not have a serial number, it assigns a new serial number based on the current length of the list.

Parameters:

atom (CharmmAtom) – The CharmmAtom object to append to the list.

from_dict(atom_dict: CharmmAtomDict)

get_atom(name: str) → CharmmAtom | None

This method searches for an atom by its name in the list of CharmmAtom objects.

Parameters:

name (str) – The name of the atom to retrieve.

Returns:

The CharmmAtom object with the specified name, or None if not found.

Return type:

CharmmAtom

get_element(name: str) → str

Retrieve the element of an atom by its name. This method searches for an atom by its name in the list of CharmmAtom objects and returns its element symbol. If the atom is not found or does not have an element attribute, it returns ‘?’.

Parameters:

name (str) – The name of the atom whose element is to be retrieved.

Returns:

The element symbol of the atom, or ‘?’ if the atom is not found or does not have an element attribute.

Return type:

str

get_mass() → float

Return the sum of the masses of all atoms in the list.

get_mass_of_member(name: str) → float

This method searches for an atom by its name in the list of CharmmAtom objects and returns its mass. If the atom is not found or does not have a mass attribute, it returns 0.0.

Parameters:

name (str) – The name of the atom whose mass is to be retrieved.

Returns:

The mass of the atom in AMU, or 0.0 if the atom is not found or does not have a mass.

Return type:

float

get_serial(name: str) → int

Retrieve the serial number of an atom by its name. This method searches for an atom by its name in the list of CharmmAtom objects and returns its serial number. If the atom is not found or does not have a serial attribute, it returns -1.

Parameters:

name (str) – The name of the atom whose serial number is to be retrieved.

Returns:

The serial number of the atom, or -1 if the atom is not found or does not have a serial attribute.

Return type:

int

set_masses(massdict: CharmmMassDict)

This method iterates through all CharmmTopAtom objects in the list and sets their masses using the provided CharmmMassDict object. It calls the set_mass method of each atom.

Parameters:

massdict (CharmmMassDict) – A CharmmMassDict object containing mass records for atom types.

to_dict(key: str = 'name')

class pestifer.charmmff.charmmfftop.CharmmBond(name1: str = '', name2: str = '', degree: int = 1, length: float = 0.0)

Bases: object

This class represents a single bond record from a CHARMM topology file. It contains the names of the two atoms that form the bond and the degree of the bond (single, double, or triple). The names are stored in uppercase, and the degree is stored as an integer. Because multiple bonds are stored on a line, input is managed by CharmmBondList.

degree: int = 1

The degree of the bond, which can be 1 (single), 2 (double), or 3 (triple). Defaults to 1.

length: float = 0.0

Length of the bond in Angstroms; only relevant within an IC

name1: str = ''

The name of the first atom in the bond, stored in uppercase.

name2: str = ''

The name of the second atom in the bond, stored in uppercase.

class pestifer.charmmff.charmmfftop.CharmmBondList(data: list[CharmmBond])

Bases: UserList[CharmmBond]

This class is a list-like object that stores CharmmBond objects. It allows for easy iteration over the bonds and provides methods to retrieve bonds by atom names.

data

A list of CharmmBond objects representing the bonds in a CHARMM topology file.

Type:

list

classmethod from_card(card: str, degree: int = 1) → CharmmBondList

Create a CharmmBondList from a CHARMM bond record.

class pestifer.charmmff.charmmfftop.CharmmDelete(atomname: str = '', comment: str = '', raw_string: str = '', error_code: int = 0)

Bases: object

This class represents a single delete atom record from a CHARMM topology file. It contains the atom name to be deleted and an optional comment. The atom name is stored in uppercase, and the comment is stored as a string.

atomname: str = ''

The name of the atom to be deleted, stored in uppercase.

comment: str = ''

An optional comment associated with the delete atom record.

error_code: int = 0

An error code indicating the status of the delete atom record. Defaults to 0.

classmethod from_card(card: str) → CharmmDelete

raw_string: str = ''

The raw string representation of the delete atom record.

class pestifer.charmmff.charmmfftop.CharmmDeleteList(initlist=None)

Bases: UserList[CharmmDelete]

This class represents a list of delete atom records from a CHARMM topology file.

class pestifer.charmmff.charmmfftop.CharmmDihedral(name1: str = '', name2: str = '', name3: str = '', name4: str = '', dihedral_type: str = 'proper', degrees: float = 0.0)

Bases: object

This class represents a single dihedral record from a CHARMM topology file. It contains the names of the four atoms that form the dihedral and the dihedral type (proper or improper). The names are stored in uppercase, and the dihedral type is stored as a string.

degrees: float = 0.0

The angle in degrees; only relevant in an IC.

dihedral_type: str = 'proper'

The type of the dihedral, which can be ‘proper’ or ‘improper’. Defaults to ‘proper’.

name1: str = ''

The name of the first atom in the dihedral, stored in uppercase.

name2: str = ''

The name of the second atom in the dihedral, stored in uppercase.

name3: str = ''

The name of the third atom in the dihedral, stored in uppercase.

name4: str = ''

The name of the fourth atom in the dihedral, stored in uppercase.

class pestifer.charmmff.charmmfftop.CharmmDihedralList(data: list[CharmmDihedral])

Bases: UserList[CharmmDihedral]

This class is a list-like object that stores CharmmDihedral objects. It allows for easy iteration over the dihedrals and provides methods to retrieve dihedrals by atom names.

data

A list of CharmmDihedral objects representing the dihedrals in a CHARMM topology file.

Type:

list

classmethod from_card(card: str, dihedral_type: str = 'proper') → CharmmDihedralList

class pestifer.charmmff.charmmfftop.CharmmIC(card: str = '', atoms: CharmmAtomList = <factory>, bonds: CharmmBondList = <factory>, angles: CharmmAngleList = <factory>, dihedral: CharmmDihedral = <factory>, dihedral_type: str = 'proper', empty: bool = False)

Bases: object

This class represents a single internal coordinate (IC) record from a CHARMM topology file. It contains the names of the four atoms that define the internal coordinate, the lengths of the bonds, the angles, and the dihedral angle. The names are stored in uppercase, and the lengths, angles, and dihedral angle are stored as floats.

angles: CharmmAngleList

A CharmmAngleList containing the angles defined by the internal coordinate.

atoms: CharmmAtomList

A list of the names of the four atoms that define the internal coordinate, stored in uppercase.

bonds: CharmmBondList

A CharmmBondList containing the bonds defined by the internal coordinate.

card: str = ''

The unprocessed string for the IC

dihedral: CharmmDihedral

A CharmmDihedral object representing the dihedral angle defined by the internal coordinate.

dihedral_type: str = 'proper'

The type of the dihedral, which can be ‘proper’ or ‘improper’. Defaults to ‘proper’.

empty: bool = False

A flag indicating whether the internal coordinate is empty (i.e., missing data). Defaults to False.

classmethod from_card(card: str) → CharmmIC

class pestifer.charmmff.charmmfftop.CharmmICList(initlist=None)

Bases: UserList[CharmmIC]

This class represents a list of internal coordinate records from a CHARMM topology file.

class pestifer.charmmff.charmmfftop.CharmmMass(atom_type: str = '', atom_mass: float = 0.0, atom_element: str = '?', com: str = '')

Bases: object

This class represents a single mass record from a CHARMM topology file. It contains the atom type, mass, and optionally the element symbol. The atom type is stored in uppercase, and the mass is stored as a float.

atom_element: str = '?'

The element symbol, if provided, otherwise inferred from the atom type.

atom_mass: float = 0.0

The mass of the atom in AMU, stored as a float.

atom_type: str = ''

The atom type, stored in uppercase.

com: str = ''

A comment associated with the mass record, if present.

classmethod from_card(card: str) → CharmmMass

class pestifer.charmmff.charmmfftop.CharmmMassDict(mList: list[CharmmMass])

Bases: UserDict[CharmmMass]

This class is a dictionary-like object that stores CharmmMassRecord objects. It allows for easy retrieval of mass records by atom type.

data

A dictionary mapping atom types to CharmmMassRecord objects.

Type:

dict

from_list(other: CharmmMassList)

to_list()

class pestifer.charmmff.charmmfftop.CharmmMassList(initlist=None)

Bases: UserList[CharmmMass]

classmethod from_cardlist(cardlist: list[str])

from_dict(d: dict[str, CharmmMass])

to_dict()

class pestifer.charmmff.charmmfftop.CharmmResi(key: str = '', blockstring: str = '', resname: str = '', charge: float = 0.0, mass: float = 0.0, synonym: str = '', metadata: dict = <factory>, atoms: CharmmAtomList = <factory>, atomdict: CharmmAtomDict = <factory>, atoms_in_group: dict[str, ~pestifer.charmmff.charmmfftop.CharmmAtomList]=<factory>, bonds: CharmmBondList = <factory>, ICs: CharmmICList = <factory>, Delete: CharmmDeleteList = <factory>, error_code: int = 0, ispatch: bool = False, source_file: str = '')

Bases: object

This class represents a single residue record (RESI) from a CHARMM topology file. It contains the residue name, charge, synonym, and a list of atoms, bonds, internal coordinates (ICs), and delete atoms associated with the residue. The residue name is stored in uppercase, and the charge is stored as a float.

Delete: CharmmDeleteList

A list of CharmmTopDelete objects representing the delete atom records in the residue.

ICs: CharmmICList

A list of CharmmTopIC objects representing the internal coordinates in the residue.

atomdict: CharmmAtomDict

A dictionary mapping atom names to their corresponding CharmmAtom objects.

atoms: CharmmAtomList

A list of CharmmAtom objects representing the atoms in the residue.

atoms_in_group: dict[str, CharmmAtomList]

A dictionary mapping atom group indices to lists of CharmmAtom objects.

blockstring: str = ''

The raw string representation of the residue record.

bonds: CharmmBondList

A list of CharmmBond objects representing the bonds in the residue.

charge: float = 0.0

The charge of the residue, stored as a float.

copy_ICs_from(other: CharmmResi)

This method copies the internal coordinates from another CharmmResi object to the current object. It checks if the atoms in the ICs exist in the current object’s atom dictionary. If any atom in the IC is not found in the current object’s atom dictionary, it logs an error and sets the error code to -5.

Parameters:

other (CharmmResi) – Another CharmmResi object from which to copy the internal coordinates.

detergent_annotate()

This method identifies the head and tail of the detergent based on the carbon atoms in the residue. It constructs a graph representation of the residue and finds the carbon atom to which the hydroxyl oxygen is bound as the head. The tail is determined as the carbon atom furthest away from the head. The method initializes the annotation attribute with heads, tails, and shortest paths based on the detergent structure.

error_code: int = 0

An error code indicating the status of the residue record. Defaults to 0.

formula()

This method constructs an empirical chemical formula string based on the elements present in the atoms of the residue. It counts the occurrences of each element and formats the string according to the standard chemical notation. The elements are sorted in a predefined order (C, H, N, O, P, and then others).

Returns:

The empirical chemical formula of the residue, formatted as a string. If no elements are found, it returns an empty string.

Return type:

str

classmethod from_blockstring(blockstring: str, metadata: dict = {}) → CharmmResi

generic_lipid_annotate()

This method identifies the heads and tails of the lipid based on the carbon atoms in the residue. It constructs a graph representation of the residue and finds carbon chains (tails) by removing edges that, when removed, produce two fragments: one containing only carbons (tail) and the other containing at least one oxygen (head). The method initializes the annotation attribute with heads, tails, and shortest paths based on the lipid structure. It handles cases where there are two tails (as in standard lipids) or multiple chains (as in complex lipids).

ispatch: bool = False

A flag indicating whether the residue contains atoms that are part of a patch. Defaults to False.

key: str = ''

The key for the residue record, typically ‘RESI’ or ‘PRES’.

lipid_annotate()

This method performs lipid-specific annotation based on the metadata of the residue. It checks the streamID and substreamID in the metadata to determine the type of lipid and calls the appropriate annotation method. The available annotation methods are: - sterol_annotate: for cholesterol lipids - detergent_annotate: for detergent lipids - model_annotate: for model lipids - generic_lipid_annotate: for generic lipids The method initializes the annotation attribute with heads, tails, and shortest paths based on the lipid type.

mass: float = 0.0

The mass of the residue, stored as a float; computed after all mass records processed

metadata: dict

A dictionary containing metadata associated with the residue.

model_annotate()

This method initializes the annotation attribute with empty heads, tails, and shortest paths. It is a placeholder and does not perform any specific operations.

static name_from_blockstring(blockstring: str)

num_atoms()

Return the number of atoms in the residue. This method returns the length of the atoms list in the residue.

Returns:

The number of atoms in the residue.

Return type:

int

resname: str = ''

The name of the residue, stored in uppercase.

set_mass(massdict: CharmmMassDict)

This method iterates through all CharmmTopAtom objects in the residue and sets their masses using the provided CharmmMasses object. It calls the set_mass() method of each atom.

Parameters:

masses (CharmmMasses) – A CharmmMasses object containing mass records for atom types.

show_error(buf)

This method checks the error code of the residue record and writes an error message to the provided buffer if the error code is not 0. It provides specific error messages based on the error code value.

Parameters:

buf (function) – A function that takes a string as input and writes it to a buffer or log.

source_file: str = ''

The source file from which the residue was constructed.

sterol_annotate()

This method identifies the head and tail of the sterol based on the carbon atoms in the residue. It constructs a graph representation of the residue and finds the carbon atom to which the hydroxyl oxygen is bound as the head. The tail is determined as the carbon atom furthest away from the head. The method initializes the annotation attribute with heads, tails, and shortest paths based on the sterol structure.

synonym: str = ''

A synonym or comment associated with the residue.

to_file(f)

Write the RESI/PRES block to f, reconstructed from the instance’s parsed data.

Note

Records not captured during parsing — IMPR, CMAP, DONOR, and ACCEPTOR — are omitted from the output. These appear in standard CHARMM force-field topology files but not in the custom patch files (e.g. pestifer.top) that this method is primarily intended to produce.

Parameters:

f (file-like object) – Destination stream.

to_graph(includeH: bool = True)

This method creates a networkx.Graph instance from the bonds in the residue. It adds edges between atoms based on the bonds, and assigns the element of each atom as a node attribute. If parameter includeH is True, hydrogen atoms are included in the graph; otherwise, they are excluded.

Parameters:

includeH (bool, optional) – A flag indicating whether to include hydrogen atoms in the graph. Defaults to True.

Returns:

A networkx graph representing the residue, with atoms as nodes and bonds as edges. Each node has an ‘element’ attribute representing the element of the atom.

Return type:

networkx.Graph

to_psfgen(W: PsfgenScripter, **kwargs)

Generate the psfgen script necessary to build the residue as as standalone molecule to generate its PSF/PDB.

Parameters:

• W (PsfgenScripter) – A PsfgenScripter object to which the residue record will be written in PSFGEN format.

• **kwargs (dict) –

  Additional keyword arguments that can be passed to the method.

  • refic-idx: An index to select a specific internal coordinate (IC) to use as a reference for setting coordinates. Defaults to 0.

Returns:

Returns 0 if successful, or -1 if no valid reference atom could be found.

Return type:

int

class pestifer.charmmff.charmmfftop.CharmmResiDict(*args, **kwargs)

Bases: UserDict[CharmmResi]

A dictionary mapping residue names to their corresponding CharmmResi objects.

classmethod from_blockstring_list(blockstring_list: list[str], metadata: dict[str, str], resnames: list[str] = [])

from_dict(d: dict[str, CharmmResi])

get_residue(name: str) → CharmmResi | None

Get a CharmmResi object by its name.

Parameters:

name (str) – The name of the residue to retrieve.

Returns:

The corresponding CharmmResi object, or None if not found.

Return type:

CharmmResi | None

tally_masses(massdict: CharmmMassDict)

Tally the masses of all residues in the dictionary.

to_dict()

to_resi_pres()

class pestifer.charmmff.charmmfftop.CharmmResiList(initlist=None)

Bases: UserList[CharmmResi]

A list of CharmmResi objects.

classmethod from_blockstring_list(blockstring_list: list[str], metadata: dict[str, str])

from_dict(d: dict[str, CharmmResi])

tally_masses(massdict: CharmmMassDict)

to_dict()

to_resi_pres()