distribute_local_data_objects_alm2map

subroutine distribute_local_data_objects_alm2map( int precompute_plms, pixeltype pixelization, scandef scan, int nlmax, int nmmax, int nmaps, int ncomp, int lda, s2hat_dcomplex *alms, int nmvals, int *mvals, s2hat_dcomplex *local_alm, long int nplm, double *local_plm, int myid, int numprocs, int root, MPI_Comm comm)

Purpose:

A general "do-it-all" driver which determines the distribution of and distributes the alm initially stored on a proc root. Also it precomputes Plm if required (precompute_plms /= 0). To be used together (and after) the call to get_local_data_size for a workload balanced distribution and preceding a call to one of the alm2map transform routines.
This routine needs to be called by all procs of the communicator comm. Blocking.

Parameter description:

input:

precompute_plms(*)-- [int], (= 0,1,2) for no precomputation precomputation of only scalar, and of both scalar and spin associated Legendre functions in a distributed form, respectively, if ncomp == 2 (i.e., spin transforms are to be performed) then precompute_plms is forced to be 0;

pixelization(*)-- [pixeltype], an S2HAT structure containing the info about the pixelization;

scan(*)-- [scandef], an S2HAT structure containing the info about the sky coverage;

nlmax(*)-- [int], maximum value of l considered (included);

nmmax(*)-- [int], maximum value of m considered (included);

nmaps(*)-- [int], a number of the alm sets (each made of ncomp components);

ncomp(*)-- [int], a number of components of every alm set to be distributed (=1,2,3);

lda(*)-- [int], defines the leading dimension of the alm, local_alm and local_plm matrices. Accepted values: lda == ncomp or nlmax;

alms-- [s2hat_dcomplex*], a vector of complex numbers corresponding to a 4-dim array of dimensions:

(0:nlmax, 0:nmmax, 1:ncomp, 1:nmaps) if lda == nlmax
(1:ncomp, 0:nlmax, 0:nmmax, 1:nmaps) if lda == ncomp

stored in the column-wise ordered. Has to be allocated and defined only on the proc root and stores all the alm coefficients which need to be distributed;

nmvals-- [int], a number of m values to be processed by a given proc;

nplm-- [long int (8bytes)], defines one of the two dimensions of the local_plm array. It is equal to a product of a number of all rings (Northern hemisphere plus equator) times a number of all l,m processed by a given proc. The value of this parameter is irrelevant if precompute_plms == 0;

myid-- [int], proc id (0,...,numprocs-1);

numprocs(*)-- [int], total number of procs used;

root(*)-- [int], defines root processor on which the alm coefficients are stored in a non-distributed form;

comm(*)-- [MPI_Comm], an mpi communicator for the numprocs procs.

(*)The value must be the same on all procs of the communicator comm.

output:

mvals-- [int*], a vector of a length nmvals containing a list of m values to be processed by a given proc;

local_alm-- [s2hat_dcomplex*], a vector of complex numbers storing a 4dim array of dimensions:

(1:ncomp,0:nlmax,0:nmvals-1,1:nmaps), if lda == ncomp;      (HEALpix convention);
(0:nlmax,0:nmvals-1,1:ncomp,1:nmaps), if lda == nlmax;      (S2HAT convention);

in the column-wise order. It contains relevant subset of the alm coefficients. Those corresponds to all m values processed on a given proc and all l and all ncomp components for each of the nmaps maps which are to be processed simultanously; For ncomp == 1 the coefficients are those for total intensity only. For ncomp == 3 the component corresponds to the total intensity, E-mode and B-mode polarizations, respectively. For ncomp == 2 the stored components are those of E and B-like.;

local_plm-- [double*], a vector of doubles corresponding to a 2dim array stored in the column-wise order. The layout of the 2dim array depends on the value of lda parameter as for the local_alm array (and must agree with it),

(1:nprec,0:nplm-1), if lda == ncomp;      (HEALpix convention);
(0:nplm-1,1:nprec), if lda == nlmax;      (S2HAT convention);

where
nprec = 1 if precompute_plms == 1, i.e., only scalar Plm are precomputed,
nprec = 3 if precompute_plms == 2, i.e., scalar and spin-2 Plm are precomputed.

It is relevant only if precompute_plms is not zero, and then: if precommpute_plms == 1, it contains only scalar Plm precomputed for every ring of the map and subset of m values as defined by a vector mvals. If precompute_plms == 2, it stores a scalar and two spin-2 harmonics (the conventions and normalizations of which are as defined in Healpix.

Comments:

memory inefficient as on the root a full suite of alm needs to be stored at the same time as all distributed objects.

all output (distributed) objects need to be allocated beforehand by the user.

exceptionally this routine requires the input alm matrix to be 4 dimensional and storing all the alm sets for all components and all maps at the same time.