Atom class¶

class 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 set, as "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 set, as "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.

The default mass is set when constructing the atom from the atomic type. To change the default value for a given type, you can use configuration files.

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.

The default charge is set when constructing the atom from the atomic type (usually to 0). To change the default value for a given type, you can use configuration files.

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. To change the value returned for a given type, you can use configuration files.

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. To change the value returned for a given type, you can use configuration files.

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

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

auto radius = atom.vdw_radius();
// dereferencing an optional<T> to access the value
assert(*radius == 1.7);
// or use the `value` member functions
assert(radius.value() == 1.7);

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

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

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. To change the value returned for a given type, you can use configuration files.

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

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

auto radius = atom.covalent_radius();
// dereferencing an optional<T> to access the value
assert(*radius == 0.77);
// or use the `value` member functions
assert(radius.value() == 0.77);

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

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

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. To change the value returned for a given type, you can use configuration files.

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);

const property_map &properties() const¶

Get the map of properties asociated with this atom. This map might be iterated over to list the properties of the atom, or directly accessed.

auto atom = Atom("C");

atom.set("a string", "this is a carbon");
atom.set("a number", 42.5);

// Iterator over properties in the atom
for (auto it: atom.properties()) {
    if (it.first == "a string") {
        assert(it.second.as_string() == "this is a carbon");
    } else if (it.first == "a number") {
        assert(it.second.as_double() == 42.5);
    }
}

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");

// Typed access to properties
assert(atom.get<Property::STRING>("first").value() == "this is a carbon");
assert(!atom.get<Property::BOOL>("first"));

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 returns 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");

// Typed access to properties
assert(atom.get<Property::STRING>("first").value() == "this is a carbon");
assert(!atom.get<Property::BOOL>("first"));

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

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

template<Property::Kind kind> optional<typename property_metadata<kind>::type> get(const std::string &name) const¶

Get the Property with the given name for this atom if it exists, and check that it has the required kind.

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

If a property with the given name is found, but has a different kind, this function emits a warning and returns nullopt.

This function returns 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");

// Typed access to properties
assert(atom.get<Property::STRING>("first").value() == "this is a carbon");
assert(!atom.get<Property::BOOL>("first"));

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

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