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.

Here is the full list of functions acting on CHFL_TOPOLOGY:

• chfl_topology()

• chfl_topology_from_frame()

• chfl_topology_copy()

• chfl_topology_atoms_count()

• chfl_topology_resize()

• chfl_topology_add_atom()

• chfl_topology_remove()

• chfl_topology_add_bond()

• chfl_topology_remove_bond()

• chfl_topology_clear_bonds()

• chfl_topology_bonds_count()

• chfl_topology_angles_count()

• chfl_topology_dihedrals_count()

• chfl_topology_impropers_count()

• chfl_topology_bonds()

• chfl_topology_angles()

• chfl_topology_dihedrals()

• chfl_topology_impropers()

• chfl_topology_add_residue()

• chfl_topology_residues_count()

• chfl_topology_residues_linked()

• chfl_topology_bond_with_order()

• chfl_topology_bond_orders()

• chfl_topology_bond_order()

---

CHFL_TOPOLOGY *chfl_topology(void)

Create a new empty topology.

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

Returns:

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_free(frame) is called, until chfl_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.

Returns:

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_free.

Returns:

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 *count)

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

Returns:

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.

Returns:

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.

Returns:

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).

Returns:

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.

Returns:

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.

Returns:

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_clear_bonds(CHFL_TOPOLOGY *topology)

Remove all existing bonds, angles, dihedral angles and improper dihedral angles in the topology.

Returns:

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 *count)

Get the number of bonds in the topology in count.

Returns:

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 *count)

Get the number of angles in the topology in count.

Returns:

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 *count)

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

Returns:

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 *count)

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

Returns:

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 count)

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

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

Returns:

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 count)

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

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

Returns:

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 count)

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

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

Returns:

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 count)

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

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

Returns:

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.

Returns:

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 *count)

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

Returns:

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.

Returns:

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.

Returns:

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].

Returns:

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.

Returns:

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