Initialization functions.

Functions
long	nlm_calc (long lmax, long mmax, long mres)
	compute number of spherical harmonics modes (l,m) to represent a real-valued spatial field for given size parameters. Does not require any previous setup.
long	nlm_cplx_calc (long lmax, long mmax, long mres)
	compute number of spherical harmonics modes (l,m) to represent a complex-valued spatial field, for given size parameters. Does not require any previous setup.
shtns_cfg	shtns_create (int lmax, int mmax, int mres, enum shtns_norm norm)
	Defines the sizes of the spectral description. Use for advanced initialization.
shtns_cfg	shtns_create_with_grid (shtns_cfg base, int mmax, int nofft)
	Copy a given config but allow a different (smaller) mmax and the possibility to enable/disable fft (beta).
void	shtns_unset_grid (shtns_cfg shtns)
	release all resources allocated by a grid.
void	shtns_destroy (shtns_cfg shtns)
	release all resources allocated by a given shtns_cfg. NOT thead-safe.
void	shtns_reset ()
	clear all allocated memory (hopefully) and go back to 0 state. NOT thread-safe.
void *	shtns_malloc (size_t size)
	allocate appropriate CPU memory (pinned for gpu, aligned for avx, ...). Use shtns_free to free it.
void	shtns_free (void *p)
	free memory allocated with shtns_malloc
int	shtns_set_grid_auto (shtns_cfg shtns, enum shtns_type flags, double eps, int nl_order, int *nlat, int *nphi)
	Precompute everything and choose the optimal nlat and nphi for a given non-linear order.
int	shtns_set_grid (shtns_cfg shtns, enum shtns_type flags, double eps, int nlat, int nphi)
	Precompute everything for a given spatial grid. Use for advanced initialization, after shtns_create.
int	shtns_set_many (shtns_cfg shtns, const int howmany, long spec_dist)
	Batched transforms, with some constraints.
shtns_cfg	shtns_init (enum shtns_type flags, int lmax, int mmax, int mres, int nlat, int nphi)
	Simple initialization of the spherical harmonic transforms of given size. Calls shtns_create and shtns_set_grid_auto.
void	shtns_robert_form (shtns_cfg shtns, int robert)
	set the use of Robert form. If robert != 0, the vector synthesis returns a field multiplied by sin(theta), while the analysis divides by sin(theta) before the transform.
int	shtns_use_threads (int num_threads)
	Enables OpenMP parallel transforms, if available (see Compiling and installing SHTns).
int	shtns_gauss_wts (shtns_cfg shtns, double *wts)
	fill the given array with quadrature weights.

Detailed Description

Function Documentation

nlm_calc()

long nlm_calc	(	long	lmax,
		long	mmax,
		long	mres )

compute number of spherical harmonics modes (l,m) to represent a real-valued spatial field for given size parameters. Does not require any previous setup.

return (mmax+1)*(lmax+1) - mres*(mmax*(mmax+1))/2; 

*‍/

nlm_cplx_calc()

long nlm_cplx_calc	(	long	lmax,
		long	mmax,
		long	mres )

compute number of spherical harmonics modes (l,m) to represent a complex-valued spatial field, for given size parameters. Does not require any previous setup.

return mmax*mmax*mres + (2*mmax+1)*(lmax-mmax*mres+1); 

*‍/

shtns_create()

shtns_cfg shtns_create	(	int	lmax,
		int	mmax,
		int	mres,
		enum shtns_norm	norm )

Defines the sizes of the spectral description. Use for advanced initialization.

This sets the description of spherical harmonic coefficients. It tells SHTns how to interpret spherical harmonic coefficient arrays, and it sets usefull arrays. Returns the configuration to be passed to subsequent transform functions, which is basicaly a pointer to a shtns_info struct.

Parameters

lmax	: maximum SH degree that we want to describe.
mmax	: number of azimutal wave numbers.
mres	: 2.pi/mres is the azimutal periodicity. mmax*mres is the maximum SH order.
norm	: define the normalization of the spherical harmonics (shtns_norm) optionaly disable Condon-Shortley phase (ex: sht_schmidt | SHT_NO_CS_PHASE) optionaly use a 'real' normalization (ex: sht_fourpi | SHT_REAL_NORM)

Condon-Shortley phase (-1)^m is used by default.

renormalization of m>0.

shtns_create_with_grid()

shtns_cfg shtns_create_with_grid	(	shtns_cfg	base,
		int	mmax,
		int	nofft )

Copy a given config but allow a different (smaller) mmax and the possibility to enable/disable fft (beta).

Copy a given config but allow a different (smaller) mmax and the possibility to enable/disable fft.

shtns_destroy()

void shtns_destroy

(

shtns_cfg

shtns

)

release all resources allocated by a given shtns_cfg. NOT thead-safe.

free memory of given config, which cannot be used afterwards.

shtns_gauss_wts()

int shtns_gauss_wts	(	shtns_cfg	shtns,
		double *	wts )

fill the given array with quadrature weights.

fill the given array with Gauss weights. returns the number of weights written (0 if not a Gauss grid).

returns the number of weights written, which may be zero if the grid has no quadrature rule

shtns_init()

shtns_cfg shtns_init	(	enum shtns_type	flags,
		int	lmax,
		int	mmax,
		int	mres,
		int	nlat,
		int	nphi )

Simple initialization of the spherical harmonic transforms of given size. Calls shtns_create and shtns_set_grid_auto.

Simple initialization of Spherical Harmonic transforms (backward and forward, vector and scalar, ...) of given size. This function sets all global variables by calling shtns_create followed by shtns_set_grid, with the default normalization and the default polar optimization (see sht_config.h). Returns the configuration to be passed to subsequent transform functions, which is basicaly a pointer to a shtns_info struct.

Parameters

lmax	: maximum SH degree that we want to describe.
mmax	: number of azimutal wave numbers.
mres	: 2.pi/mres is the azimutal periodicity. mmax*mres is the maximum SH order.
nlat,nphi	: respectively the number of latitudinal and longitudinal grid points.
flags	allows to choose the type of transform (see shtns_type) and the spatial data layout (see Spatial data layouts and grids used by SHTns)

shtns_reset()

void shtns_reset

(

void

)

clear all allocated memory (hopefully) and go back to 0 state. NOT thread-safe.

destroy all configs, free memory, and go back to initial state.

shtns_set_grid()

int shtns_set_grid	(	shtns_cfg	shtns,
		enum shtns_type	flags,
		double	eps,
		int	nlat,
		int	nphi )

Precompute everything for a given spatial grid. Use for advanced initialization, after shtns_create.

Initialization of Spherical Harmonic transforms (backward and forward, vector and scalar, ...) of given size. This function must be called after shtns_create and before any SH transform. and sets all global variables. returns the required number of doubles to be allocated for a spatial field.

Parameters

shtns	is the config created by shtns_create for which the grid will be set.
flags	allows to choose the type of transform (see shtns_type) and the spatial data layout (see Spatial data layouts and grids used by SHTns)
eps	polar optimization threshold : polar values of Legendre Polynomials below that threshold are neglected (for high m), leading to increased performance (a few percents) 0 = no polar optimization; 1.e-14 = VERY safe; 1.e-10 = safe; 1.e-6 = aggresive, but still good accuracy.
nlat,nphi	respectively the number of latitudinal and longitudinal grid points.

shtns_set_grid_auto()

int shtns_set_grid_auto	(	shtns_cfg	shtns,
		enum shtns_type	flags,
		double	eps,
		int	nl_order,
		int *	nlat,
		int *	nphi )

Precompute everything and choose the optimal nlat and nphi for a given non-linear order.

Initialization of Spherical Harmonic transforms (backward and forward, vector and scalar, ...) of given size. This function must be called after shtns_create and before any SH transform. and sets all global variables and internal data. returns the required number of doubles to be allocated for a spatial field.

Parameters

shtns	is the config created by shtns_create for which the grid will be set.
nlat,nphi	pointers to the number of latitudinal and longitudinal grid points respectively. If 0, they are set to optimal values.
nl_order	defines the maximum SH degree to be resolved by analysis : lmax_analysis = lmax*nl_order. It is used to set an optimal and anti-aliasing nlat. If 0, the default SHT_DEFAULT_NL_ORDER is used.
flags	allows to choose the type of transform (see shtns_type) and the spatial data layout (see Spatial data layouts and grids used by SHTns)
eps	polar optimization threshold : polar values of Legendre Polynomials below that threshold are neglected (for high m), leading to increased performance (a few percents) 0 = no polar optimization; 1.e-14 = VERY safe; 1.e-10 = safe; 1.e-6 = aggresive, but still good accuracy.

shtns_set_many()

int shtns_set_many	(	shtns_cfg	shtns,
		const int	howmany,
		long	spec_dist )

Batched transforms, with some constraints.

Sets the number of transforms to be performed together (batch). Must be called before shtns_set_grid or shtns_set_grid_auto. Useful to get good performance for small transforms on GPU, but also works on CPU.

Currently only theta-contiguous data is allowed. This function must be called before shtns_set_grid or shtns_set_grid_auto, after which the spatial datat layout will be defined by shtns->nlat_padded and shtns->nspat as:

data[(i_batch*shtns->nphi + i_phi)*shtns->nlat_padded + i_theta] 

Note that shtns->nspat will be the number of spatial points in howmany fields (not in a single field).

Parameters

[in]	shtns	= a plan created by shtns_create that should handle many transforms at once.
[in]	howmany	= number of transforms in batch.
[in]	spec_dist	= distance between spectral arrays in batch. Spectral data is accessed with Qlm[i_batch * spec_dist + lm]

Returns

howmany on success, or -1 on failure.

shtns_unset_grid()

void shtns_unset_grid

(

shtns_cfg

shtns

)

release all resources allocated by a grid.

unset the grid.

shtns_use_threads()

int shtns_use_threads

(

int

num_threads

)

Enables OpenMP parallel transforms, if available (see Compiling and installing SHTns).

Enables multi-thread transform using OpenMP with num_threads (if available). Returns number of threads that will be used.

Call before any initialization of shtns to use multiple threads. Returns the actual number of threads.

• If num_threads > 0, specifies the maximum number of threads that should be used.
• If num_threads <= 0, maximum number of threads is automatically set to the number of processors.
• If num_threads == 1, openmp will be disabled.