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:
% init [subroutine] ::
chfl_topology%init()
% copy [subroutine] ::
chfl_topology%copy()
% atoms_count [function] ::
chfl_topology%atoms_count()
% add_atom [subroutine] ::
chfl_topology%add_atom()
% atom [function] ::
chfl_topology%atom()
% resize [subroutine] ::
chfl_topology%resize()
% remove [subroutine] ::
chfl_topology%remove()
% add_bond [subroutine] ::
chfl_topology%add_bond()
% remove_bond [subroutine] ::
chfl_topology%remove_bond()
% clear_bonds [subroutine] ::
chfl_topology%clear_bonds()
% bond_order [function] ::
chfl_topology%bond_order()
% bond_orders [subroutine] ::
chfl_topology%bond_orders()
% bonds_count [function] ::
chfl_topology%bonds_count()
% angles_count [function] ::
chfl_topology%angles_count()
% dihedrals_count [function] ::
chfl_topology%dihedrals_count()
% impropers_count [function] ::
chfl_topology%impropers_count()
% bonds [subroutine] ::
chfl_topology%bonds()
% angles [subroutine] ::
chfl_topology%angles()
% dihedrals [subroutine] ::
chfl_topology%dihedrals()
% impropers [subroutine] ::
chfl_topology%impropers()
% residues_count [function] ::
chfl_topology%residues_count()
% add_residue [subroutine] ::
chfl_topology%add_residue()
% residue [function] ::
chfl_topology%residue()
% residue_for_atom [function] ::
chfl_topology%residue_for_atom()
% residues_linked [function] ::
chfl_topology%residues_linked()
% free [subroutine] ::
chfl_topology%free()
- 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
, usechfl_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 withchfl_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
, usechfl_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
, usechfl_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
, usechfl_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
, usechfl_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 topologyAny modification to the atom will be reflected in the topology. The topology will be kept alive, even if
chfl_topology%free()
is called, untilchfl_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
, usechfl_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
, usechfl_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
, usechfl_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
, usechfl_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
, usechfl_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
, usechfl_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
, usechfl_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 arraydata
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
, usechfl_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
, usechfl_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
, usechfl_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
andj
in the topology, and optionaly set thebond_order
. By default, a bond order ofCHFL_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:
bond_order [integer(chfl_bond_order)] :: order of the bond
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
- 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
andj
in the topology.This function does nothing if there is no bond between
i
andj
.- 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
, usechfl_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
, usechfl_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
andj
in the topology, and optionaly set thebond_order
. By default, a bond order ofCHFL_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:
bond_order [integer(chfl_bond_order)] :: order of the bond
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
- function chfl_topology%bond_order(i, j[, status])¶
Get the bond order for the bond between atoms at indexes
i
andj
.- 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
, usechfl_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 forchfl_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
, usechfl_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
, usechfl_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
, usechfl_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 ofchfl_topology%residues_count()
, this function will return an invalidchfl_residue
and setstatus
toCHFL_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, untilchfl_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 withchfl_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
, usechfl_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 setstatus
toCHFL_MEMORY_ERROR
if the atom is not in a residue, or if theindex
is bigger thanchfl_topology%atoms_count()
.The topology will be kept alive, even if
chfl_topology%free()
is called, untilchfl_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 withchfl_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
, usechfl_last_error()
to learn more about the error.
- function chfl_topology%residues_linked(first, second[, status])¶
Check if the two residues
first
andsecond
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:
first [type(chfl_residue)] :: first residue
second [type(chfl_residue)] :: second residue
- Options:
status [integer(chfl_status)] :: status code of the operation. If it is not
CHFL_SUCCESS
, usechfl_last_error()
to learn more about the error.
- subroutine chfl_topology%free()¶
Destroy a topology, and free the associated memory