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

Here is the full list of functions acting on CHFL_ATOM:

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

CHFL_ATOM* atom = chfl_atom("Na");

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

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

Get access to the atom at the given index from a frame.

Any modification to the atom will be reflected in the frame. The frame will be kept alive, even if chfl_free(frame) 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 frame, and will be invalidated if any of the following function is called on the frame:

  • chfl_frame_resize
  • chfl_frame_add_atom
  • chfl_frame_remove
  • chfl_frame_set_topology
  • chfl_trajectory_read
  • chfl_trajectory_read_step

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_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_free(atom);
chfl_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(CHFL_TOPOLOGY *topology, uint64_t index)

Get access to the atom at the given index from a topology

Any modification to the atom will be reflected in the topology. 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:

  • chfl_topology_resize
  • chfl_topology_add_atom
  • chfl_topology_remove

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();
/* Update the topology by hand, or using a file */

CHFL_ATOM* atom = chfl_atom_from_topology(topology, 4);

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

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

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

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

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

property = chfl_atom_get_property(atom, "this");

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

chfl_free(property);
chfl_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 if no property exists with the given name.

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

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

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

property = chfl_atom_get_property(atom, "this");

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

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

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

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

chfl_atom_set_property(atom, "this", property);
chfl_atom_set_property(atom, "that", property);
chfl_free(property);

uint64_t count = 0;
chfl_atom_properties_count(atom, &count);
assert(count == 2);

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

Get the names of all properties of this atom 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_atom_properties_count.

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

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

chfl_atom_set_property(atom, "this", property);
chfl_atom_set_property(atom, "that", property);
chfl_free(property);

uint64_t count = 0;
chfl_atom_properties_count(atom, &count);
assert(count == 2);

const char* names[2] = {NULL};
chfl_atom_list_properties(atom, 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(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.