charm_crd#

Module to work with the coordinates of evaluation points/cells:

defines charm_point and charm_cell structures,
allocates, initializes and frees charm_point and charm_cell,
computes charm_point for a few pre-defined grid types.

References:

Sneeuw, N. (1994) Global spherical harmonic analysis by least-squares and numerical quadrature methods in historical perspective. Geophysical Journal International 118:707-716
Driscoll, J. R., Healy, D. M. (1994) Computing Fourier transforms and convolutions on the 2-sphere. Advances in Applied Mathematics 15:202-250
Wieczorek, M. A., Meschede, M. (2018) SHTools: Tools for Working with Spherical Harmonics. Geochemistry, Geophysics, Geosystems 19:2574-2592

Note

This documentation is written for double precision version of CHarm.

Allocate, initialize and free the charm_point structure

These functions allocate, initialize and free the charm_point structure, which is designed to store evaluation points.

charm_point *charm_crd_point_malloc(int type, size_t nlat, size_t nlon)#

Allocates evaluation points of a given type with nlat latitudes, nlon longitudes and nlat spherical radii. If type is CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 or CHARM_CRD_POINT_GRID_DH2, nlat integration weights are allocated in addition. The memory of all array elements is uninitialized, so their values are undefined.

Valid values of type are constants CHARM_CRD_POINT_SCATTERED, CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 and CHARM_CRD_POINT_GRID_DH2.

For charm_point *pnt returned by this function with type being CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 or CHARM_CRD_POINT_GRID_DH2, the coordinates of the grid point on the i-th latitude parallel and the j-th meridian have to be accessed as
- pnt->lat[i] for the grid latitude,
- pnt->lon[j] for the grid longitude, and
- pnt->r[i] for the spherical radii
with i = 0, 1, ..., nlat - 1 and j = 0, 1, ..., nlon - 1.
For type set to CHARM_CRD_POINT_SCATTERED, the coordinates of the i-th point have to be accessed as
- pnt->lat[i] for the grid latitude,
- pnt->lon[i] for the grid longitude, and
- pnt->r[i] for the spherical radii
with i = 0, 1, ..., nlat - 1, nlat == nlon.

Warning

The structure returned must be deallocated by calling charm_crd_point_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_point structure. On error, NULL is returned. Errors include memory allocation failures and incorrect input arguments (e.g., nlat < 1, nlon < 1 or unsupported value of type).

charm_point *charm_crd_point_calloc(int type, size_t nlat, size_t nlon)#: The same as charm_crd_point_malloc() but all array elements are initialized to zero.

charm_point *charm_crd_point_init(int type, size_t nlat, size_t nlon, double *lat, double *lon, double *r)#

For a given point type, takes nlat spherical latitudes from the array pointed to by lat, nlon spherical longitudes from lon and nlat spherical radii from r (shallow copy).

Valid values of type are constants CHARM_CRD_POINT_SCATTERED, CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 and CHARM_CRD_POINT_GRID_DH2.

If type is CHARM_CRD_POINT_SCATTERED,
- nlat must be equal to nlon and
- each of lat, lon and r must have access to nlat elements.
If type is CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 or CHARM_CRD_POINT_GRID_DH2,
- lat must have access to nlat elements,
- lon must have access to nlon elements, and
- r must have access to nlat elements.

Note

See charm_crd_point_malloc() to find out how to access the coordinates stored in the returned charm_point structure.

Note

See charm_shc_init() for the rationale behind the shallow copies of input arrays lat, lon and r. The memory of these arrays must be treated in the same fashion as shown therein with the c and s arrays.

Warning

The structure returned must be deallocated using charm_crd_point_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_point structure. On error, NULL is returned. Errors include memory allocation failures and incorrect input arguments (e.g., nlat < 1, nlon < 1 or unsupported value of type).

void charm_crd_point_free(charm_point *pnt)#

Frees the memory associated with pnt. No operation is performed if pnt is NULL.

If pnt->owner is 1, the function releases all the memory that is associated with pnt, including that of its array members. If pnt->owner is 0, the arrays are not released from the memory, because they were not allocated by CHarm.

Quadrature point grids

These functions compute the Gauss-Legendre and Driscoll-Healy quadrature grids and the associated integration weights.

charm_point *charm_crd_point_gl(unsigned long nmax, double r)#

Computes the Gauss-Legendre grid associated with the harmonic degree nmax (Sneeuw, 1994) on the sphere with the radius r. The integration weights are computed on the unit sphere.

Loops are parallelized using OpenMP.

Note

The Gauss-Legendre grid is non-equiangular in latitude. The longitudinal step is constant.

Warning

The structure returned must be deallocated by calling charm_crd_point_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_point structure. On error, NULL is returned. In addition to the memory allocation failure, the error may be due to the exceeded maximum number of iterations to compute the latitudes or due to the overflow problem. The latter may happen in single precision if nmax is larger than 7200 or so. The overflow check is not performed if the output from charm_misc_buildopt_isfinite() is zero.

charm_point *charm_crd_point_dh1(unsigned long nmax, double r)#

Computes the non-equiangular Driscoll-Healy grid (as defined by Driscoll and Healy, 1994) associated with the maximum spherical harmonic degree nmax on the sphere with the radius r. The integration weights are computed on the unit sphere.

Loops are parallelized using OpenMP.

Warning

The structure returned must be deallocated by calling charm_crd_point_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_point structure. On error, NULL is returned.

charm_point *charm_crd_point_dh2(unsigned long nmax, double r)#: The same as charm_crd_point_dh1() but for the equiangular modification of the Driscoll-Healy grid after Wieczorek and Meschede (2018).

Allocate, initialize and free the charm_cell structure

These functions allocate, initialize and free the charm_cell structure, which is designed to store evaluation cells.

charm_cell *charm_crd_cell_malloc(int type, size_t nlat, size_t nlon)#

Allocates evaluation cells of a given type with nlat minimum and maximum latitudes, nlon minimum and maximum longitudes and nlat spherical radii. The memory of all array elements is uninitialized, so their values are undefined.

Valid values of type are constants CHARM_CRD_CELL_GRID and CHARM_CRD_CELL_SCATTERED.

For charm_cell *cell returned by this function with type being CHARM_CRD_CELL_GRID, the coordinates of the grid cell on the i-th latitude parallel and the j-th meridian have to be accessed as
- cell->latmin[i] for the minimum cell latitude,
- cell->latmax[i] for the maximum cell latitude,
- cell->lonmin[j] for the minimum cell longitude,
- cell->lonmax[j] for the maximum cell longitude,
- cell->r[i] for the spherical radii
with i = 0, 1, ..., nlat - 1 and j = 0, 1, ..., nlon - 1.
For type set to CHARM_CRD_CELL_SCATTERED, the coordinates of the i-th cell have to be accessed as
- cell->latmin[i] for the minimum cell latitude,
- cell->latmax[i] for the maximum cell latitude,
- cell->lonmin[i] for the minimum cell longitude,
- cell->lonmax[i] for the maximum cell longitude,
- cell->r[i] for the spherical radii
with i = 0, 1, ..., nlat - 1, nlat == nlon.

Warning

The structure returned must be deallocated by calling charm_crd_cell_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_cell structure. On error, NULL is returned. Errors include memory allocation failures and incorrect input arguments (e.g., nlat < 1, nlon < 1 or unsupported value of type).

charm_cell *charm_crd_cell_calloc(int type, size_t nlat, size_t nlon)#: The same as charm_crd_cell_malloc() but the memory of all array elements is initialized to zero.

charm_cell *charm_crd_cell_init(int type, size_t nlat, size_t nlon, double *latmin, double *latmax, double *lonmin, double *lonmax, double *r)#

For a given type, takes nlat minimum and maximum spherical latitudes from the arrays pointed to by latmin and latmax, nlon minimum and maximum spherical longitudes from lonmin and lonmax and nlat spherical radii from r, respectively (shallow copy).

Accepted values of type are CHARM_CRD_CELL_GRID and CHARM_CRD_CELL_SCATTERED.

If type is CHARM_CRD_CELL_SCATTERED,
- nlat must be equal to nlon and
- each of latmin, latmax, lonmin, lonmax and r must have access to nlat elements.
If type is CHARM_CRD_CELL_GRID,
- latmin and latmax must each have access to nlat elements,
- lonmin and lonmax must each have access to nlon elements,
- r must have access to nlat elements.

Note

See charm_crd_cell_malloc() to find out how to access the coordinates stored in the returned charm_cell structure.

Note

See charm_shc_init() for the rationale behind the shallow copies of input arrays latmin, latmax, lonmin, lonmax and r. The memory of these arrays must be treated in the same fashion as shown therein with the c and s arrays.

Warning

The structure created by this function must be deallocated using charm_crd_cell_free(). The usual deallocation with free will lead to memory leaks.

Returns:: On success, returned is a pointer to the charm_cell structure. On error, NULL is returned. Errors include memory allocation failures and incorrect input arguments (e.g., nlat < 1, nlon < 1 or unsupported value of type).

void charm_crd_cell_free(charm_cell *cell)#

Frees the memory associated with cell. No operation is performed if cell is NULL.

If cell->owner is 1, the function releases all the memory that is associated with cell, including that of its array members. If cell->owner is 0, the arrays are not released from the memory, because they were not allocated by CHarm.

Enums

enum [anonymous]#

Defines supported values of charm_point.type to CHARM_CRD_POINT_SCATTERED, CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1, CHARM_CRD_POINT_GRID_DH2. For charm_cell.type, valid constants are CHARM_CRD_CELL_SCATTERED and CHARM_CRD_CELL_GRID.

Values:

enumerator CHARM_CRD_CELL_GRID = -2#: Custom grid of cells.

enumerator CHARM_CRD_CELL_SCATTERED#: Scattered cells.

enumerator CHARM_CRD_POINT_SCATTERED = 1#: Scattered points.

enumerator CHARM_CRD_POINT_GRID#: Custom point grid.

enumerator CHARM_CRD_POINT_GRID_GL#: Gauss-Legendre point grid.

enumerator CHARM_CRD_POINT_GRID_DH1#: Driscoll-Healy point grid as defined by Driscoll and Healy (1994) (non-equiangular).

enumerator CHARM_CRD_POINT_GRID_DH2#: The equiangular modification of the Driscoll-Healy point grid after Wieczorek and Meschede (2018).

struct charm_point#

Structure to store evaluation points.

Public Members

int type#

Defines whether the points are organized as a grid or are scattered.

charm_point.type takes the following constants:

CHARM_CRD_POINT_SCATTERED for user-defined scattered points,
CHARM_CRD_POINT_GRID for a user-defined grid,
CHARM_CRD_POINT_GRID_GL for the Gauss-Legendre grid (Sneeuw, 1994) with nmax + 1 latitudes and 2 * nmax + 2 longitudes (nmax is maximum harmonic degree),
CHARM_CRD_POINT_GRID_DH1 for the non-equiangular Driscoll-Healy grid as defined by Driscoll and Healy (1994) with 2 * nmax + 2 latitudes and 2 * nmax + 2 longitudes, and
CHARM_CRD_POINT_GRID_DH2 for an equiangular modification of the Driscoll-Healy grid (Wieczorek and Meschede, 2018) with 2 * nmax + 2 latitudes and 4 * nmax + 4 longitudes.

size_t nlat#

Number of latitudes.

For scattered points (charm_point.type is CHARM_CRD_POINT_SCATTERED), charm_point.nlat represents the total number of points in the charm_point structure.
For grids (charm_point.type is CHARM_CRD_POINT_GRID, CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1 or CHARM_CRD_POINT_GRID_DH2), charm_point.nlat stands for the numbers of points in the latitudinal direction of the grid.

size_t nlon#

Number of longitudes.

For scattered points, charm_point.nlon represents the total number of points in the charm_point structure. charm_point.nlon must be equal to charm_point.nlat. The total number of points is charm_point.nlat == charm_point.nlon.
For grids, charm_point.nlon stands for the numbers of points in the longitudinal direction of the grid. charm_point.nlat and charm_point.nlon may be different. The total number of grid points is charm_point.nlat * charm_point.nlon.

double *lat#: Pointer to an array of latitudes in radians. charm_point.nlat array elements are associated with charm_point.lat.

double *lon#: Pointer to an array of longitudes in radians. charm_point.nlon array elements are associated with charm_point.lon.

double *r#: Pointer to an array of spherical radii in metres. charm_point.nlat array elements are associated with charm_point.r.

double *w#

Pointer to an array of integration weights on the unit sphere. The pointer is used (i.e. is not NULL) only for charm_point structures returned by the charm_crd_point_gl(), charm_crd_point_dh1() and charm_crd_point_dh2() functions, that is, if charm_point.type is CHARM_CRD_POINT_GRID_GL, CHARM_CRD_POINT_GRID_DH1, or CHARM_CRD_POINT_GRID_DH2.

charm_point.nlat array elements are associated with charm_point.w.

For all other values of charm_point.type, charm_point.w is NULL and is never used.

_Bool owner#: If 1, the memory associated with charm_point.lat, charm_point.lon, charm_point.r and charm_point.w was allocated by CHarm, so charm_crd_point_free() deallocates it. If charm_point.owner is 0, the memory associated with these arrays was allocated outside CHarm, so charm_crd_point_free() does not deallocate it (the user allocated this memory outside CHarm, so the user should free the memory outside CHarm as well).

struct charm_cell#

Structure to store evaluation cells.

Public Members

int type#

Defines whether the cells are organized as a regular grid or are scattered.

charm_cell.type takes the following constants:

CHARM_CRD_CELL_GRID for a user-defined grid of cells,
CHARM_CRD_CELL_SCATTERED for a user-defined set of scattered cells.

size_t nlat#

Number of latitudes.

For scattered cells (charm_cell.type set to CHARM_CRD_CELL_SCATTERED), charm_cell.nlat represents the total number of cells in the charm_cell structure.
For grids (charm_cell.type set to CHARM_CRD_CELL_GRID), charm_cell.nlat stands for the numbers of cells in the latitudinal direction of the grid.

size_t nlon#

Number of longitudes.

For scattered cells, charm_cell.nlon represents the total number of cells in the charm_cell structure. charm_cell.nlon must be equal to charm_cell.nlat. The total number of cells is equal to charm_cell.nlat == charm_cell.nlon.
For grids, charm_cell.nlon stands for the numbers of cells in the longitudinal direction of the grid. charm_cell.nlat and charm_cell.nlon may be different. The total number of grid cells is charm_cell.nlat * charm_cell.nlon.

double *latmin#: Pointer to an array of minimum cell latitudes in radians. charm_cell.nlat array elements are associated with charm_cell.latmin

double *latmax#: Pointer to an array of maximum cell latitudes in radians. charm_cell.nlat array elements are associated with charm_cell.latmax

double *lonmin#: Pointer to an array of minimum cell longitudes in radians. charm_cell.nlon array elements are associated with charm_cell.lonmin

double *lonmax#: Pointer to an array of maximum cell longitudes in radians. charm_cell.nlon array elements are associated with charm_cell.lonmax

double *r#: Pointer to an array of spherical radii in metres. charm_cell.nlat array elements are associated with charm_cell.r.

_Bool owner#: If 1, the memory associated with charm_cell.latmin, charm_cell.latmax, charm_cell.lonmin, charm_cell.lonmax and charm_cell.r was allocated by CHarm, so charm_crd_cell_free() deallocates it. If charm_cell.owner is 0, the memory associated with these arrays was allocated outside CHarm, so charm_crd_cell_free() does not deallocate it (the user allocated this memory outside CHarm, so the user should free the memory outside CHarm as well).