distribute_local_data_objects_map2alm

subroutine distribute_local_data_objects_map2alm( precompute_plms, pixelization, scan, nlmax, nmmax, nmaps, ncomp, map, map_size, local_map, nmvals, mvals, lda, nplm, local_plm, first_ring, last_ring, local_w8ring, w8ring, myid, numprocs, root, comm)

Purpose:

A general "do-it-all" driver which distributes the map and map weights initially stored on a proc root, precomputes an distribution of the m-modes of processor and, on each proc, computes a relevant set of Plm if requested. To be used after a call to get_local_data_size for a workload balanced distribution.
This routine is 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 considered l value (included);

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

nmaps(*)-- [integer(4b)], a total number of maps (each composed of ncomp component maps) to be distributed over all processors;

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

map_size-- [integer(4b)], a number of pixels in a assumed pixelization corresponding to a set of rings defined by first_ring and last_ring as assigned to each proc;

map-- [real(dp)], a 3dim array of dimensions (0:npixall-1, 1:ncomp, 1:nmaps) on the input storing all the maps on the proc root. This needs to be allocated only on the proc root;

first_ring, last_ring -- [integer(4b)], numbers of a first and last ring which define a sub map (both included) as assigned to each proc;

w8ring-- [real(dp)], an allocated pointer to a 2-dim array of a size (1:nringsall,1:ncomp) storing on a proc root all the ring weights. It needs to be allocated only on the proc root;;

nmvals-- [integer(4b)], a number of m values stored on a given proc;

lda(*)-- [integer(4b)], a leading dimension of local_plm array. Equal either to = ncomp or = nlmax. Meaningfull only for precompute_plms /= 0;

nplm-- [integer(8b)], a total number of precomputed Plm of one kind, (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 a proc root on which the non-distributed data are initially stored;

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 size nmvals containing m values to be processed by a given proc;

local_map-- [real(dp)], an allocated pointer to a 3-dim array of a size (0:map_size-1,1:ncomp,1:nmaps);

local_w8ring-- [real(dp)], an allocated pointer to a 2-dim array of a size (1:last_ring-first_ring+1,1:ncomp) storing a subset of the map weights and distributed over procs in the same way as the map (see Healpix);

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 precompute_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 map and weights need to be stored at the same time as all distributed objects.

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

This routine exceptionally requires a full map to be defined as a 3 dimensional object storing all the info for all components and maps.