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.

CHFL_TOPOLOGY* topology = chfl_topology();

if (topology == NULL) {
    /* handle error */
}

chfl_free(topology);

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.

CHFL_FRAME* frame = chfl_frame();
const CHFL_TOPOLOGY* topology = chfl_topology_from_frame(frame);

if (topology == NULL) {
    /* handle error */
}

chfl_free(topology);
chfl_free(frame);

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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_free(atom);

CHFL_TOPOLOGY* copy = chfl_topology_copy(topology);

if (copy == NULL) {
    /* handle error */
}

chfl_free(copy);
chfl_free(topology);

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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_free(atom);

uint64_t atoms = 0;
chfl_topology_atoms_count(topology, &atoms);
assert(atoms == 3);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

chfl_topology_resize(topology, 67);

uint64_t atoms = 0;
chfl_topology_atoms_count(topology, &atoms);
assert(atoms == 67);

chfl_free(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_add_atom(CHFL_TOPOLOGY *topology, const CHFL_ATOM *atom)

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

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* O = chfl_atom("O");
CHFL_ATOM* H = chfl_atom("H");

chfl_topology_add_atom(topology, O);
chfl_topology_add_atom(topology, H);
chfl_topology_add_atom(topology, H);

chfl_free(O);
chfl_free(H);

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

CHFL_TOPOLOGY* topology = chfl_topology();

// Add a fex atoms to the topology
CHFL_ATOM* O = chfl_atom("O");
CHFL_ATOM* H = chfl_atom("H");
chfl_topology_add_atom(topology, O);
chfl_topology_add_atom(topology, H);
chfl_topology_add_atom(topology, H);
chfl_topology_add_atom(topology, O);
chfl_free(O);
chfl_free(H);

uint64_t atoms = 0;
chfl_topology_atoms_count(topology, &atoms);
assert(atoms == 4);

chfl_topology_remove(topology, 2);

chfl_topology_atoms_count(topology, &atoms);
assert(atoms == 3);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);

uint64_t bonds = 0;
chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 1);

chfl_free(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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 2, 3);

uint64_t bonds = 0;
chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 3);

chfl_topology_remove_bond(topology, 1, 2);

chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 2);

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

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

CHFL_TOPOLOGY* topology = chfl_topology();
CHFL_ATOM* atom = chfl_atom("C");

chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);
chfl_topology_add_atom(topology, atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 2, 1);

uint64_t bonds = 0;
chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 2);

chfl_topology_clear_bonds(topology);
chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 0);

chfl_free(atom);
chfl_free(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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 2, 3);

uint64_t bonds = 0;
chfl_topology_bonds_count(topology, &bonds);
assert(bonds == 2);

chfl_free(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_angles_count(const CHFL_TOPOLOGY *topology, uint64_t *count)

Get the number of angles in the topology in count.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

// We have two angles: 0-1-2 and 1-2-3
chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 2, 3);

uint64_t angles = 0;
chfl_topology_angles_count(topology, &angles);
assert(angles == 2);

chfl_free(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_dihedrals_count(const CHFL_TOPOLOGY *topology, uint64_t *count)

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

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

// We have one dihedral angle: 0-1-2-3
chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 2, 3);

uint64_t dihedrals = 0;
chfl_topology_dihedrals_count(topology, &dihedrals);
assert(dihedrals == 1);

chfl_free(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_impropers_count(const CHFL_TOPOLOGY *topology, uint64_t *count)

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

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 1, 0);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 1, 3);

uint64_t impropers = 0;
chfl_topology_impropers_count(topology, &impropers);
assert(impropers == 1);

chfl_free(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(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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 2, 3);

uint64_t bonds[2][2] = {{0}};
chfl_topology_bonds(topology, bonds, 2);
assert(bonds[0][0] == 0);
assert(bonds[0][1] == 1);

assert(bonds[1][0] == 2);
assert(bonds[1][1] == 3);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 2, 3);

uint64_t angles[2][3] = {{0}};
chfl_topology_angles(topology, angles, 2);
assert(angles[0][0] == 0);
assert(angles[0][1] == 1);
assert(angles[0][2] == 2);

assert(angles[1][0] == 1);
assert(angles[1][1] == 2);
assert(angles[1][2] == 3);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 0, 1);
chfl_topology_add_bond(topology, 1, 2);
chfl_topology_add_bond(topology, 2, 3);

uint64_t dihedrals[1][4] = {{0}};
chfl_topology_dihedrals(topology, dihedrals, 1);
assert(dihedrals[0][0] == 0);
assert(dihedrals[0][1] == 1);
assert(dihedrals[0][2] == 2);
assert(dihedrals[0][3] == 3);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_add_bond(topology, 3, 0);
chfl_topology_add_bond(topology, 3, 1);
chfl_topology_add_bond(topology, 3, 2);

uint64_t impropers[1][4] = {{0}};
chfl_topology_impropers(topology, impropers, 1);
assert(impropers[0][0] == 0);
assert(impropers[0][1] == 3);
assert(impropers[0][2] == 1);
assert(impropers[0][3] == 2);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();
CHFL_RESIDUE* residue = chfl_residue("res");

chfl_topology_add_residue(topology, residue);

chfl_free(residue);
chfl_free(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_residues_count(const CHFL_TOPOLOGY *topology, uint64_t *count)

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

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_RESIDUE* residue = chfl_residue("res");
chfl_topology_add_residue(topology, residue);
chfl_free(residue);

uint64_t residues = 0;
chfl_topology_residues_count(topology, &residues);
assert(residues == 1);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

// Build the topology ...

const CHFL_RESIDUE* first = chfl_residue_from_topology(topology, 0);
const CHFL_RESIDUE* second = chfl_residue_from_topology(topology, 1);

bool linked = false;
chfl_topology_residues_linked(topology, first, second, &linked);

chfl_free(first);
chfl_free(second);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_bond_with_order(topology, 0, 1, CHFL_BOND_SINGLE);
chfl_topology_bond_with_order(topology, 2, 3, CHFL_BOND_DOUBLE);

chfl_bond_order bond_orders[2] = {0};
chfl_topology_bond_orders(topology, bond_orders, 2);
assert(bond_orders[0] == CHFL_BOND_SINGLE);

chfl_bond_order order;
chfl_topology_bond_order(topology, 2, 3, &order);
assert(order == CHFL_BOND_DOUBLE);

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

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_bond_with_order(topology, 0, 1, CHFL_BOND_SINGLE);
chfl_topology_bond_with_order(topology, 2, 3, CHFL_BOND_DOUBLE);

chfl_bond_order bond_orders[2] = {0};
chfl_topology_bond_orders(topology, bond_orders, 2);
assert(bond_orders[0] == CHFL_BOND_SINGLE);

chfl_bond_order order;
chfl_topology_bond_order(topology, 2, 3, &order);
assert(order == CHFL_BOND_DOUBLE);

chfl_free(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_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.

CHFL_TOPOLOGY* topology = chfl_topology();

CHFL_ATOM* atom = chfl_atom("F");
for (size_t i=0; i<5; i++) {
    chfl_topology_add_atom(topology, atom);
}
chfl_free(atom);

chfl_topology_bond_with_order(topology, 0, 1, CHFL_BOND_SINGLE);
chfl_topology_bond_with_order(topology, 2, 3, CHFL_BOND_DOUBLE);

chfl_bond_order bond_orders[2] = {0};
chfl_topology_bond_orders(topology, bond_orders, 2);
assert(bond_orders[0] == CHFL_BOND_SINGLE);

chfl_bond_order order;
chfl_topology_bond_order(topology, 2, 3, &order);
assert(order == CHFL_BOND_DOUBLE);

chfl_free(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.