pyPDAF.PDAF.get_state

pyPDAF.PDAF.get_state()

Distributing analysis state vector to an array.

The primary purpose of this function is to distribute the analysis state vector to the model. This is attained by the user-supplied function py__distribute_state_pdaf(). One can also use this function to get the state vector for other purposes, e.g. to write the state vector to a file.

In this function, the user-supplied function py__next_observation_pdaf() is executed to specify the number of forecast time steps until the next assimilation step. One can also use the user-supplied function to end the assimilation.

In an online DA system, this function also execute the user-supplied function py__prepoststep_state_pdaf(), when this function is first called. The purpose of this design is to call this function right after pyPDAF.PDAF.init() to process the initial ensemble before using it to initialse model forecast. This user-supplied function will not be called afterwards.

This function is also used in flexible parallel system where the number of ensemble members are greater than the parallel model tasks. In this case, this function is called multiple times to distribute the analysis ensemble.

User-supplied function are executed in the following sequence:

  1. py__prepoststep_state_pdaf (only in online system when first called)

  2. py__distribute_state_pdaf

  3. py__next_observation_pdaf

Parameters:

  • steps (int) – number of forecast time steps for next assimilation The input value can be an arbitrary integer

  • doexit (int) – Whether to exit from forecasts

  • py__next_observation_pdaf (Callable[stepnow:int, nsteps:int, doexit:int, time:float]) –

    Routine to provide number of forecast time steps until next assimilations, model physical time and end of assimilation cycles

    Callback Parameters
    • stepnowint

      • the current time step given by PDAF

    • nstepsint

      • number of forecast time steps until next assimilation; this can also be interpreted as number of assimilation function calls to perform a new assimilation

    • doexitint

      • whether to exit forecasting (1 for exit)

    • timefloat

      • current model (physical) time

    Callback Returns
    • nstepsint

      • number of forecast time steps until next assimilation; this can also be interpreted as number of assimilation function calls to perform a new assimilation

    • doexitint

      • whether to exit forecasting (1 for exit)

    • timefloat

      • current model (physical) time

  • py__distribute_state_pdaf (Callable[dim_p:int, state_p : ndarray[tuple[dim_p], np.float64]]) –

    distribute a state vector from pdaf to the model/any arrays

    Callback Parameters
    • dim_pint

      • PE-local state dimension

    • state_pndarray[tuple[dim_p], np.float64]

      • PE-local state vector

    Callback Returns
    • state_pndarray[tuple[dim_p], np.float64]

      • PE-local state vector

  • py__prepoststep_pdaf (Callable[step:int, dim_p:int, dim_ens:int, dim_ens_l:int, dim_obs_p:int, state_p : ndarray[tuple[dim_p], np.float64], uinv : ndarray[tuple[dim_ens-1, dim_ens-1], np.float64], ens_p : ndarray[tuple[dim_p, dim_ens], np.float64], flag:int]) –

    Processing the ensemble when this function is called by the first time in an online PDAF system before distributing to the model to initialise the next forecast

    Callback Parameters
    • stepint

      • current time step (negative for call before analysis/preprocessing)

    • dim_pint

      • PE-local state vector dimension

    • dim_ensint

      • number of ensemble members

    • dim_ens_lint

      • number of ensemble members run serially on each model task

    • dim_obs_pint

      • PE-local dimension of observation vector

    • state_pndarray[tuple[dim_p], np.float64]

      • pe-local forecast/analysis state (the array ‘state_p’ is generally not initialised in the case of ESTKF/ETKF/EnKF/SEIK, so it can be used freely here.)

    • uinvndarray[tuple[dim_ens-1, dim_ens-1], np.float64]

      • Inverse of the transformation matrix in ETKF and ESKTF; inverse of matrix formed by right singular vectors of error covariance matrix of ensemble perturbations in SEIK/SEEK. not used in EnKF.

    • ens_pndarray[tuple[dim_p, dim_ens], np.float64]

      • PE-local ensemble

    • flagint

      • pdaf status flag

    Callback Returns
    • state_pndarray[tuple[dim_p], np.float64]

      • pe-local forecast/analysis state (the array ‘state_p’ is generally not initialised in the case of ESTKF/ETKF/EnKF/SEIK, so it can be used freely here.)

    • uinvndarray[tuple[dim_ens-1, dim_ens-1], np.float64]

      • Inverse of the transformation matrix in ETKF and ESKTF; inverse of matrix formed by right singular vectors of error covariance matrix of ensemble perturbations in SEIK/SEEK. not used in EnKF.

    • ens_pndarray[tuple[dim_p, dim_ens], np.float64]

      • PE-local ensemble

  • flag (int) – Status flag

Returns:

  • steps (int) – number of forecast time steps for next assimilation The input value can be an arbitrary integer

  • time (float) – current model time

  • doexit (int) – Whether to exit from forecasts

  • flag (int) – Status flag