Function manipulating CHFL_RESIDUE

typedef struct CHFL_RESIDUE CHFL_RESIDUE

An opaque type handling a residue.

A CHFL_RESIDUE is a group of atoms belonging to the same logical unit. They can be small molecules, amino-acids in a protein, monomers in polymers, etc.

CHFL_RESIDUE *chfl_residue(const char *name)

Create a new residue with the given name.

The caller of this function should free the allocated memory using chfl_residue_free.

CHFL_RESIDUE* residue = chfl_residue("ALA");

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

chfl_residue_free(residue);
Return
A pointer to the residue, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_RESIDUE *chfl_residue_with_id(const char *name, uint64_t resid)

Create a new residue with the given name and residue identifier resid.

The caller of this function should free the allocated memory using chfl_residue_free.

CHFL_RESIDUE* residue = chfl_residue_with_id("water", 3);

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

chfl_residue_free(residue);
Return
A pointer to the residue, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_RESIDUE *chfl_residue_for_atom(const CHFL_TOPOLOGY *topology, uint64_t i)

Get a copy of the residue containing the atom at index i in the topology.

This function will return NULL if the atom is not in a residue, or if the index i is bigger than chfl_topology_atoms_count.

The caller of this function should free the allocated memory using chfl_residue_free.

CHFL_TOPOLOGY* topology = chfl_topology();

// Build topology ...

CHFL_RESIDUE* residue = chfl_residue_for_atom(topology, 3);

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

chfl_residue_free(residue);
chfl_topology_free(topology);
Return
A pointer to the residue, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_RESIDUE *chfl_residue_from_topology(const CHFL_TOPOLOGY *topology, uint64_t i)

Get a copy of the residue at index i from a topology.

If i is bigger than the result of chfl_topology_residues_count, this function will return NULL.

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

The caller of this function should free the allocated memory using chfl_residue_free.

CHFL_TOPOLOGY* topology = chfl_topology();

// Build topology ...

CHFL_RESIDUE* residue = chfl_residue_from_topology(topology, 3);

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

chfl_residue_free(residue);
chfl_topology_free(topology);
Return
A pointer to the residue, or NULL in case of error. You can use chfl_last_error to learn about the error.

CHFL_RESIDUE *chfl_residue_copy(const CHFL_RESIDUE *residue)

Get a copy of a residue.

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

CHFL_RESIDUE* residue = chfl_residue("water");
CHFL_RESIDUE* copy = chfl_residue_copy(residue);

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

chfl_residue_free(copy);
chfl_residue_free(residue);
Return
A pointer to the new residue, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_residue_name(const CHFL_RESIDUE *residue, char *name, uint64_t buffsize)

Get the name of a residue in the string buffer name.

The buffer size must be passed in buffsize. This function will truncate the residue name to fit in the buffer.

CHFL_RESIDUE* residue = chfl_residue("water");

char name[32] = {0};
chfl_residue_name(residue, name, sizeof(name));
assert(strcmp(name, "water") == 0);

chfl_residue_free(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_residue_id(const CHFL_RESIDUE *residue, uint64_t *id)

Get the identifier of a residue in the initial topology file in the integer pointed to by id.

This function will return CHFL_GENERIC_ERROR if this residue does not have an associated identifier.

CHFL_RESIDUE* residue = chfl_residue_with_id("water", 3);

uint64_t id = 0;
chfl_residue_id(residue, &id);
assert(id == 3);

chfl_residue_free(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_residue_add_atom(CHFL_RESIDUE *residue, uint64_t i)

Add the atom at index i in the residue.

CHFL_RESIDUE* residue = chfl_residue("water");

chfl_residue_add_atom(residue, 0);
chfl_residue_add_atom(residue, 32);
chfl_residue_add_atom(residue, 28);

chfl_residue_free(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_residue_atoms_count(const CHFL_RESIDUE *residue, uint64_t *size)

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

CHFL_RESIDUE* residue = chfl_residue("water");
chfl_residue_add_atom(residue, 0);
chfl_residue_add_atom(residue, 32);
chfl_residue_add_atom(residue, 28);

uint64_t atoms = 0;
chfl_residue_atoms_count(residue, &atoms);
assert(atoms == 3);

chfl_residue_free(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_residue_atoms(const CHFL_RESIDUE *residue, uint64_t atoms[], uint64_t natoms)

Get the list of atoms in the residue in the pre-allocated array atoms of size natoms.

The atoms array size must be passed in the natoms parameter, and be equal to the result of chfl_residue_atoms_count. The atoms array is sorted.

CHFL_RESIDUE* residue = chfl_residue("water");
chfl_residue_add_atom(residue, 0);
chfl_residue_add_atom(residue, 32);
chfl_residue_add_atom(residue, 28);

uint64_t atoms[3] = {0};
chfl_residue_atoms(residue, atoms, 3);
assert(atoms[0] == 0);
assert(atoms[1] == 28);
assert(atoms[2] == 32);

chfl_residue_free(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_residue_contains(const CHFL_RESIDUE *residue, uint64_t i, bool *result)

Check if the atom at index i is in the residue, and store the result in result.

CHFL_RESIDUE* residue = chfl_residue("water");

chfl_residue_add_atom(residue, 0);
chfl_residue_add_atom(residue, 32);
chfl_residue_add_atom(residue, 28);

bool contained = false;
chfl_residue_contains(residue, 32, &contained);
assert(contained == true);

chfl_residue_contains(residue, 11, &contained);
assert(contained == false);

chfl_residue_free(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_residue_set_property(CHFL_RESIDUE *residue, const char *name, const CHFL_PROPERTY *property)

Add a new property with the given name to this residue.

If a property with the same name already exists, this function override the existing property with the new one.

CHFL_RESIDUE* residue = chfl_residue("ASP");
CHFL_PROPERTY* property = chfl_property_double(-23);

chfl_residue_set_property(residue, "this", property);
chfl_property_free(property);

property = chfl_residue_get_property(residue, "this");

double value = 0;
chfl_property_get_double(property, &value);
assert(value == -23);

chfl_property_free(property);
chfl_residue_free(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_PROPERTY *chfl_residue_get_property(const CHFL_RESIDUE *residue, const char *name)

Get a property with the given name in this residue.

This function returns NULL if no property exists with the given name.

The user of this function is responsible to deallocate memory using the chfl_property_free function.

CHFL_RESIDUE* residue = chfl_residue("ASP");
CHFL_PROPERTY* property = chfl_property_double(-23);

chfl_residue_set_property(residue, "this", property);
chfl_property_free(property);

property = chfl_residue_get_property(residue, "this");

double value = 0;
chfl_property_get_double(property, &value);
assert(value == -23);

chfl_property_free(property);
chfl_residue_free(residue);
Return
A pointer to the property, or NULL in case of error. You can use chfl_last_error to learn about the error.

chfl_status chfl_residue_free(CHFL_RESIDUE *residue)

Free the memory associated with a residue.

CHFL_RESIDUE* residue = chfl_residue("ALA");

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

chfl_residue_free(residue);
Return
CHFL_SUCCESS