Function manipulating CHFL_TOPOLOGY

typedef struct CHFL_TOPOLOGY CHFL_TOPOLOGY

An opaque type handling a 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.

CHFL_TOPOLOGY *chfl_topology(void)

Create a new empty topology.

The caller of this function should free the associated memory using chfl_topology_free.

Return
A pointer to the topology, or NULL in case of error. You can use chfl_last_error to learn about the error.

const CHFL_TOPOLOGY *chfl_topology_from_frame(const CHFL_FRAME *frame)

Get access to the topology of a frame.

The frame will be kept alive, even if chfl_frame_free is called, until chfl_topology_free is also called on the pointer returned by this function.

If chfl_frame_set_topology is called, this pointer will point to the new topology.

Return
A pointer to the topology, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_TOPOLOGY *chfl_topology_copy(const CHFL_TOPOLOGY *topology)

Get a copy of a topology.

The caller of this function should free the associated memory using chfl_topology_free.

Return
A pointer to the new topology, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_topology_atoms_count(const CHFL_TOPOLOGY *topology, uint64_t *size)

Get the number of atoms in the topology in the integer pointed to by size.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_resize(CHFL_TOPOLOGY *topology, uint64_t natoms)

Resize the topology to hold natoms 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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_add_atom(CHFL_TOPOLOGY *topology, const CHFL_ATOM *atom)

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

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_remove(CHFL_TOPOLOGY *topology, uint64_t i)

Remove the atom at index i from a topology.

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

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_add_bond(CHFL_TOPOLOGY *topology, uint64_t i, uint64_t j)

Add a bond between the atoms at indexes i and j in the topology.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_remove_bond(CHFL_TOPOLOGY *topology, uint64_t i, uint64_t j)

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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_bonds_count(const CHFL_TOPOLOGY *topology, uint64_t *nbonds)

Get the number of bonds in the topology in nbonds.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_angles_count(const CHFL_TOPOLOGY *topology, uint64_t *nangles)

Get the number of angles in the topology in nangles.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_dihedrals_count(const CHFL_TOPOLOGY *topology, uint64_t *ndihedrals)

Get the number of dihedral angles in the topology in ndihedrals.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_impropers_count(const CHFL_TOPOLOGY *topology, uint64_t *nimpropers)

Get the number of improper dihedral angles in the topology in nimpropers.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_bonds(const CHFL_TOPOLOGY *topology, uint64_t (*data)[2], uint64_t nbonds)

Get the list of bonds in the topology in the pre-allocated array data of size nbonds.

data size must be passed in the nbonds parameter, and be equal to the result of chfl_topology_bonds_count. The bonds are sorted in the array.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_angles(const CHFL_TOPOLOGY *topology, uint64_t (*data)[3], uint64_t nangles)

Get the list of angles in the topology in the pre-allocated array data of size nangles.

data size must be passed in the nangles parameter, and be equal to the result of chfl_topology_angles_count. The angles are sorted in the array.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_dihedrals(const CHFL_TOPOLOGY *topology, uint64_t (*data)[4], uint64_t ndihedrals)

Get the list of dihedral angles in the topology in the pre-allocated array data of size ndihedrals.

data size must be passed in the ndihedrals parameter, and be equal to the result of chfl_topology_dihedrals_count. The dihedrals are sorted in the array.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_impropers(const CHFL_TOPOLOGY *topology, uint64_t (*data)[4], uint64_t nimpropers)

Get the list of improper dihedral angles in the topology in the pre-allocated array data of size nimpropers.

data size must be passed in the nimpropers parameter, and be equal to the result of chfl_topology_impropers_count. The impropers are sorted in the array.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_add_residue(CHFL_TOPOLOGY *topology, const CHFL_RESIDUE *residue)

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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_residues_count(const CHFL_TOPOLOGY *topology, uint64_t *residues)

Get the number of residues in the topology in the integer pointed to by residues.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_residues_linked(const CHFL_TOPOLOGY *topology, const CHFL_RESIDUE *first, const CHFL_RESIDUE *second, bool *result)

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, and store the result in result.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_bond_with_order(CHFL_TOPOLOGY *topology, uint64_t i, uint64_t j, chfl_bond_order bond_order)

Add a bond between the atoms at indexes i and j with bond order bond_order in the topology.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_bond_orders(const CHFL_TOPOLOGY *topology, chfl_bond_order orders[], uint64_t nbonds)

Get the list of bond orders in the topology in the pre-allocated array orders of size nbonds.

orders size must be passed in the nbonds parameter, and be equal to the result of chfl_topology_bond_count. The bond orders are sorted so the bond order of bond[i] is orders[i].

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_bond_order(const CHFL_TOPOLOGY *topology, uint64_t i, uint64_t j, chfl_bond_order *order)

Get a specific bond order in the topology in the chfl_bond_order pointed to by order

i and j must be valid atom indexes in the topology and a bond must exist between these two atoms.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_topology_free(const CHFL_TOPOLOGY *topology)

Free the memory associated with a topology.

Return
CHFL_SUCCESS