C API¶

Defines the C API for sphericart. Similar types and functions are available whether one is using the double or float data type, and whether one is using spherical or solid harmonics calculators. Types and functions for the float data type contain _f in their name, while those for the double data type do not. Similarly, types and functions for spherical harmonics calculations contain _spherical_harmonics in their name, and they calculate the real spherical harmonics \( Y^m_l \) as defined on Wikipedia, which are homogeneous polynomials of (x/r, y/r, z/r). In contrast, types and functions for solid harmonics calculations contain _solid_harmonics in their name, and thay calculate the same polynomials but as a function of the Cartesian coordinates (x, y, z), or, equivalently, \( r^l\,Y^m_l \).

Typedefs

typedef struct sphericart_spherical_harmonics_calculator_t sphericart_spherical_harmonics_calculator_t¶: A type referring to the sphericart_spherical_harmonics_calculator_t struct.

typedef struct sphericart_spherical_harmonics_calculator_f_t sphericart_spherical_harmonics_calculator_f_t¶: A type referring to the sphericart_spherical_harmonics_calculator_f_t struct.

typedef struct sphericart_solid_harmonics_calculator_t sphericart_solid_harmonics_calculator_t¶: A type referring to the sphericart_solid_harmonics_calculator_t struct.

typedef struct sphericart_solid_harmonics_calculator_f_t sphericart_solid_harmonics_calculator_f_t¶: A type referring to the sphericart_solid_harmonics_calculator_f_t struct.

Functions

sphericart_spherical_harmonics_calculator_t *sphericart_spherical_harmonics_new(size_t l_max)¶

Initializes a spherical harmonics calculator and returns a pointer that can then be used by functions that evaluate spherical harmonics over arrays or individual samples.

Parameters:

l_max – The maximum degree of the spherical harmonics to be calculated.

Returns:

A pointer to a sphericart_spherical_harmonics_calculator_t object

sphericart_spherical_harmonics_calculator_f_t *sphericart_spherical_harmonics_new_f(size_t l_max)¶: Similar to sphericart_spherical_harmonics_new, but it returns a sphericart_spherical_harmonics_calculator_f_t, which performs calculations on the float type.

void sphericart_spherical_harmonics_delete(sphericart_spherical_harmonics_calculator_t *calculator)¶: Deletes a previously allocated sphericart_spherical_harmonics_calculator_t calculator.

void sphericart_spherical_harmonics_delete_f(sphericart_spherical_harmonics_calculator_f_t *calculator)¶: Deletes a previously allocated sphericart_spherical_harmonics_calculator_f_t calculator.

void sphericart_spherical_harmonics_compute_array(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length)¶

This function calculates the spherical harmonics for an array of 3D points.

Parameters:

calculator – A pointer to a sphericart_spherical_harmonics_calculator_t struct that holds prefactors and options to compute the spherical harmonics.
xyz – An array of size n_samples x 3. It contains the Cartesian coordinates of the 3D points for which the spherical harmonics are to be computed, organized along two dimensions. The outer dimension is n_samples long, accounting for different samples, while the inner dimension has size 3 and it represents the x, y, and z coordinates respectively.
xyz_length – size of the xyz allocation, i.e, 3 x n_samples
sph – pointer to the first element of an array containing n_samples x (l_max + 1)^2 elements. On exit, this array will contain the spherical harmonics organized along two dimensions. The leading dimension is n_samples long and it represents the different samples, while the inner dimension size is (l_max + 1)^2 long and it contains the spherical harmonics. These are laid out in lexicographic order. For example, if l_max=2, it will contain (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.
sph_length – size of the sph allocation, should be n_samples x (l_max + 1)^2

void sphericart_spherical_harmonics_compute_array_with_gradients(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length)¶

This function calculates the spherical harmonics and their derivatives for an array of 3D points.

Parameters:

calculator – A pointer to a sphericart_spherical_harmonics_calculator_t struct that holds prefactors and options to compute the spherical harmonics.
xyz – An array of size n_samples x 3. It contains the Cartesian coordinates of the 3D points for which the spherical harmonics are to be computed, organized along two dimensions. The outer dimension is n_samples long, accounting for different samples, while the inner dimension has size 3 and it represents the x, y, and z coordinates respectively.
xyz_length – size of the xyz allocation, i.e, 3 x n_samples @param sph pointer to the first element of an array containingn_samples x (l_max + 1)^2` elements. On exit, this array will contain the spherical harmonics organized along two dimensions. The leading dimension is n_samples long and it represents the different samples, while the inner dimension size is (l_max + 1)^2 long and it contains the spherical harmonics. These are laid out in lexicographic order. For example, if l_max=2, it will contain (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.
sph_length – size of the sph allocation, should be n_samples * (l_max + 1)^2
dsph – pointer to the first element of an array containing n_samples xn_samples x 3 x (l_max + 1)^2 elements. On exit, this array will contain the spherical harmonics derivatives organized along three dimensions. As for the sph parameter, the leading dimension represents the different samples, while the inner-most dimension size is (l_max + 1)^2, and it represents the degree and order of the spherical harmonics (again, organized in lexicographic order). The intermediate dimension corresponds to different spatial derivatives of the spherical harmonics: x, y, and z, respectively.
dsph_length – size of the dsph allocation, which should be n_samples x 3 x (l_max + 1)^2

void sphericart_spherical_harmonics_compute_array_with_hessians(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length, double *ddsph, size_t ddsph_length)¶

This function calculates the spherical harmonics, their derivatives and second derivatives for an array of 3D points.

Parameters:

calculator – A pointer to a sphericart_spherical_harmonics_calculator_t struct that holds prefactors and options to compute the spherical harmonics.
xyz – An array of size n_samples x 3. It contains the Cartesian coordinates of the 3D points for which the spherical harmonics are to be computed, organized along two dimensions. The outer dimension is n_samples long, accounting for different samples, while the inner dimension has size 3 and it represents the x, y, and z coordinates respectively.
xyz_length – size of the xyz allocation, i.e, 3 x n_samples
sph – pointer to the first element of an array containing n_samples x (l_max + 1)^2 elements. On exit, this array will contain the spherical harmonics organized along two dimensions. The leading dimension is n_samples long and it represents the different samples, while the inner dimension size is (l_max + 1)^2 long and it contains the spherical harmonics. These are laid out in lexicographic order. For example, if l_max=2, it will contain (l, m) = (0, 0), (1, -1), (1, 0), (1, 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2), in this order.
sph_length – size of the sph allocation, should be n_samples * (l_max + 1)^2
dsph – pointer to the first element of an array containing n_samples x 3 x (l_max + 1)^2 elements. On exit, this array will contain the spherical harmonics’ derivatives organized along three dimensions. As for the sph parameter, the leading dimension represents the different samples, while the inner-most dimension size is (l_max + 1)^2, and it represents the degree and order of the spherical harmonics (again, organized in lexicographic order). The intermediate dimension corresponds to different spatial derivatives of the spherical harmonics: x, y, and z, respectively.
dsph_length – size of the dsph allocation, which should be n_samples x 3 x (l_max + 1)^2
ddsph – pointer to the first element of an array containing n_samples x 3 x 3 x (l_max + 1)^2 elements. On exit, this array will contain the spherical harmonics’ second derivatives organized along four dimensions. As for the sph parameter, the leading dimension represents the different samples, while the inner-most dimension size is (l_max + 1)^2, and it represents the degree and order of the spherical harmonics (again, organized in lexicographic order). The intermediate dimensions correspond to the different spatial second derivatives of the spherical harmonics, i.e., to the dimensions of the hessian matrix.
ddsph_length – size of the dsph allocation, which should be n_samples x 3 x 3* (l_max + 1)^2

void sphericart_spherical_harmonics_compute_sample(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array, but it computes the spherical harmonics for a single 3D point in space.

void sphericart_spherical_harmonics_compute_sample_with_gradients(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array_with_gradients, but it computes the spherical harmonics for a single 3D point in space.

void sphericart_spherical_harmonics_compute_sample_with_hessians(sphericart_spherical_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length, double *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array_with_hessians, but it computes the spherical harmonics for a single 3D point in space.

void sphericart_spherical_harmonics_compute_array_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array, but using the float data type.

void sphericart_spherical_harmonics_compute_array_with_gradients_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array_with_gradients, but using the float data type.

void sphericart_spherical_harmonics_compute_array_with_hessians_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length, float *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array_with_hessians, but using the float data type.

int sphericart_spherical_harmonics_omp_num_threads(sphericart_spherical_harmonics_calculator_t *calculator)¶: Get the number of OpenMP threads used by a calculator. If sphericart is computed without OpenMP support returns 1.

int sphericart_spherical_harmonics_omp_num_threads_f(sphericart_spherical_harmonics_calculator_f_t *calculator)¶: Similar to :func:sphericart_spherical_harmonics_omp_num_threads, but for a float calculator.

void sphericart_spherical_harmonics_compute_sample_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_sample, but using the float data type.

void sphericart_spherical_harmonics_compute_sample_with_gradients_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_sample_with_gradients, but using the float data type.

void sphericart_spherical_harmonics_compute_sample_with_hessians_f(sphericart_spherical_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length, float *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_sample_with_hessians, but using the float data type.

sphericart_solid_harmonics_calculator_t *sphericart_solid_harmonics_new(size_t l_max)¶: Similar to :func:sphericart_spherical_harmonics_new, but it returns a sphericart_solid_harmonics_calculator_t, which perform solid harmonics calculations.

sphericart_solid_harmonics_calculator_f_t *sphericart_solid_harmonics_new_f(size_t l_max)¶: Similar to sphericart_solid_harmonics_new, but it returns a sphericart_solid_harmonics_calculator_f_t, which performs calculations on the float type.

void sphericart_solid_harmonics_delete(sphericart_solid_harmonics_calculator_t *calculator)¶: Deletes a previously allocated sphericart_solid_harmonics_calculator_t calculator.

void sphericart_solid_harmonics_delete_f(sphericart_solid_harmonics_calculator_f_t *calculator)¶: Deletes a previously allocated sphericart_solid_harmonics_calculator_f_t calculator.

void sphericart_solid_harmonics_compute_array(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length)¶: Similar to :func:sphericart_spherical_harmonics_compute_array, but it computes the solid harmonics.

void sphericart_solid_harmonics_compute_array_with_gradients(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_gradients, but it computes the solid harmonics and their derivatives.

void sphericart_solid_harmonics_compute_array_with_hessians(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length, double *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_hessians, but it computes the solid harmonics and their derivatives.

void sphericart_solid_harmonics_compute_sample(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array, but it computes the solid harmonics for a single 3D point in space.

void sphericart_solid_harmonics_compute_sample_with_gradients(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_gradients, but it computes the solid harmonics for a single 3D point in space.

void sphericart_solid_harmonics_compute_sample_with_hessians(sphericart_solid_harmonics_calculator_t *calculator, const double *xyz, size_t xyz_length, double *sph, size_t sph_length, double *dsph, size_t dsph_length, double *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_hessians, but it computes the solid harmonics for a single 3D point in space.

void sphericart_solid_harmonics_compute_array_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array, but using the float data type.

void sphericart_solid_harmonics_compute_array_with_gradients_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_gradients, but using the float data type.

void sphericart_solid_harmonics_compute_array_with_hessians_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length, float *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_array_with_hessians, but using the float data type.

void sphericart_solid_harmonics_compute_sample_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_sample, but using the float data type.

void sphericart_solid_harmonics_compute_sample_with_gradients_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_sample_with_gradients, but using the float data type.

void sphericart_solid_harmonics_compute_sample_with_hessians_f(sphericart_solid_harmonics_calculator_f_t *calculator, const float *xyz, size_t xyz_length, float *sph, size_t sph_length, float *dsph, size_t dsph_length, float *ddsph, size_t ddsph_length)¶: Similar to :func:sphericart_solid_harmonics_compute_sample_with_hessians, but using the float data type.

int sphericart_solid_harmonics_omp_num_threads(sphericart_solid_harmonics_calculator_t *calculator)¶: Similar to :func:sphericart_spherical_harmonics_omp_num_threads, but for a solid harmonics calculator.

int sphericart_solid_harmonics_omp_num_threads_f(sphericart_solid_harmonics_calculator_f_t *calculator)¶: Similar to :func:sphericart_spherical_harmonics_omp_num_threads, but for a float solid harmonics calculator.