Getting started

BUMP parameters

The configuration parameters of BUMP can be divided into two categories: “internal” parameters that are used within the code to perform the required calculations and “external” parameters handling the interactions with the rest of the code (OOPS for instance).

Internal parameters

Internal parameters are briefly described in saber/src/saber/bump/BUMP.h.

External parameters

External parameters are:

  • universe radius: a model file containing length-scales (in m) defining the size of the “known universe” for each MPI task in the domain decomposition.

  • input number of components: a text file containing the number of components in convolution functions, for each variable.

  • input: a list of model files containing various parameters (amplitude, length-scale, tensor components, etc) to define the convolution functions.

  • ensemble: ensemble configuration when the ensemble is not provided by OOPS. Members are read sequentially to limit the memory usage.

  • msvalr: missing value for real numbers.

  • grids: list of sets of BUMP internal parameters. For each item of this list, a independent instance of BUMP is created and the specified BUMP internal parameters override the parameters provided outside of grids.

  • output number of components: a text file containing the number of components in convolution functions, for each variable.

  • output: a list of model files containing various parameters (amplitude, length-scale, tensor components, Dirac test results, etc) estimated in BUMP.

  • operators application: a list of configurations defining operators applied to input fields. Required parameters are:

    • input: a model file containing the input field to read.

    • bump operators: a list of operators to apply, among the following list: “multiplyVbal”, “inverseMultiplyVbal”, “multiplyVbalAd”, “inverseMultiplyAd”, “multiplyStdDev”, “inverseMultiplyStdDev” and “multiplyNicas”.

    • output: a model file where the output field is written.

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 these 5 variables, you can run it for one 3D and one 2D variable 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 with 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 ErrorCovarianceTraining.h to generate the various operators data.

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

Important

For some operators, BUMP can produce “local” files (one per MPI task) or “global” files (a single file) during the first step. If local files are produced, the second step has to be run with the same number of MPI tasks and the same grid distribution among these tasks.

Generating operators

This section provides some examples of the bump section of the yaml inputs of ErrorCovarianceTraining.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: true               # Force NICAS length-scales
  method: loc                      # Compute localization parameters
  new_nicas: true                  # Run NICAS driver
  prefix: my_bump_files            # BUMP files prefix
  resol: 8.0                       # NICAS subgrid resolution
  rh:                              # Horizontal radius (in m)
    var_1: [1000.0e3]              # Single value or vertical profile for the variable "var_1"
    var_2: [2000.0e3]              # Single value or vertical profile for the variable "var_2"
    [...]
  rv:                              # Vertical radius (in the unit provided in the OOPS-SABER interface)
    var_1: [2000.0e3]              # Single value or vertical profile for the variable "var_1"
    var_2: [2000.0e3]              # Single value or vertical profile for the variable "var_2"
    [...]
  strategy: common                 # NICAS multivariate strategy (here: same localization for all variables)
  write_nicas_local: true          # Write local NICAS files

    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
  nc1: 500                         # Number of subsampling points in HDIAG
  nc3: 20                          # Number of distance classes in HDIAG
  ne: 10                           # Ensemble size
  new_hdiag: true                  # Run HDIAG driver
  new_nicas: true                  # Run NICAS driver
  nl0r: 2                          # Number of reduced levels in HDIAG
  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)
  write_hdiag: true                # Write HDIAG files
  write_nicas_local: true          # Write local NICAS files

  • 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: true               # Force NICAS length-scales
  method: cor                      # Compute correlation parameters
  new_nicas: true                  # Run NICAS driver
  prefix: my_bump_files            # BUMP files prefix
  resol: 8.0                       # NICAS subgrid resolution
  rh:                              # Horizontal radius (in m)
    var_1: [1000.0e3]              # Single value or vertical profile for the variable "var_1"
    var_2: [2000.0e3]              # Single value or vertical profile for the variable "var_2"
    [...]
  rv:                              # Vertical radius (in the unit provided in the OOPS-SABER interface)
    var_1: [2000.0e3]              # Single value or vertical profile for the variable "var_1"
    var_2: [2000.0e3]              # Single value or vertical profile for the variable "var_2"
    [...]
  strategy: specific_univariate    # NICAS multivariate strategy (here: specific auto-correlation for each variable)
  write_nicas_local: true          # Write local NICAS files

    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
  nc1: 500                         # Number of subsampling points in HDIAG
  nc3: 20                          # Number of distance classes in HDIAG
  ne: 10                           # Ensemble size
  new_hdiag: true                  # Run HDIAG driver
  new_nicas: true                  # Run NICAS driver
  nl0r: 2                          # Number of reduced levels in HDIAG
  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)
  write_hdiag: true                # Write HDIAG files
  write_nicas_local: true          # Write local NICAS files

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

    • For the streamfunction/velocity potential to horizonal winds variable change:

      bump:
  datadir: path_to_bump_directory  # BUMP data directory
  new_wind: true                   # Run PsiChiToUV driver
  prefix: my_bump_files            # BUMP files prefix
  wind_nlon: 400                   # Number of longitudes for the internal calculation grid
  wind_nlat: 200                   # Number of latitudes for the internal calculation grid
  wind_nsg: 5                      # Number of points for the Savitzky-Golay filter (to estimate smooth derivatives)
  wind_inflation: 1.1              # Wind inflation to compensate for the smoothing
  write_wind_local: true           # Write local PsiChiToUV files

    • For the vertical balance:

      bump:
  datadir: path_to_bump_directory                 # BUMP data directory
  new_vbal: true                                  # Run VBAL driver
  prefix: my_bump_files                           # BUMP files prefix
  vbal_block: [false,true,true,false,true,false]  # 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
  write_vbal: true                                # Write vertical balance
  write_samp_local: true                          # Write local sampling

    • For the variance:

      bump:
  new_var: true          # Run VAR driver
  ne: 10                 # Ensemble size
  prefix: my_bump_files  # BUMP files prefix
  var_filter: true       # Activate variance filtering
  var_niter: 3           # Number of iterations for the variance filtering
  var_rhflt: 1000.0e3    # Initial radius for the variance filtering

Applying operators

Operators pre-computed in the previous section can be applied within SABER blocks. The common parameters of SABER blocks are described here. The bump section is the only additional parameter required for the BUMP-based SABER blocks.

  • BUMP_NICAS block:

    bump:
  datadir: path_to_bump_directory  # BUMP data directory
  load_nicas_local: true           # Load local NICAS data
  prefix: my_bump_files            # BUMP files prefix
  strategy: common                 # NICAS multivariate strategy

  • BUMP_PsiChiToUV block:

    bump:
  datadir: path_to_bump_directory  # BUMP data directory
  load_wind_local: true            # Load local PsiChiToUV data
  prefix: my_bump_files            # BUMP files prefix

  • BUMP_StdDev block:

    bump:
  datadir: path_to_bump_directory  # BUMP data directory
  load_var: true                   # Load VAR data
  prefix: my_bump_files            # BUMP files prefix

  • BUMP_VerticalBalance block:

    bump:
  datadir: path_to_bump_directory                 # BUMP data directory
  load_samp_local: true                           # Load local sampling data
  load_vbal: true                                 # Load VBAL data
  vbal_block: [false,true,true,false,true,false]  # Activate the multivariate
                                                  # 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]
  prefix: my_bump_files                           # BUMP files prefix

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.