= 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, n_modeltasks, dim_ens, &
       COMM_model, mype_model, npes_model, COMM_assim, mype_assim, npes_assim, &
       task_id)

    INTEGER, INTENT(in)    :: screen          ! >0 for display information about the parallelization setup

    ! Input variables
    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 variable that might be updated in the routine
    INTEGER, INTENT(inout) :: n_modeltasks    ! Number of model tasks
    INTEGER, INTENT(out) :: 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.