Defining systems

There are two ways you can define systems to pass to a featomic::Calculator. The easy way is to use featomic::BasicSystems to read all systems defined in a file, and run the calculation on all these systems. The more complex but also more flexible way is to define a new child class of featomic::System implementing all required functions; and then passing a vector of pointers to the child class instances to your featomic::Calculator.

class System

A System deals with the storage of atoms and related information, as well as the computation of neighbor lists.

This class only defines a pure virtual interface for System. In order to provide access to new system, users must create a child class implementing all virtual member functions.

Subclassed by featomic_torch::SystemAdapter

Public Types

using CellMatrix = std::array<std::array<double, 3>, 3>

Unit cell representation as a 3x3 matrix. The cell should be written in row major order, i.e. {{ax ay az}, {bx by bz}, {cx cy cz}}, where a/b/c are the unit cell vectors.

Public Functions

System(const System&) = default

System is copy-constructible.

System(System&&) = default

System is move-constructible.

System &operator=(const System&) = default

System can be copy-assigned.

System &operator=(System&&) = default

System can be move-assigned.

virtual uintptr_t size() const = 0

Get the number of atoms in this system.

virtual const int32_t *types() const = 0

Get a pointer to the first element a contiguous array (typically std::vector or memory allocated with new[]) containing the atomic type of each atom in this system. Different atomics types should be identified with a different value. These values are usually the atomic number, but don’t have to be. The array should contain System::size() elements.

virtual const double *positions() const = 0

Get a pointer to the first element of a contiguous array containing the atomic cartesian coordinates. positions[0], positions[1], positions[2] must contain the x, y, z cartesian coordinates of the first atom, and so on. The array should contain 3 x System::size() elements.

virtual CellMatrix cell() const = 0

Get the matrix describing the unit cell.

virtual void compute_neighbors(double cutoff) = 0

Compute the neighbor list with the given cutoff, and store it for later access using System::pairs or System::pairs_containing.

virtual const std::vector<featomic_pair_t> &pairs() const = 0

Get the list of pairs in this system

This list of pair should only contain each pair once (and not twice as i-j and j-i), should not contain self pairs (i-i); and should only contains pairs where the distance between atoms is actually bellow the cutoff passed in the last call to System::compute_neighbors. This function is only valid to call after a call to System::compute_neighbors.

virtual const std::vector<featomic_pair_t> &pairs_containing(uintptr_t atom) const = 0

Get the list of pairs in this system containing the atom at the given index.

The same restrictions on the list of pairs as System::pairs applies, with the additional condition that the pair i-j should be included both in the return of System::pairs_containing(i) and System::pairs_containing(j).

inline featomic_system_t as_featomic_system_t()

Convert a child instance of the System class to a featomic_system_t to be passed to the featomic functions.

This is an advanced function that most users don’t need to call directly.

class BasicSystems

A collection of systems read from a file. This is a convenience class enabling the common use case of reading systems from a file and runnning a calculation on the systems. If you need more control or access to advanced functionalities, you should consider writing a new class extending System.

Public Functions

inline BasicSystems(const std::string &path)

Read all structures in the file at the given path using chemfiles.

This function can read all formats supported by chemfiles.

Throws:

FeatomicError – if chemfiles can not read the file

BasicSystems(const BasicSystems&) = delete

BasicSystems is NOT copy-constructible.

BasicSystems &operator=(const BasicSystems&) = delete

BasicSystems can NOT be copy-assigned.

inline BasicSystems(BasicSystems &&other) noexcept

BasicSystems is move-constructible.

inline BasicSystems &operator=(BasicSystems &&other) noexcept

BasicSystems can be move-assigned.

inline featomic_system_t *systems()

Get a pointer to the first element of the underlying array of systems

This function is intended for internal use only.

inline uintptr_t count() const

Get the number of systems managed by this BasicSystems