distribute_local_data_objects_alm2map

subroutine distribute_local_data_objects_alm2map( precompute_plms, pixelization, scan, nlmax, nmmax, nmaps, ncomp,lda, alms, nmvals, mvals, local_alm, nplm, local_plm, myid, numprocs, root, 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 (after) the call to get_local_data_size for a workload balanced distribution.
This routine needs to be called by all procs of the communicator comm. Blocking.

Parameter description:

input:

precompute_plms(*)-- [integer(4b)], (= 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(*)-- [integer(4b)], maximum value of l (included);

nmmax(*)-- [integer(4b)], maximum value of m (included);

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

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

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

alms-- [complex(dp)], an allocated (on the proc root only) pointer 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

and which, on the proc root stores all the alm coefficients which need to be distributed;

nmvals-- [integer(4b)], a number of m values to be processed by a given proc;

nplm-- [integer(8b)], 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-- [integer(4b)], proc id (0,...,numprocs-1);

numprocs(*)-- [integer(4b)], total number of procs used;

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

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

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

output:

mvals-- [integer(4b)], a vector of a length nmvals containing a list of m values to be processed by a given proc;

local_alm-- [complex(dp)], an allocated pointer to 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);

storing relevant alm coefficients for 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;

local_plm-- [real(dp)], an allocated (if needed) pointer to a 2dim array. 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. The layout of the 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.

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.