Dealing with calculators

typedef struct featomic_calculator_t featomic_calculator_t

Opaque type representing a Calculator

The following functions operate on featomic_calculator_t:

struct featomic_calculator_t *featomic_calculator(const char *name, const char *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.

All memory allocated by this function can be released using featomic_calculator_free.

Parameters:

  • name – name of the calculator as a NULL-terminated string

  • parameters – hyper-parameters of the calculator, JSON-formatted in a NULL-terminated string

Returns:

A pointer to the newly allocated calculator, or a NULL pointer in case of error. In case of error, you can use featomic_last_error() to get the error message.

featomic_status_t featomic_calculator_free(struct featomic_calculator_t *calculator)

Free the memory associated with a calculator previously created with featomic_calculator.

If calculator is NULL, this function does nothing.

Parameters:

  • calculator – pointer to an existing calculator, or NULL

Returns:

The status code of this operation. If the status is not FEATOMIC_SUCCESS, you can use featomic_last_error() to get the full error message.

featomic_status_t featomic_calculator_compute(struct featomic_calculator_t *calculator, mts_tensormap_t **descriptor, struct featomic_system_t *systems, uintptr_t systems_count, struct featomic_calculation_options_t options)

Compute the representation of the given list of systems with a calculator

This function allocates a new mts_tensormap_t in *descriptor, which memory needs to be released by the user with mts_tensormap_free.

Parameters:

  • calculator – pointer to an existing calculator

  • descriptor – pointer to an mts_tensormap_t * that will be allocated by this function

  • systems – pointer to an array of systems implementation

  • systems_count – number of systems in systems

  • options – options for this calculation

Returns:

The status code of this operation. If the status is not FEATOMIC_SUCCESS, you can use featomic_last_error() to get the full error message.

featomic_status_t featomic_calculator_name(const struct featomic_calculator_t *calculator, char *name, uintptr_t bufflen)

Get a copy of the name of this calculator in the name buffer of size bufflen.

name will be NULL-terminated by this function. If the buffer is too small to fit the whole name, this function will return FEATOMIC_BUFFER_SIZE_ERROR

Parameters:

  • calculator – pointer to an existing calculator

  • name – string buffer to fill with the calculator name

  • bufflen – number of characters available in the buffer

Returns:

The status code of this operation. If the status is not FEATOMIC_SUCCESS, you can use featomic_last_error() to get the full error message.

featomic_status_t featomic_calculator_parameters(const struct featomic_calculator_t *calculator, char *parameters, uintptr_t bufflen)

Get a copy of the parameters used to create this calculator in the parameters buffer of size bufflen.

parameters will be NULL-terminated by this function. If the buffer is too small to fit the whole name, this function will return FEATOMIC_BUFFER_SIZE_ERROR.

Parameters:

  • calculator – pointer to an existing calculator

  • parameters – string buffer to fill with the parameters used to create this calculator

  • bufflen – number of characters available in the buffer

Returns:

The status code of this operation. If the status is not FEATOMIC_SUCCESS, you can use featomic_last_error() to get the full error message.

featomic_status_t featomic_calculator_cutoffs(const struct featomic_calculator_t *calculator, const double **cutoffs, uintptr_t *cutoffs_count)

Get all radial cutoffs used by this calculator’s neighbors lists (which can be an empty list).

The *cutoffs pointer will be pointing to data inside the calculator, and is only valid when the calculator itself is.

Parameters:

  • calculator – pointer to an existing calculator

  • cutoffs – pointer to be filled with the address of the first element of an array of cutoffs

  • cutoffs_count – pointer to be filled with the number of elements in the cutoffs array

Returns:

The status code of this operation. If the status is not FEATOMIC_SUCCESS, you can use featomic_last_error() to get the full error message.

struct featomic_calculation_options_t

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

Public Members

const char *const *gradients

Array of NULL-terminated strings containing the gradients to compute. If this field is NULL and gradients_count is 0, 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}\]

uintptr_t gradients_count

Size of the gradients array

bool use_native_system

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

struct featomic_labels_selection_t selected_samples

Selection of samples on which to run the computation

struct featomic_labels_selection_t selected_properties

Selection of properties to compute for the samples

const mts_labels_t *selected_keys

Selection for the keys to include in the output. Set this parameter to NULL 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.

struct featomic_labels_selection_t

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

To run the calculation for all possible labels, users should set both fields to NULL.

Public Members

const mts_labels_t *subset

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

If the mts_labels_t instance 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 mts_labels_t instance 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.

const mts_tensormap_t *predefined

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

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