Function manipulating `CHFL_ATOM`¶

typedef struct CHFL_ATOM CHFL_ATOM¶

An opaque type handling an atom.

A `CHFL_ATOM` is a particle in the current `CHFL_FRAME`. It stores the following atomic properties:

atom name;
atom type;
atom mass;
atom charge.

The atom name is usually an unique identifier (`”H1”`, `”C_a”`) while the atom type will be shared between all particles of the same type: `”H”`, `”Ow”`, `”CH3”`.

CHFL_ATOM *chfl_atom(const char *name)¶

Create an atom with the given `name`, and set the atom type to `name`.

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

CHFL_ATOM* atom = chfl_atom("Na");

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

chfl_atom_free(atom);

Return: A pointer to the atom, or NULL in case of error. You can use `chfl_last_error` to learn about the error.

CHFL_ATOM *chfl_atom_from_frame(const CHFL_FRAME *const frame, uint64_t i)¶

Get a copy of the atom at index `i` from a `frame`

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

CHFL_FRAME* frame = chfl_frame();
/* Update the frame, or read it from a file */
chfl_frame_resize(frame, 5);

CHFL_ATOM* atom = chfl_atom_from_frame(frame, 4);

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

chfl_atom_free(atom);
chfl_frame_free(frame);

Return: A pointer to the atom, or NULL in case of error or if `i` is out of bounds. You can use `chfl_last_error` to learn about the error.

CHFL_ATOM *chfl_atom_from_topology(const CHFL_TOPOLOGY *const topology, uint64_t i)¶

Get a copy of the atom at index `i` from a `topology`

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

CHFL_TOPOLOGY* topology = chfl_topology();
/* Update the topology by hand, or using a file */

CHFL_ATOM* atom = chfl_atom_from_topology(topology, 4);

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

chfl_atom_free(atom);
chfl_topology_free(topology);

Return: A pointer to the atom, or NULL in case of error or if `i` is out of bounds. You can use `chfl_last_error` to learn about the error.

CHFL_ATOM *chfl_atom_copy(const CHFL_ATOM *const atom)¶

Get a copy of an `atom`.

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

CHFL_ATOM* atom = chfl_atom("Na");
CHFL_ATOM* copy = chfl_atom_copy(atom);

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

chfl_atom_free(copy);
chfl_atom_free(atom);

Return: A pointer to the new atom, or NULL in case of error. You can use `chfl_last_error` to learn about the error.

chfl_status chfl_atom_mass(const CHFL_ATOM *const atom, double *mass)¶

Get the mass of an `atom`, in the double pointed to by `mass`.

The mass is given in atomic mass units.

CHFL_ATOM* atom = chfl_atom("Na");

double mass = 0;
chfl_atom_mass(atom, &mass);
assert(fabs(mass - 22.98976928) < 1e-15);

chfl_atom_free(atom);

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_atom_set_mass(CHFL_ATOM *const atom, double mass)¶

Set the mass of an `atom` to `mass`.

The mass must be in atomic mass units.

CHFL_ATOM* atom = chfl_atom("H");

chfl_atom_set_mass(atom, 1.45);

double mass = 0;
chfl_atom_mass(atom, &mass);
assert(fabs(mass - 1.45) < 1e-15);

chfl_atom_free(atom);

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_atom_charge(const CHFL_ATOM *const atom, double *charge)¶

Get the charge of an `atom`, in the double pointed to by `charge`.

The charge is in number of the electron charge *e*.

CHFL_ATOM* atom = chfl_atom("Na");

double charge = 0;
chfl_atom_charge(atom, &charge);
assert(charge == 0);

chfl_atom_free(atom);

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_atom_set_charge(CHFL_ATOM *const atom, double charge)¶

Set the charge of an `atom` to `charge`.

The charge must be in number of the electron charge *e*.

CHFL_ATOM* atom = chfl_atom("H");

chfl_atom_set_charge(atom, 0.82);

double charge = 0;
chfl_atom_charge(atom, &charge);
assert(fabs(charge - 0.82) < 1e-15);

chfl_atom_free(atom);

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_atom_name(const CHFL_ATOM *const atom, char *const name, uint64_t buffsize)¶

Get the name of an `atom` in the string buffer `name`.

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

CHFL_ATOM* atom = chfl_atom("Na");

char name[32] = {0};
chfl_atom_name(atom, name, sizeof(name));
assert(strcmp(name, "Na") == 0);

chfl_atom_free(atom);

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_atom_set_name(CHFL_ATOM *const atom, const char *name)¶

Set the name of an `atom` to `name`.

`name` must be a null terminated string.

CHFL_ATOM* atom = chfl_atom("Na");

chfl_atom_set_name(atom, "Cs");

char name[32] = {0};
chfl_atom_name(atom, name, sizeof(name));
assert(strcmp(name, "Cs") == 0);

chfl_atom_free(atom);

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_atom_type(const CHFL_ATOM *const atom, char *const type, uint64_t buffsize)¶

Get the type of an `atom` in the string buffer `type`.

The buffer size must be passed in `buffsize`. This function will truncate the atomic type to fit in the buffer.

CHFL_ATOM* atom = chfl_atom("Na");

char type[32] = {0};
chfl_atom_type(atom, type, sizeof(type));
assert(strcmp(type, "Na") == 0);

chfl_atom_free(atom);

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_atom_set_type(CHFL_ATOM *const atom, const char *type)¶

Set the type of an `atom` to `type`.

`type` must be a null terminated string.

CHFL_ATOM* atom = chfl_atom("Na");

chfl_atom_set_type(atom, "Cs");

char type[32] = {0};
chfl_atom_type(atom, type, sizeof(type));
assert(strcmp(type, "Cs") == 0);

chfl_atom_free(atom);

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_atom_full_name(const CHFL_ATOM *const atom, char *const name, uint64_t buffsize)¶

Get the full name of an `atom` from its type in the string buffer `name`

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

CHFL_ATOM* atom = chfl_atom("Na");

char name[32] = {0};
chfl_atom_full_name(atom, name, sizeof(name));
assert(strcmp(name, "Sodium") == 0);

chfl_atom_free(atom);

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_atom_vdw_radius(const CHFL_ATOM *const atom, double *radius)¶

Get the Van der Waals radius of an `atom` from the atom type, in the double pointed to by `radius`.

If the radius in unknown, this function set `radius` to -1.

CHFL_ATOM* atom = chfl_atom("Na");

double radius = 0;
chfl_atom_vdw_radius(atom, &radius);
assert(fabs(radius - 2.4) < 1e-15);

chfl_atom_free(atom);

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_atom_covalent_radius(const CHFL_ATOM *const atom, double *radius)¶

Get the covalent radius of an `atom` from the atom type, in the double pointed to by `radius`.

If the radius in unknown, this function set `radius` to -1.

CHFL_ATOM* atom = chfl_atom("Na");

double radius = 0;
chfl_atom_covalent_radius(atom, &radius);
assert(fabs(radius - 1.54) < 1e-15);

chfl_atom_free(atom);

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_atom_atomic_number(const CHFL_ATOM *const atom, int64_t *number)¶

Get the atomic number of an `atom` from the atom type, in the integer pointed to by `number`.

If the atomic number in unknown, this function set `number` to -1.

CHFL_ATOM* atom = chfl_atom("Na");

int64_t number = 0;
chfl_atom_atomic_number(atom, &number);
assert(number == 11);

chfl_atom_free(atom);

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_atom_free(CHFL_ATOM *const atom)¶

Free the memory associated with an `atom`.

CHFL_ATOM* atom = chfl_atom("Na");

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

chfl_atom_free(atom);

Return: `CHFL_SUCCESS`

Function manipulating CHFL_ATOM¶

Function manipulating `CHFL_ATOM`¶