Topology

class Topology(atoms: List[Atom] | None = None, preamble: List[str] | None = None, molecule_type: MoleculeType | None = None, format: str = 'gromos')[source]

Bases: object

Represents the topology of a molecular system, including atoms, bonds, angles, and dihedrals.

Parameters:

atoms (Optional[List[Atom]], optional) – a list of atoms in the molecular system, defaults to None
preamble (Optional[List[str]], optional) – a string containing the preamble of the topology file, defaults to None
molecule_type (Optional[MoleculeType], optional) – the type of molecule represented by the topology, defaults to None

Variables:

atoms (List[Atom]) – A list of atoms in the molecular system.
bonds (List[Bond]) – A list of bonds in the molecular system.
angles (List[Angle]) – A list of angles in the molecular system.
dihedrals (List[Dihedral]) – A list of dihedral angles in the molecular system.

from_ITP(cls, itp_file: str, preprocess) → 'Topology'[source]: Class method to create a Topology object from a GROMACS ITP file.

add(topology: Topology)[source]

Add a new Topology ‘topology’ to this Topology.

Parameters:: topology (Topology) – a Topology to be added to this Topology.

add_atom(atom: Atom)[source]

Add a new Atom to the Topology. The Atom will be appended to the end of the list of Atoms.

Parameters:: atom (Atom) – a new Atom to add to the Topology.

property angles: List[Angle]

Getter method to retrieve the Topology’s Angles.

Returns:: a list of all of the Angles in this Topology.
Return type:: List[Angle]

atom_counts() → Dict[str, int][source]

Get the number of Atoms of each element in the Topology.

Returns:: a dictionary of each element present as a key with the number of Atoms of this element as it’s value.
Return type:: Dict[str, int]

atom_elements() → set[str][source]

Retrieve a set of all atom elements in the Topology.

Returns:: a set containing all of the elements present in this Topology.
Return type:: set[str]

auto_rename_atoms()[source]

Rename all atoms in the topology to their element symbol plus their index among atoms with the same element (ordered by atom.id).

This compresses the namespace of atom names to the minimum possible, while preserving the element and order of atoms in the topology.

For example, a carbon atom with the smallest id attribute out of all of the carbon atoms will be renamed to “C1”.

property bonds: List[Bond]

Getter method to retrieve the Topology’s Bonds.

Returns:: a list of all of the Bonds in this Topology.
Return type:: List[Bond]

property carbons: dict[slice(<class 'int'>, <class 'polytop.Atoms.Atom'>, None)]

Getter method to retrieve the Topology’s carbon atoms.

Returns:: a dictionary of the carbon atoms in this Topology as values and their keys as their indexes.
Return type:: dict[int: Atom]

change_atom(old_atom: Atom, new_atom: Atom)[source]

Change an Atom in the Topology to a new Atom at the same position in the atom list. Bonds, Angles, Dihedrals, etc. are also updated.

Parameters:

old_atom (Atom) – the Atom to swap out of the Atom list.
new_atom (Atom) – the Atom to swap into the Atom list.

Raises:

ValueError – if ‘old_atom’ is not in the Topology.

clear_former_ids()[source]: Sets the ‘formerly’ attribute of all of the Atoms in the Topology to None.

contains_atom(candidate: Atom) → bool[source]

Check if the Topology contains the given Atom.

Parameters:: candidate (Atom) – the Atom that is being checked to see if it is in the Topology.
Returns:: True if the Atom is in the Topology, otherwise False
Return type:: bool

contains_bond(candidate: Bond) → bool[source]

Check if the Topology contains the given Bond.

Parameters:: candidate (Bond) – the Bond that is being checked to see if it is in the Topology.
Returns:: True if the Bond is in the Topology, otherwise False
Return type:: bool

copy() → Topology[source]

A non-recursive alternative to deepcopy, which is used to create a new Topology with the same Atoms, Bonds, Angles, Dihedrals, etc. This function can copy large topology systems without the risk of stack overflow produced by a deepcopy algorithm.

Returns:: a new copy of this Topology
Return type:: Topology

deduplicate()[source]: Remove any duplicate bonds from the topology.

property dihedrals: List[Dihedral]

Getter method to retrieve the Topology’s Dihedrals.

Returns:: a list of all of the Dihedrals in this Topology.
Return type:: List[Dihedral]

property exclusions: List[Exclusion]

Getter method to retrieve the Topology’s Exclusions.

Returns:: a list of all of the Exclusions in this Topology.
Return type:: List[Exclusion]

classmethod from_ITP(file_path: str, preprocess=None, format: str = 'gromos') → Topology[source]

Class method to create a Topology object from an ITP file.

Note: this function does not explicitly check that moleculetype.nrexcl = number of exclusions associated with atoms.

Parameters:

file_path (str) – the path to the GROMOS ITP file.
preprocess (lambda function, optional) – function to preprocess the topology, that must accept the section and line as arguments in that order, defaults to None.
format (str, defaults to "gromos" for GROMOS forcefields.) – The forcefield the ITP file is formatted as, options are “gromos”, “amber”, “opls” and “charmm”

Returns:

the created Topology object.

Return type:

Topology

classmethod from_dict(data: dict, format: str = 'gromos') → Topology[source]

Create a new Topology from a dictionary, such as that created with Topology.to_dict().

The structure of the dictionary is as below: {“atoms”: [atom.to_dict() for atom in self.atoms], “bonds”: [bond.to_dict() for bond in self.bonds], “angles”: [angle.to_dict() for angle in self.angles], “dihedrals”: [dihedral.to_dict() for dihedral in self.dihedrals], “pairs”: [pair.to_dict() for pair in self.pairs], “exclusions”: [exclusion.to_dict() for exclusion in self.exclusions], “preamble”: self.preamble, “moleculetype”: self.molecule_type.to_dict()}

Parameters:

data (dict) – dictionary containing data to make a Topology, generate with ‘to_dict()’.
format (str, defaults to "gromos" for GROMOS forcefields.) – The forcefield the ITP file is formatted as, options are “gromos”, “amber”, “opls” and “charmm”

Returns:

a new Topology

Return type:

Topology

get_angle(atom_a_id: int, atom_b_id: int, atom_c_id: int) → Angle[source]

get_angle(atom_a_name: str, atom_b_name: str, atom_c_name: str) → Angle

Getter method to retrieve an Angle in the Topology from the id’s of the three Atoms that share it.

Parameters:

atom_a_id (int) – The id of the first Atom involved in the angle.
atom_b_id (int) – The id of the second Atom involved in the angle.
atom_c_id (int) – The id of the third Atom involved in the angle.

Returns:

the corresponding Angle.

Return type:

Angle

get_atom(atom_id: int) → Atom[source]

get_atom(atom_name: str, residue_id: int = None) → Atom

Getter method to retrieve an Atom in the Topology from its id.

Parameters:: atom_id (int) – the id of the desired Atom.
Returns:: the Atom corresponding to the provided ‘atom_id’.
Return type:: Atom

get_bond(atom_a: Atom, atom_b: Atom) → Bond[source]

get_bond(atom_a_id: int, atom_b_id: int) → Bond

get_bond(atom_a_name: str, atom_b_name: str) → Bond

Getter method to retrieve a Bond in the Topology from the two Atoms that share it.

Parameters:

atom_a (Atom) – The first Atom involved in the bond.
atom_b (Atom) – The second Atom involved in the bond.

Returns:

the corresponding Bond.

Return type:

Bond

get_dihedral(atom_a_id: int, atom_b_id: int, atom_c_id: int, atom_d_id: int) → Dihedral[source]

get_dihedral(atom_a_name: str, atom_b_name: str, atom_c_name: str, atom_d_name: str) → Dihedral

Getter method to retrieve a Dihedral in the Topology from the id’s of the four Atoms that share it.

Parameters:

atom_a_id (int) – The id of the first Atom involved in the dihedral.
atom_b_id (int) – The id of the second Atom involved in the dihedral.
atom_c_id (int) – The id of the third Atom involved in the dihedral.
atom_d_id (int) – The id of the fourth Atom involved in the dihedral.

Returns:

the corresponding Dihedral.

Return type:

Dihedral

get_former_atom(former_atom_id: int) → Atom[source]

Getter method to retrieve an Atom in the Topology from its ‘formerly’ attribute.

Parameters:: former_atom_id (int) – the former id (i.e. ‘formerly’ attribute) to retrieve an Atom.
Returns:: an Atom from the Topology with a matching ‘formerly’ attribute.
Return type:: Atom

get_pair(atom_a: Atom, atom_b: Atom) → Pair[source]

get_pair(atom_a_id: int, atom_b_id: int) → Pair

get_pair(atom_a_name: str, atom_b_name: str) → Pair

Getter method to retrieve a Pair in the Topology from the two Atoms that share it.

Parameters:

atom_a (Atom) – The first Atom involved in the pair.
atom_b (Atom) – The second Atom involved in the pair.

Returns:

the corresponding Pair.

Return type:

Pair

junction(monomer_atom_name: str, residue_atom_name: str, name: str = None) → Junction[source]

Additional method to create a Junction from atoms within this Topology.

For example: top = Topology.from_ITP(“file.itp”) junction1 = top.junction(“atomA”, “atomB”).named(“name”)

Instead of: junction1 = Junction(top.get_atom(“atomA”), top.get_atom(“atomB”), name=”name”)

Parameters:

monomer_atom_name (str) – the name of the Atom which will remain with Topology after polymerisation, and will obtain a new bond.
residue_atom_name (str) – the name of the Atom which will be lost during polymerisation, analogous to the leaving atom in a chemical reaction.
name (str, optional) – the unique name of the Junction type, defaults to None

Returns:

a new Junction

Return type:

Junction

max_atom_index() → dict[str, int][source]

Get the maximum atom index for each atom symbol/element in the Topology.

Returns:: a dictionary with each element assigned a value representing the highest index of all atoms of that element.
Return type:: dict[str, int]

max_residue_id() → int[source]

Get the maximum residue id in the Topology.

Returns:: the highest residue id of all atoms in the Topology.
Return type:: int

property name: str

Getter method to retrieve the Topology’s name.

Returns:: the name of the Topology, or “Unknown” if None.
Return type:: str

property netcharge: int

Getter method to retrieve the Topology’s net charge. The net charge is calculated as the sum of all of the Atom’s partial charges.

Returns:: the net charge of the Topology.
Return type:: int

classmethod numerically_order_oxygens(section: str, line: str) → str[source]

Preprocesses oxygen atoms with alphanumeric ordering to numeric ordering. For example: OD becomes O4.

Parameters:

instance (Topology) – the Topology class being called.
section (str) – the itp file section, for example “molecule”.
line (str) – a line from the itp file.

Returns:

the processed line with oxygen atoms renamed numerically.

Return type:

str

property pairs: List[Pair]

Getter method to retrieve the Topology’s Pairs.

Returns:: a list of all of the Pairs in this Topology.
Return type:: List[Pair]

proportional_charge_change(new_netcharge: float)[source]

Change the net charge of the molecular system by changing the partial harge of each atom proportionally.

Parameters:: new_netcharge (float) – value to adjust the partial charges by.

property pseudoatoms: dict[slice(<class 'int'>, <class 'polytop.Atoms.Atom'>, None)]

Getter method to retrieve the Topology’s pseudo atoms.

Returns:: a dictionary of the pseudo atoms in this Topology as values and their keys as their indexes.
Return type:: dict[int: Atom]

remove_atom(atom: Atom)[source]

Remove an Atom and all Bonds, Angles and Dihedrals associated with it. If the atom is not present, exception errors are ignored.

Parameters:: atom (Atom) – the Atom to be removed from the Topology

renumber_atoms(start: int)[source]

Renumber all of the atoms atom_id attributes to their current value plus the value of ‘start’. The existing order is maintained.

This is used when extending a polymer with a new monomer.

Note: this is the only function that sets the ‘formerly’ attribute of: an atom

Parameters:: start (int) – the value to offset the Atom’s ‘atom_id’ attributes by.

renumber_residues(starting_from: int)[source]

Renumber the residues by id in the topology starting from a given number. The order of the residues is maintained.

Parameters:

starting_from (int) – the starting number for the residues to be renumbered from, e.g. a value of ‘10’ means that the first residue will now have an id of 10, and the next an id of 11 and so forth.

Raises:

ValueError – if ‘starting_from’ is less than 1.
ValueError – if any existing residue_id is less than 1.

reorder_atom_indexes(atom_symbol: str, new_first_index: int)[source]

Renumber the atom indexes of all atoms of a given symbol (i.e. element) to start from a given index. The original order of these atoms is maintained.

Parameters:

atom_symbol (str) – the element of atoms to renumber, e.g. “C” to renumber all of the carbon atoms
new_first_index (int) – the starting number for the selected atoms to be renumbered from, e.g. a value of ‘10’ means that the first selected atom will now have an index of 10, and the next atom an index of 11 and so forth.

reorder_atoms()[source]: Renumber all of the atoms atom_id attributes starting from 1. The existing order is maintained.

property residue_id: int

Getter method to retrieve the Topology’s residue id. The residue id of the entire Topology is set to that of the first Atom.

Returns:: the residue id of the Topology.
Return type:: int

property residue_name: str

Getter method to retrieve the Topology’s residue name. The residue name of the entire Topology is set to that of the first Atom.

Returns:: the residue name of the Topology.
Return type:: str

reverse() → Topology[source]

Create a new Topology that is a copy of this Topology, except that the atoms are in the opposite order.

Returns:: the new, reverse order Topology.
Return type:: Topology

set_former_ids()[source]: Sets the ‘formerly’ attribute of all of the Atoms in the Topology to their current atom_id.

to_ITP(file_path: str)[source]

Write the Topology to a GROMACS ITP file of the desired forcefield format.

Parameters:: file_path (str) – the path to and the desired name of the GROMACS ITP file.

to_dict() → dict[source]

Convert this Topology to a dictionary representation.

The structure of the dictionary is as below: {“atoms”: [atom.to_dict() for atom in self.atoms], “bonds”: [bond.to_dict() for bond in self.bonds], “angles”: [angle.to_dict() for angle in self.angles], “dihedrals”: [dihedral.to_dict() for dihedral in self.dihedrals], “pairs”: [pair.to_dict() for pair in self.pairs], “exclusions”: [exclusion.to_dict() for exclusion in self.exclusions], “preamble”: self.preamble, “moleculetype”: self.molecule_type.to_dict()}

Returns:: a dictionary representation of this Topology’s attributes.
Return type:: dict