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:
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
(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);
chfl_last_error
to learn about the error.
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);
index
is out of bounds. You can use chfl_last_error
to learn about the error.
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);
index
is out of bounds. You can use chfl_last_error
to learn about the error.
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);
chfl_last_error
to learn about the error.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
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);
chfl_last_error
to learn about the error.
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);
CHFL_SUCCESS