Dealing with calculators

class Calculator

The Calculator class implements the calculation of a given atomic scale representation. Specific implementation are registered globally, and requested at construction.

Public Functions

inline Calculator(std::string name, std::string parameters)

Create a new calculator with the given name and parameters.

The list of available calculators and the corresponding parameters are in the main documentation. The parameters should be formatted as JSON, according to the requested calculator schema.

Throws:

FeatomicError – if name is not associated with a known calculator, if parameters is not valid JSON, or if parameters do not contains the expected values for the requested calculator.

Calculator(const Calculator&) = delete

Calculator is NOT copy-constructible.

Calculator &operator=(const Calculator&) = delete

Calculator can NOT be copy-assigned.

inline Calculator(Calculator &&other) noexcept

Calculator is move-constructible.

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

Calculator can be move-assigned.

inline std::string name() const

Get the name used to create this Calculator

inline std::string parameters() const

Get the parameters used to create this Calculator

inline std::vector<double> cutoffs() const

Get all radial cutoffs used by this Calculator’s neighbors lists.

inline metatensor::TensorMap compute(std::vector<featomic_system_t> &systems, CalculationOptions options = CalculationOptions()) const

Runs a calculation with this calculator on the given systems

template<typename SystemImpl, typename std::enable_if<std::is_base_of<System, SystemImpl>::value, bool>::type = true>
inline metatensor::TensorMap compute(std::vector<SystemImpl> &systems, CalculationOptions options = CalculationOptions()) const

Runs a calculation for multiple systems

template<typename SystemImpl, typename std::enable_if<std::is_base_of<System, SystemImpl>::value, bool>::type = true>
inline metatensor::TensorMap compute(SystemImpl &system, CalculationOptions options = CalculationOptions()) const

Runs a calculation for a single system

inline metatensor::TensorMap compute(BasicSystems &systems, CalculationOptions options = CalculationOptions()) const

Runs a calculation for all the systems that where read from a file using the BasicSystems(std::string path) constructor

inline featomic_calculator_t *as_featomic_calculator_t()

Get the underlying pointer to a featomic_calculator_t.

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

inline const featomic_calculator_t *as_featomic_calculator_t() const

Get the underlying const pointer to a featomic_calculator_t.

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

class CalculationOptions

Options that can be set to change how a calculator operates.

Public Functions

inline featomic_calculation_options_t as_featomic_calculation_options_t()

Convert this instance of CalculationOptions to a featomic_calculation_options_t.

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

Public Members

bool use_native_system = false

Copy the data from systems into native SimpleSystem. This can be faster than having to cross the FFI boundary too often.

LabelsSelection selected_samples = LabelsSelection::all()

Selection of samples on which to run the computation.

LabelsSelection selected_properties = LabelsSelection::all()

Selection of properties to compute for the samples.

std::optional<metatensor::Labels> selected_keys = std::nullopt

Selection for the keys to include in the output. Set this to std::nullopt to use the default set of keys, as determined by the calculator. Note that this default set of keys can depend on which systems we are running the calculation on.

std::vector<const char*> gradients

List of gradients that should be computed. If this list is empty no gradients are computed.

The following gradients are available:

• "positions", for gradients of the representation with respect to atomic positions, with fixed cell matrix parameters. Positions gradients are computed as

  \[\frac{\partial \langle q \vert A_i \rangle} {\partial \mathbf{r_j}}\]

  where \(\langle q \vert A_i \rangle\) is the representation around atom \(i\) and \(\mathbf{r_j}\) is the position vector of the atom \(j\).

  Note: Position gradients of an atom are computed with respect to all other atoms within the representation. To recover the force one has to accumulate all pairs associated with atom \(i\).

• "strain", for gradients of the representation with respect to strain. These gradients are typically used to compute the virial, and from there the pressure acting on a system. To compute them, we pretend that all the positions \(\mathbf r\) and unit cell \(\mathbf H\) have been scaled by a strain matrix \(\epsilon\):

  \[\begin{split}\mathbf r &\rightarrow \mathbf r \left(\mathbb{1} + \epsilon \right)\\ \mathbf H &\rightarrow \mathbf H \left(\mathbb{1} + \epsilon \right)\end{split}\]

  and then take the gradients of the representation with respect to this matrix:

  \[\frac{\partial \langle q \vert A_i \rangle} {\partial \mathbf{\epsilon}}\]

• "cell", for gradients of the representation with respect to the system’s cell parameters. These gradients are computed at fixed positions, and often not what you want when computing gradients explicitly (they are mainly used in featomic.torch to integrate with backward propagation). If you are trying to compute the virial or the stress, you should use "strain" gradients instead.

  \[\left. \frac{\partial \langle q \vert A_i \rangle} {\partial \mathbf{H}} \right |_\mathbf{r}\]

class LabelsSelection

Rules to select labels (either samples or properties) on which the user wants to run a calculation

Public Functions

inline LabelsSelection(const LabelsSelection &other)

LabelsSelection can be copy-constructed.

inline LabelsSelection &operator=(const LabelsSelection &other)

LabelsSelection can be copy-assigned.

inline LabelsSelection(LabelsSelection &&other) noexcept

LabelsSelection can be move-constructed.

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

LabelsSelection can be move-assigned.

inline featomic_labels_selection_t as_featomic_labels_selection_t() const

Get the featomic_labels_selection_t corresponding to this LabelsSelection.

Public Static Functions

static inline LabelsSelection all()

Use all possible labels for this calculation.

static inline LabelsSelection subset(metatensor::Labels selection)

Select a subset of labels, using the same selection criterion for all keys in the final TensorMap.

If the selection contains the same variables as the full set of labels, then only entries from the full set that also appear in this selection will be used.

If the selection contains a subset of the variables of the full set of labels, then only entries from the full set which match one of the entry in this selection for all of the selection variable will be used.

static inline LabelsSelection predefined(const metatensor::TensorMap &selection)

Use a predefined subset of labels, with different entries for different keys of the final TensorMap.

For each key, the corresponding labels are fetched out of the selection, which must have the same set of keys as the full calculation.