charm_crd#
Module to work with the coordinates of evaluation points/cells:
defines
charm_point
andcharm_cell
structures,allocates, initializes and frees
charm_point
andcharm_cell
,computes
charm_point
for a few predefined grid types.
References:
Sneeuw, N. (1994) Global spherical harmonic analysis by leastsquares and numerical quadrature methods in historical perspective. Geophysical Journal International 118:707716
Driscoll, J. R., Healy, D. M. (1994) Computing Fourier transforms and convolutions on the 2sphere. Advances in Applied Mathematics 15:202250
Wieczorek, M. A., Meschede, M. (2018) SHTools: Tools for Working with Spherical Harmonics. Geochemistry, Geophysics, Geosystems 19:25742592
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
withnlat
latitudes,nlon
longitudes andnlat
spherical radii. Iftype
isCHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
orCHARM_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 constantsCHARM_CRD_POINT_SCATTERED
,CHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
andCHARM_CRD_POINT_GRID_DH2
.For
charm_point *pnt
returned by this function withtype
beingCHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
orCHARM_CRD_POINT_GRID_DH2
, the coordinates of the grid point on thei
th latitude parallel and thej
th meridian have to be accessed aspnt>lat[i]
for the grid latitude,pnt>lon[j]
for the grid longitude, andpnt>r[i]
for the spherical radii
with
i = 0, 1, ..., nlat  1
andj = 0, 1, ..., nlon  1
.For
type
set toCHARM_CRD_POINT_SCATTERED
, the coordinates of thei
th point have to be accessed aspnt>lat[i]
for the grid latitude,pnt>lon[i]
for the grid longitude, andpnt>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 withfree
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 oftype
).

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
, takesnlat
spherical latitudes from the array pointed to bylat
,nlon
spherical longitudes fromlon
andnlat
spherical radii fromr
(shallow copy).Valid values of
type
are constantsCHARM_CRD_POINT_SCATTERED
,CHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
andCHARM_CRD_POINT_GRID_DH2
.If
type
isCHARM_CRD_POINT_SCATTERED
,nlat
must be equal tonlon
andeach of
lat
,lon
andr
must have access tonlat
elements.
If
type
isCHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
orCHARM_CRD_POINT_GRID_DH2
,lat
must have access tonlat
elements,lon
must have access tonlon
elements, andr
must have access tonlat
elements.
Note
See
charm_crd_point_malloc()
to find out how to access the coordinates stored in the returnedcharm_point
structure.Note
See
charm_shc_init()
for the rationale behind the shallow copies of input arrayslat
,lon
andr
. The memory of these arrays must be treated in the same fashion as shown therein with thec
ands
arrays.Warning
The structure returned must be deallocated using
charm_crd_point_free()
. The usual deallocation withfree
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 oftype
).

void charm_crd_point_free(charm_point *pnt)#
Frees the memory associated with
pnt
. No operation is performed ifpnt
isNULL
.If
pnt>owner
is1
, the function releases all the memory that is associated withpnt
, including that of its array members. Ifpnt>owner
is0
, the arrays are not released from the memory, because they were not allocated by CHarm.
Quadrature point grids
These functions compute the GaussLegendre and DriscollHealy quadrature grids and the associated integration weights.

charm_point *charm_crd_point_gl(unsigned long nmax, double r)#
Computes the GaussLegendre grid associated with the harmonic degree
nmax
(Sneeuw, 1994) on the sphere with the radiusr
. The integration weights are computed on the unit sphere.Loops are parallelized using OpenMP.
Note
The GaussLegendre grid is nonequiangular in latitude. The longitudinal step is constant.
Warning
The structure returned must be deallocated by calling
charm_crd_point_free()
. The usual deallocation withfree
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 ifnmax
is larger than7200
or so. The overflow check is not performed if the output fromcharm_misc_buildopt_isfinite()
is zero.

charm_point *charm_crd_point_dh1(unsigned long nmax, double r)#
Computes the nonequiangular DriscollHealy grid (as defined by Driscoll and Healy, 1994) associated with the maximum spherical harmonic degree
nmax
on the sphere with the radiusr
. 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 withfree
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 DriscollHealy 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
withnlat
minimum and maximum latitudes,nlon
minimum and maximum longitudes andnlat
spherical radii. The memory of all array elements is uninitialized, so their values are undefined.Valid values of
type
are constantsCHARM_CRD_CELL_GRID
andCHARM_CRD_CELL_SCATTERED
.For
charm_cell *cell
returned by this function withtype
beingCHARM_CRD_CELL_GRID
, the coordinates of the grid cell on thei
th latitude parallel and thej
th meridian have to be accessed ascell>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
andj = 0, 1, ..., nlon  1
.For
type
set toCHARM_CRD_CELL_SCATTERED
, the coordinates of thei
th cell have to be accessed ascell>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 withfree
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 oftype
).

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
, takesnlat
minimum and maximum spherical latitudes from the arrays pointed to bylatmin
andlatmax
,nlon
minimum and maximum spherical longitudes fromlonmin
andlonmax
andnlat
spherical radii fromr
, respectively (shallow copy).Accepted values of
type
areCHARM_CRD_CELL_GRID
andCHARM_CRD_CELL_SCATTERED
.If
type
isCHARM_CRD_CELL_SCATTERED
,nlat
must be equal tonlon
andeach of
latmin
,latmax
,lonmin
,lonmax
andr
must have access tonlat
elements.
If
type
isCHARM_CRD_CELL_GRID
,latmin
andlatmax
must each have access tonlat
elements,lonmin
andlonmax
must each have access tonlon
elements,r
must have access tonlat
elements.
Note
See
charm_crd_cell_malloc()
to find out how to access the coordinates stored in the returnedcharm_cell
structure.Note
See
charm_shc_init()
for the rationale behind the shallow copies of input arrayslatmin
,latmax
,lonmin
,lonmax
andr
. The memory of these arrays must be treated in the same fashion as shown therein with thec
ands
arrays.Warning
The structure created by this function must be deallocated using
charm_crd_cell_free()
. The usual deallocation withfree
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 oftype
).

void charm_crd_cell_free(charm_cell *cell)#
Frees the memory associated with
cell
. No operation is performed ifcell
isNULL
.If
cell>owner
is1
, the function releases all the memory that is associated withcell
, including that of its array members. Ifcell>owner
is0
, 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
toCHARM_CRD_POINT_SCATTERED
,CHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
,CHARM_CRD_POINT_GRID_DH2
. Forcharm_cell.type
, valid constants areCHARM_CRD_CELL_SCATTERED
andCHARM_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#
GaussLegendre point grid.

enumerator CHARM_CRD_POINT_GRID_DH1#
DriscollHealy point grid as defined by Driscoll and Healy (1994) (nonequiangular).

enumerator CHARM_CRD_POINT_GRID_DH2#
The equiangular modification of the DriscollHealy point grid after Wieczorek and Meschede (2018).

enumerator CHARM_CRD_CELL_GRID = 2#

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 userdefined scattered points,CHARM_CRD_POINT_GRID
for a userdefined grid,CHARM_CRD_POINT_GRID_GL
for the GaussLegendre grid (Sneeuw, 1994) withnmax + 1
latitudes and2 * nmax + 2
longitudes (nmax
is maximum harmonic degree),CHARM_CRD_POINT_GRID_DH1
for the nonequiangular DriscollHealy grid as defined by Driscoll and Healy (1994) with2 * nmax + 2
latitudes and2 * nmax + 2
longitudes, andCHARM_CRD_POINT_GRID_DH2
for an equiangular modification of the DriscollHealy grid (Wieczorek and Meschede, 2018) with2 * nmax + 2
latitudes and4 * nmax + 4
longitudes.

size_t nlat#
Number of latitudes.
For scattered points (
charm_point.type
isCHARM_CRD_POINT_SCATTERED
),charm_point.nlat
represents the total number of points in thecharm_point
structure.For grids (
charm_point.type
isCHARM_CRD_POINT_GRID
,CHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
orCHARM_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 thecharm_point
structure.charm_point.nlon
must be equal tocharm_point.nlat
. The total number of points ischarm_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
andcharm_point.nlon
may be different. The total number of grid points ischarm_point.nlat * charm_point.nlon
.

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

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

double *r#
Pointer to an array of spherical radii in metres.
charm_point.nlat
array elements are associated withcharm_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 forcharm_point
structures returned by thecharm_crd_point_gl()
,charm_crd_point_dh1()
andcharm_crd_point_dh2()
functions, that is, ifcharm_point.type
isCHARM_CRD_POINT_GRID_GL
,CHARM_CRD_POINT_GRID_DH1
, orCHARM_CRD_POINT_GRID_DH2
.charm_point.nlat
array elements are associated withcharm_point.w
.For all other values of
charm_point.type
,charm_point.w
isNULL
and is never used.

_Bool owner#
If
1
, the memory associated withcharm_point.lat
,charm_point.lon
,charm_point.r
andcharm_point.w
was allocated by CHarm, socharm_crd_point_free()
deallocates it. Ifcharm_point.owner
is0
, the memory associated with these arrays was allocated outside CHarm, socharm_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).

int type#

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 userdefined grid of cells,CHARM_CRD_CELL_SCATTERED
for a userdefined set of scattered cells.

size_t nlat#
Number of latitudes.
For scattered cells (
charm_cell.type
set toCHARM_CRD_CELL_SCATTERED
),charm_cell.nlat
represents the total number of cells in thecharm_cell
structure.For grids (
charm_cell.type
set toCHARM_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 thecharm_cell
structure.charm_cell.nlon
must be equal tocharm_cell.nlat
. The total number of cells is equal tocharm_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
andcharm_cell.nlon
may be different. The total number of grid cells ischarm_cell.nlat * charm_cell.nlon
.

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

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

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

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

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

_Bool owner#
If
1
, the memory associated withcharm_cell.latmin
,charm_cell.latmax
,charm_cell.lonmin
,charm_cell.lonmax
andcharm_cell.r
was allocated by CHarm, socharm_crd_cell_free()
deallocates it. Ifcharm_cell.owner
is0
, the memory associated with these arrays was allocated outside CHarm, socharm_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).

int type#