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, uint64_t resid)¶

Create a new residue with the given `name` and residue identifier `resid`. If the residue has no identifier, the special value of `uint64_t(-1)` should be used.

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

CHFL_RESIDUE* residue = chfl_residue("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 *const 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 *const 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 *const 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", 3);
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 *const 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", 3);

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 *const residue, uint64_t *id)¶

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

CHFL_RESIDUE* residue = chfl_residue("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 *const residue, uint64_t i)¶

Add the atom at index `i` in the `residue`.

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

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 *const 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", 3);
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_contains(const CHFL_RESIDUE *const 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", 3);

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_free(CHFL_RESIDUE *const residue)¶

Free the memory associated with a `residue`.

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

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

chfl_residue_free(residue);

Return

`CHFL_SUCCESS`