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.

Here is the full list of functions acting on CHFL_RESIDUE:

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

CHFL_RESIDUE* residue = chfl_residue("ALA");

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

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

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

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

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

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

Get access to 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 topology will be kept alive, even if chfl_free(topology) is called, until chfl_free is also called on the pointer returned by this function.

The pointer returned by this function points directly inside the topology, and will be invalidated if any of the following function is called on the topology or the frame containing the topology:

  • chfl_frame_add_residue
  • chfl_topology_add_residue

Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_free.

CHFL_TOPOLOGY* topology = chfl_topology();

// Build topology ...

const CHFL_RESIDUE* residue = chfl_residue_for_atom(topology, 3);

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

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

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

Get access to the residue at index i in 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 topology will be kept alive, even if chfl_free(topology) is called, until chfl_free is also called on the pointer returned by this function, unless the pointer returned by this function is NULL.

The pointer returned by this function points directly inside the topology, and will be invalidated if any of the following function is called on the topology or the frame containing the topology:

  • chfl_frame_add_residue
  • chfl_topology_add_residue

Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_free.

CHFL_TOPOLOGY* topology = chfl_topology();

// Build topology ...

const CHFL_RESIDUE* residue = chfl_residue_from_topology(topology, 3);

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

chfl_free(residue);
chfl_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_free.

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

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

chfl_free(copy);
chfl_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_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_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_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 *count)

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

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_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_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_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_free(property);

property = chfl_residue_get_property(residue, "this");

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

chfl_free(property);
chfl_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_free function.

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

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

property = chfl_residue_get_property(residue, "this");

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

chfl_free(property);
chfl_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_properties_count(const CHFL_RESIDUE *residue, uint64_t *count)

Get the number of properties associated with this residue in count.

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

chfl_residue_set_property(residue, "this", property);
chfl_residue_set_property(residue, "that", property);
chfl_free(property);

uint64_t count = 0;
chfl_residue_properties_count(residue, &count);
assert(count == 2);

chfl_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_list_properties(const CHFL_RESIDUE *residue, const char *names[], uint64_t count)

Get the names of all properties of this residue in the pre-allocated array names of size count.

names size must be passed in the count parameter, and be equal to the result of chfl_residue_properties_count.

The pointers in names are only valid until a new property is added to the residue with chfl_residue_set_property.

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

chfl_residue_set_property(residue, "this", property);
chfl_residue_set_property(residue, "that", property);
chfl_free(property);

uint64_t count = 0;
chfl_residue_properties_count(residue, &count);
assert(count == 2);

const char* names[2] = {NULL};
chfl_residue_list_properties(residue, names, count);

// Properties are not ordered
assert(strcmp(names[0], "this") == 0 || strcmp(names[0], "that") == 0);
assert(strcmp(names[1], "this") == 0 || strcmp(names[1], "that") == 0);

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