Getting started

BUMP can be run in two different ways:

  • as a library from another code (e.g. within OOPS)

  • as a standalone executable

Using BUMP within OOPS

To use BUMP as an ensemble, a static or a hybrid covariance matrix model, you need to proceed in two successive steps:

  1. Run the EstimateParams.h to generate the various operators data.

  2. Run Variational.h or Dirac.h, reading the pre-computed data.

IMPORTANT: both steps should be run with the same number of MPI tasks and the same grid distribution among these tasks.

Operators generation

This section provides some examples of the bump section of the yaml inputs of EstimateParams.h:

  • For an ensemble covariance matrix, the localization operator generated by the NICAS driver BUMP can be set either with forced horizontal and vertical length-scales:

    bump:
      datadir: path_to_bump_directory  # BUMP data directory
      forced_radii: 1                  # Force NICAS length-scales
      method: loc                      # Compute localization parameters
      mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
      new_nicas: 1                     # Run NICAS driver
      ntry: 10                         # Number of tries for and NICAS subsamplings
      prefix: my_bump_files            # BUMP files prefix
      resol: 8.0                       # NICAS subgrid resolution
      rh: 1000.0e3                     # Horizontal radius (in m)
      rv: 2000.0                       # Horizontal radius (in the unit provided in the OOPS-SABER interface)
      strategy: common                 # NICAS multivariate strategy (here: same localization for all variables)
    

    or with length-scales diagnosed from the ensemble:

    bump:
      datadir: path_to_bump_directory  # BUMP data directory
      dc: 500.0e3                      # Distance class size (in m) in HDIAG
      method: loc                      # Compute localization parameters
      mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
      nc1: 500                         # Number of subsampling points in HDIAG
      nc3: 20                          # Number of distance classes in HDIAG
      ne: 10                           # Ensemble size
      new_hdiag: 1                     # Run HDIAG driver
      new_nicas: 1                     # Run NICAS driver
      nl0r: 2                          # Number of reduced levels in HDIAG
      ntry: 10                         # Number of tries for HDIAG and NICAS subsamplings
      prefix: my_bump_files            # BUMP files prefix
      resol: 8.0                       # NICAS subgrid resolution
      strategy: common                 # HDIAG and NICAS multivariate strategy (here: same localization for all variables)
    
  • Similarly for a static covariance matrix, the correlation operator generated by the NICAS driver BUMP can be set either with forced horizontal and vertical length-scales:

    bump:
      datadir: path_to_bump_directory  # BUMP data directory
      forced_radii: 1                  # Force NICAS length-scales
      method: cor                      # Compute correlation parameters
      mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
      new_nicas: 1                     # Run NICAS driver
      ntry: 10                         # Number of tries for and NICAS subsamplings
      prefix: my_bump_files            # BUMP files prefix
      resol: 8.0                       # NICAS subgrid resolution
      rh: 1000.0e3                     # Horizontal radius (in m)
      rv: 2000.0                       # Horizontal radius (in the unit provided in the OOPS-SABER interface)
      strategy: specific_univariate    # NICAS multivariate strategy (here: specific auto-correlation for each variable)
    

    or with length-scales diagnosed from the ensemble:

    bump:
      datadir: path_to_bump_directory  # BUMP data directory
      dc: 500.0e3                      # Distance class size (in m) in HDIAG
      method: cor                      # Compute correlation parameters
      mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
      nc1: 500                         # Number of subsampling points in HDIAG
      nc3: 20                          # Number of distance classes in HDIAG
      ne: 10                           # Ensemble size
      new_hdiag: 1                     # Run HDIAG driver
      new_nicas: 1                     # Run NICAS driver
      nl0r: 2                          # Number of reduced levels in HDIAG
      ntry: 10                         # Number of tries for HDIAG and NICAS subsamplings
      prefix: my_bump_files            # BUMP files prefix
      resol: 8.0                       # NICAS subgrid resolution
      strategy: specific_univariate    # HDIAG and NICAS multivariate strategy (here: specific auto-correlation for each variable)
    

    Other operators that can be useful for the static covariance matrix - vertical balance and variance - can be generated simultaneously using the ensemble. The corresponding yaml keys in the bump section are:

    • For the vertical balance:

      bump: # (continued)
        new_vbal: 1                      # Run VBAL driver
        vbal_block: [0,1,1,0,1,0]        # Activate the multivariate blocks
                                         # Here with 3 variables, the blocks K2, K3 and K5 are activated:
                                         # K = [I  0  0  0]
                                         #     [K1 I  0  0]
                                         #     [K2 K3 I  0]
                                         #     [K4 K5 K6 I]
        vbal_rad: 3000.0e3               # Vertical balance averaging radius
      
    • For the variance:

      bump: # (continued)
        new_var: 1                       # Run VAR driver
        ne: 10                           # Ensemble size
        var_filter: 1                    # Activate variance filtering
        var_niter: 3                     # Number of iterations for the variance filtering
        var_rhflt: 1000.0e3              # Initial radius for the variance filtering
      

Operators application

This section provides some examples of the bump section of the yaml inputs where the pre-computed BUMP operators are read:

  • For the VBAL operator, the bump section is inserted in the StatsVariableChange variable change:

    background error:
      variable changes:
      - variable change: StatsVariableChange
        bump:
          datadir: path_to_bump_directory  # BUMP data directory
          load_vbal: 1                     # Load VBAL data
          vbal_block: [0,1,1,0,1,0]        # Activate the multivariate blocks
          prefix: my_bump_files            # BUMP files prefix
    
  • For the VAR operator, the bump section is inserted in the StdDev variable change:

    background error :
      variable changes:
      - variable change: StdDev
        bump:
          datadir: path_to_bump_directory  # BUMP data directory
          load_var: 1                      # Load VAR data
          prefix: my_bump_files            # BUMP files prefix
    
  • For the localization operator of the ensemble covariance matrix, the bump section is inserted in the background error section, with the localization method key set to BUMP:

    background error:
      covariance model: ensemble           # Covariance model
      localization:
        bump:
          datadir: path_to_bump_directory  # BUMP data directory
          mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
          load_nicas: 1                    # Load NICAS data
          prefix: my_bump_files            # BUMP files prefix
          strategy: common                 # NICAS multivariate strategy
        localization method: BUMP          # Localization method
        localization variables: [array]    # Localization_variables
      members: [array]                     # Ensemble members
    
  • For the correlation operator of the static covariance matrix, the bump section is inserted in the background error section, with the covariance model key set to BUMP:

    background error:
      bump:
        datadir: path_to_bump_directory  # BUMP data directory
        mpicom: 2                        # Number of internal MPI communication steps in NICAS, 2 is good
        load_nicas: 1                    # Load NICAS data
        prefix: my_bump_files            # BUMP files prefix
        strategy: specific_univariate    # NICAS multivariate strategy
      covariance model: BUMP             # Covariance model
    
  • The hybrid covariance matrix is just a linear combination of both ensemble and static covariance matrices. Thus, you can use BUMP for either the ensemble part, the static part, or both:

    background error:
      covariance model: hybrid               # Covariance model
      static:
        # Static covariance model (BUMP or other)
      static weight: float                   # Static weights
      ensemble:
        localization:
          # Localization method (BUMP or other)
          localization method: string        # Localization method
          localization variables: [array]    # Localization_variables
        members: [array]                     # Ensemble members
      ensemble weight: float                 # Ensemble weights
    

    IMPORTANT: the static weight and ensemble weight values are those of \(\beta_s\) and \(\beta_e\), used in the linear combination of the increment components. They are not equal to their squared counterparts \(\beta_s^2\) and \(\beta_e^2\) used in the linear combination of the covariance matrices (see Goals and code organization).

Alias system

If you wish to apply the same NICAS operator to several variables, you can define an alias that is used at both generation and application steps, in order to save computing time and memory.

For instance, the static correlation operator is generated and applied with the method: specific_univariate (specific auto-correlation for each variable), and the same length-scales for the 5 variables: u, v, T, q that are 3D and ps that is 2D.

Instead of running EstimateParams.h for this 5 variables, you can run it for one 3D and one 2D variables only (for instance T and ps), and add the following keys in the yaml file:

bump: # (continued)
  io_keys:
  - T_T
  - ps_ps
  io_values:
  - static_3D
  - static_2D

In the application step, you can use these keys in the yaml file to apply the same 3D operators to all 3D variables:

bump: # (continued)
  io_keys:
  - u_u
  - v_v
  - T_T
  - q_q
  - ps_ps
  io_values:
  - static_3D
  - static_3D
  - static_3D
  - static_3D
  - static_2D

Using BUMP as a standalone executable

The executable bump.x, used for BUMP tests, is available to run all drivers directly, without running OOPS. In this case, two kinds of inputs are required:

  • A grid.nc file containing the coordinates.

  • Ensemble members with the following name: ens$E_$NNNNNN.nc, where:

    • $E is the ensemble number (1 or 2)

    • $NNNNNN is the ensemble member index (six digits)

They should all be placed in the directory datadir, specified in the input yaml file.

Specific reading routines should be implemented. Some are already present:

To add a new model $MODEL in the BUMP executable, you need to write an include file mains/model/model_$MODEL.inc containing two routines:

  • model_$MODEL_coord to get the model coordinates,

  • model_$MODEL_read to read a model field.

You also need to add:

  • corresponding calls in mains/model/type_model.F90,

  • a case for the namelist check in the routine nam_check, contained in src/bump/type_nam.f90.

For models with a regular grid, you can start from AROME, ARPEGE, FV3, GEM, GEOS, GFS, IFS, NEMO, NORCPM and WRF routines. For models with an unstructured grid, you can start from MPAS and RES routines.