chfl_topology type

type  chfl_topology

A chfl_topology contains the definition of all the atoms in the system, and the liaisons between the atoms (bonds, angles, dihedrals, …). It will also contain all the residues information if it is available.

Type fields:
subroutine  chfl_topology%init([status])

Initialize this topology with a new empty topology. This subroutine allocate memory which must be released with chfl_topology%free().

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%copy(topology[, status])

Initialize this topology with a copy of topology. This subroutine allocate memory which must be released with chfl_topology%free().

Parameters:

topology [type(chfl_topology)] :: topology to copy

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%atoms_count([status])

Get the number of atoms in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%resize(count[, status])

Resize the topology to hold count atoms. If the new number of atoms is bigger than the current number, new atoms will be created with an empty name and type. If it is lower than the current number of atoms, the last atoms will be removed, together with the associated bonds, angles and dihedrals.

Parameters:

count [integer] :: new size of the topology

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%add_atom(atom[, status])

Add a copy of atom at the end of the topology.

Parameters:

atom [type(chfl_atom)] :: atom to be added

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%atom(index[, status])

Get access to the atom at the given index from this topology

Any modification to the atom will be reflected in the topology. The topology will be kept alive, even if chfl_topology%free() is called, until chfl_atom%free() is also called on the atom returned by this function.

The atom returned by this function is a pointer that points directly inside the topology, and will be invalidated if any of the following function is called on the topology:

Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_atom%free.

Return:

type (chfl_atom)

Parameters:

index [integer] :: index of the atom to retrieve

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%remove(index[, status])

Remove the atom at the given index from the topology.

This shifts all the atoms indexes after index by 1 (n becomes n-1).

Parameters:

index [integer] :: index of the atom to remove

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%bonds_count([status])

Get the number of bonds in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%angles_count([status])

Get the number of angles in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%dihedrals_count([status])

Get the number of dihedral angles in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%impropers_count([status])

Get the number of improper dihedral angles in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%bonds(data[, status])

Get the list of bonds in the topology in the pre-allocated array data of shape [2, chfl_topology%bonds_count()].

Parameters:

data (2, :) [integer] :: array to be filled with the bonds in the system

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%angles(data[, status])

Get the list of angles in the topology in the pre-allocated array data of shape [3, chfl_topology%angles_count()].

Parameters:

data (3, :) [integer] :: array to be filled with the angles in the system

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%dihedrals(data[, status])

Get the list of dihedral angles in the topology in the pre-allocated array data of shape [4, chfl_topology%dihedrals_count()].

Parameters:

data (4, :) [integer] :: array to be filled with the dihedral angles in the system

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%impropers(data[, status])

Get the list of improper dihedral angles in the topology in the pre-allocated array data of shape [4, chfl_topology%impropers_count()].

Parameters:

data (4, :) [integer] :: array to be filled with the dihedral angles in the system

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%add_bond(i, j[, bond_order, status])

Add a bond between the atoms at indexes i and j in the topology, and optionaly set the bond_order. By default, a bond order of CHFL_BOND_UNKNOWN is used.

Possible bond orders are represented by an integer of kind chfl_bond_order.

Parameters:

  • i [integer] :: atomic index of the first atom of the bond

  • j [integer] :: atomic index of the second atom of the bond

Options:
chfl_bond_order [integer]

Kind parameter for integers representing bond orders.

CHFL_BOND_UNKNOWN [integer(chfl_bond_order)]

This bond order is used when the actual bond order is unkown or unspecified in the input file format.

CHFL_BOND_SINGLE [integer(chfl_bond_order)]

Bond order for single bonds

CHFL_BOND_DOUBLE [integer(chfl_bond_order)]

Bond order for double bonds

CHFL_BOND_TRIPLE [integer(chfl_bond_order)]

Bond order for triple bonds

CHFL_BOND_QUADRUPLE [integer(chfl_bond_order)]

Bond order for quadruple bond (present in some metals)

CHFL_BOND_QINTUPLET [integer(chfl_bond_order)]

Bond order for quintuplet bond (present in some metals)

CHFL_BOND_AMIDE [integer(chfl_bond_order)]

Bond order for amide bonds

CHFL_BOND_AROMATIC [integer(chfl_bond_order)]

Bond order for aromatic bonds

subroutine  chfl_topology%remove_bond(i, j[, status])

Remove any existing bond between the atoms at indexes i and j in the topology.

This function does nothing if there is no bond between i and j.

Parameters:

  • i [integer] :: The atomic index of the first atom

  • j [integer] :: The atomic index of the second atom

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%clear_bonds([status])

Remove all bonds in this topology.

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%add_bond(i, j[, bond_order, status])

Add a bond between the atoms at indexes i and j in the topology, and optionaly set the bond_order. By default, a bond order of CHFL_BOND_UNKOWN is used.

Possible bond orders are represented by an integer of kind chfl_bond_order.

Parameters:

  • i [integer] :: atomic index of the first atom of the bond

  • j [integer] :: atomic index of the second atom of the bond

Options:
function  chfl_topology%bond_order(i, j[, status])

Get the bond order for the bond between atoms at indexes i and j.

Return:

integer (chfl_bond_order)

Parameters:

  • i [integer] :: atomic index of the first atom of the bond

  • j [integer] :: atomic index of the second atom of the bond

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%bond_orders(data[, status])

Get the bond order for all bonds in the system in the pre-allocated array data. This array must have room for chfl_topology%bonds_count() elements.

Parameters:

data (:) [integer(chfl_bond_order)] :: Array to be filled with the bond order of all bonds in the system.

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%residues_count(natoms[, status])

Get the number of residues in the topology.

Return:

integer

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%add_residue(residue[, status])

Add a copy of residue to this topology.

The residue id must not already be in the topology, and the residue must contain only atoms that are not already in another residue.

Parameters:

residue [type(chfl_residue)] :: residue to add in the topology

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%residue(index[, status])

Get read-only access to the residue at the given index in this topology. Trying to write to the residue will give an error.

If the index is bigger than the result of chfl_topology%residues_count(), this function will return an invalid chfl_residue and set status to CHFL_MEMORY_ERROR.

The residue index in the topology is not always the same as the residue id.

The topology will be kept alive, even if chfl_topology%free() is called, until chfl_residue%free() is also called on the residue returned by this function, unless the this function returns an invalid residue.

The residue returned by this function is a pointer that points directly inside the topology, and will be invalidated if chfl_topology%add_residue() is called. Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_residue%free().

Return:

type (chfl_residue)

Parameters:

index [integer] :: Index of the residue in the topology. This is NOT the same thing as the residue id.

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%residue_for_atom(index[, status])

Get read-only access to the residue containing the atom at the given index in this topology. Trying to write to the residue will give an error.

This function will return an invalid invalid chfl_residue and set status to CHFL_MEMORY_ERROR if the atom is not in a residue, or if the index is bigger than chfl_topology%atoms_count().

The topology will be kept alive, even if chfl_topology%free() is called, until chfl_residue%free() is also called on the residue returned by this function.

The residue returned by this function is a pointer that points directly inside the topology, and will be invalidated if chfl_topology%add_residue() is called. Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_residue%free().

Return:

type (chfl_residue)

Parameters:

index [integer] :: index of the atom in the topology.

Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

function  chfl_topology%residues_linked(first, second[, status])

Check if the two residues first and second from the topology are linked together, i.e. if there is a bond between one atom in the first residue and one atom in the second one.

Return:

logical

Parameters:
Options:

status [integer(chfl_status)] :: status code of the operation. If it is not CHFL_SUCCESS, use chfl_last_error() to learn more about the error.

subroutine  chfl_topology%free()

Destroy a topology, and free the associated memory