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 *frame, uint64_t index)

Get a copy of the atom at the given index 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 index is out of bounds. You can use chfl_last_error to learn about the error.

CHFL_ATOM *chfl_atom_from_topology(const CHFL_TOPOLOGY *topology, uint64_t index)

Get a copy of the atom at the given index 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 index is out of bounds. You can use chfl_last_error to learn about the error.

CHFL_ATOM *chfl_atom_copy(const CHFL_ATOM *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 *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 *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 *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 *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 *atom, char *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 *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 *atom, char *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 *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 *atom, char *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 *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 0.

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 *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 0.

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 *atom, uint64_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 0.

CHFL_ATOM* atom = chfl_atom("Na");

uint64_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_set_property(CHFL_ATOM *atom, const char *name, const CHFL_PROPERTY *property)

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

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

CHFL_ATOM* atom = chfl_atom("Na");
CHFL_PROPERTY* property = chfl_property_double(-23);

chfl_atom_set_property(atom, "this", property);
chfl_property_free(property);

property = chfl_atom_get_property(atom, "this");

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

chfl_property_free(property);
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_PROPERTY *chfl_atom_get_property(const CHFL_ATOM *atom, const char *name)

Get a property with the given name in this atom.

This function returns NULL is no property exist with the given name.

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

CHFL_ATOM* atom = chfl_atom("Na");
CHFL_PROPERTY* property = chfl_property_double(-23);

chfl_atom_set_property(atom, "this", property);
chfl_property_free(property);

property = chfl_atom_get_property(atom, "this");

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

chfl_property_free(property);
chfl_atom_free(atom);
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_atom_free(CHFL_ATOM *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