= PDAF3_init_parallel =

This page documents the routine `PDAF3_init_parallel` of PDAF. The routine was introduced with PDAF V3.1. 

The routine `PDAF3_set_parallel` is called in `init_parallel_pdaf` to initialize the parallelization configuration inside PDAF and return the information to the user code. 

Note: In PDAF V3.0, the actual initialization of the parallelization was done directly in `init_parallel_pdaf` and then provided to PDAF by calling [wiki:PDAF3_set_parallel]. In PDAF V3.1 and later one does no longer need this functionality in the user code.

For calling the routine one sets the ensemble size (`dim_ens`) and number of parallel model tasks (`n_modeltasks`). In addition, one provides the MPI communicator that was initialized by the model (`COMM_model`) or the main program in case of offline coupled DA. The routine updates the model communicator for the ensemble setup. Further, it provides the rank and size information for the model commuicator. Further the communicator of processes that execute the analysis step (`COMM_assim`) and the related process rank and size information is provided. The latter can be used in call-back routines that are executed during the analysis step.


The interface is the following:
{{{
  SUBROUTINE PDAF3_init_parallel(screen, type_parallel, online_coupling, dim_ens, n_modeltasks, &
       COMM_model, mype_model, npes_model, COMM_assim, mype_assim, npes_assim, &
       task_id)

    ! Input variables
    INTEGER, INTENT(in)    :: screen          ! >0 for display information about the parallelization setup
    INTEGER, INTENT(in) :: type_parallel      ! Type of parallelization (currently not uesed)
    INTEGER, INTENT(in) :: online_cpl         ! 1: online DA coupling, 0: offline DA coupling
    INTEGER, INTENT(in) :: dim_ens            ! Ensemble size

    ! Input variables that might be updated in the routine
    INTEGER, INTENT(inout) :: n_modeltasks    ! Number of model tasks
    INTEGER, INTENT(inout) :: COMM_model      ! Input: Model MPI communicator
                                              ! Output: Model communicator split for model tasks
    ! Output variables
    INTEGER, INTENT(out) :: npes_model        ! Number of Processs in COMM_model
    INTEGER, INTENT(out) :: mype_model        ! Process rank in COMM_model
    INTEGER, INTENT(out) :: COMM_assim        ! MPI communicator for assimilation processes 
    INTEGER, INTENT(out) :: npes_assim        ! Number of processes in COMM_assim
    INTEGER, INTENT(out) :: mype_assim        ! Process rank in COMM_assim
    INTEGER, INTENT(out) :: task_id           ! Index of my model task (1,...,n_modeltasks)
}}}

Notes:
* The configuration of the parallelization is what we found to be 'typically working'. If one has a particular case, one can instead do the communicator configuration in the user code and then call [wiki:PDAF3_set_parallel] to provide PDAF with the configuration.
* In cases that the ensemble parallelization is readily prepared by the model, one can directly use [wiki:PDAF3_set_parallel] to provide PDAF with the configuration of the parallelization.
* The template and tutorial codes show the use of `PDAF3_init_parallel` in the file `init_parallel_pdaf.F90`.
* For the offline DA coupling, the routine always sets `n_modeltasks=1` independent of the input value.
* The routine can be called without a prior initialization of the MPI environment (i.e. call to MPI_init). In this case the routine will initialize MPI and then perform the the parallelization setup according to the values of `n_modeltasks` and `dim_ens`.
* The value of `n_modeltasks` cannot be larger than the number of processes in the execution of the DA program. If this is the case, the routine sets `n_modeltasks=npes_model`
* The value of `dim_ens` is used for consistency checking (`n_modeltasks` cannot be larger than `dim_ens`; if this is the case, the routine sets `n_modeltasks=dim_ens`). The check is deactivated with `dim_ens=0` is provided to the routine.