# Atom class¶

class chemfiles::Atom

An Atom is a particle in the current Frame.

An atom stores atomic properties such as the atom name and type, the mass and the charge. It also stores arbitrary property unsing the Property class. Position and velocity are not stored in the Atom class, but in separated arrays in the Frame class.

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

Public Functions

Atom(std::string name = "")

Create an atom with the given name and set the atom type to be the same as name.

If the atom type exists in the periodic table, the atom mass is set to the matching value. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na mass.

auto atom = Atom();
assert(atom.name() == "");
assert(atom.type() == "");

atom = Atom("Zn");
assert(atom.name() == "Zn");
assert(atom.type() == "Zn");
// The atom mass is automatically set
assert(atom.mass() == 65.38);

atom = Atom("O23", "Ow");
assert(atom.name() == "O23");
assert(atom.type() == "Ow");
// The atom mass is not automatically set, "Ow" is not in the periodic table
assert(atom.mass() == 0.0);


Parameters
• name: atomic name for the new atom

Atom(std::string name, std::string type)

Create an atom from the given name and type

If the atom type exists in the periodic table, the atom mass is set to the matching value. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na mass.

auto atom = Atom();
assert(atom.name() == "");
assert(atom.type() == "");

atom = Atom("Zn");
assert(atom.name() == "Zn");
assert(atom.type() == "Zn");
// The atom mass is automatically set
assert(atom.mass() == 65.38);

atom = Atom("O23", "Ow");
assert(atom.name() == "O23");
assert(atom.type() == "Ow");
// The atom mass is not automatically set, "Ow" is not in the periodic table
assert(atom.mass() == 0.0);


Parameters
• name: atomic name for the new atom
• type: atomic type for the new atom

const std::string &name() const

Get the atom name.

auto atom = Atom("C");
assert(atom.name() == "C");

atom.set_name("C1");
assert(atom.name() == "C1");


const std::string &type() const

Get the atom type.

auto atom = Atom("C1");
assert(atom.type() == "C1");

atom.set_type("C");
assert(atom.type() == "C");

atom = Atom("O1", "O");
assert(atom.type() == "O");


double mass() const

Get the atom mass.

auto atom = Atom("C");
assert(atom.mass() == 12.011);

atom.set_mass(42.5);
assert(atom.mass() == 42.5);


double charge() const

Get the atom charge.

auto atom = Atom("C");
assert(atom.charge() == 0.0);

atom.set_charge(0.2);
assert(atom.charge() == 0.2);


void set_name(std::string name)

Set the atom name to name.

auto atom = Atom("C");
assert(atom.name() == "C");

atom.set_name("C1");
assert(atom.name() == "C1");


void set_type(std::string type)

Set the atom type to type.

auto atom = Atom("C1");
assert(atom.type() == "C1");

atom.set_type("C");
assert(atom.type() == "C");

atom = Atom("O1", "O");
assert(atom.type() == "O");


void set_mass(double mass)

Set the atom mass to mass.

auto atom = Atom("C");
assert(atom.mass() == 12.011);

atom.set_mass(42.5);
assert(atom.mass() == 42.5);


void set_charge(double charge)

Set the atom charge to charge.

auto atom = Atom("C");
assert(atom.mass() == 12.011);

atom.set_mass(42.5);
assert(atom.mass() == 42.5);


optional<std::string> full_name() const

Try to get the full atomic name from the atom type.

This function tries to get the full name corresponding to the current atom type: for example, the full name for He is "Helium". If no name can be found, this function returns nullopt. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na full name.

This function returna an chemfiles::optional value that is close to C++17 std::optional.

auto atom = Atom("C23a", "C");

auto name = atom.full_name();
// dereferencing an optional<T> to access the value
assert(*name == "Carbon");
// or use the value member functions
assert(name.value() == "Carbon");

// matching is performed with case-insensitive search
atom = Atom("C23a", "c");
assert(atom.full_name().value() == "Carbon");

// the radius is guessed from the atom type, the atom name is ignored
atom = Atom("C", "Baz");
name = atom.full_name();
assert(!name);


optional<double> vdw_radius() const

Try to get the Van der Waals radius from the atom type.

This function tries to get the Van der Waals radius corresponding to the current atom type: for example, the radius for He is 1.4 A. If no radius can be found, this function returns nullopt. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na radius.

This function returna an chemfiles::optional value that is close to C++17 std::optional.

auto atom = Atom("C23a", "C");

// dereferencing an optional<T> to access the value
// or use the value member functions

// matching is performed with case-insensitive search
atom = Atom("C23a", "c");

// the radius is guessed from the atom type, the atom name is ignored
atom = Atom("C", "Baz");


optional<double> covalent_radius() const

Try to get the covalent radius from the atom type.

This function tries to get the covalent radius corresponding to the current atom type: for example, the radius for He is 0.32 A. If no radius can be found, this function returns nullopt. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na radius.

This function returna an chemfiles::optional value that is close to C++17 std::optional.

auto atom = Atom("C23a", "C");

// dereferencing an optional<T> to access the value
// or use the value member functions

// matching is performed with case-insensitive search
atom = Atom("C23a", "c");

// the radius is guessed from the atom type, the atom name is ignored
atom = Atom("C", "Baz");


optional<uint64_t> atomic_number() const

Try to get the atomic number from the atom type.

This function tries to get the atomic number corresponding to the current atom type: for example, the atomic number for He is 2. If no atomic number can be found, this function returns nullopt. This check is executed with case-insensitive atom type: Na, NA, nA and na all get the Na atomic number.

This function returna an chemfiles::optional value that is close to C++17 std::optional.

auto atom = Atom("C23a", "C");

auto number = atom.atomic_number();
// dereferencing an optional<T> to access the value
assert(*number == 6);
// or use the value member functions
assert(number.value() == 6);

// matching is performed with case-insensitive search
atom = Atom("C23a", "c");
assert(atom.atomic_number().value() == 6);

// the radius is guessed from the atom type, the atom name is ignored
atom = Atom("C", "Baz");
number = atom.atomic_number();
assert(!number);


void set(std::string name, Property value)

Set an arbitrary Property for this atom with the given name and value. If a property with this name already exist, it is replaced with the new value.

auto atom = Atom("C");

atom.set("first", "this is a carbon");
atom.set("second", 42.5);

assert(atom.get("second")->as_double() == 42.5);
assert(atom.get("first")->as_string() == "this is a carbon");

assert(!atom.get("non-existant property"));

// Override the "first" property
atom.set("first", false);
assert(atom.get("first")->as_bool() == false);


optional<const Property&> get(const std::string &name) const

Get the Property with the given name for this atom if it exists.

If no property with the given name is found, this function returns nullopt.

This function returna an chemfiles::optional value that is close to C++17 std::optional.

auto atom = Atom("C");

atom.set("first", "this is a carbon");
atom.set("second", 42.5);

assert(atom.get("second")->as_double() == 42.5);
assert(atom.get("first")->as_string() == "this is a carbon");

assert(!atom.get("non-existant property"));

// Override the "first" property
atom.set("first", false);
assert(atom.get("first")->as_bool() == false);