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:
Run the
EstimateParams.hto generate the various operators data.Run
Variational.horDirac.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
bumpsection 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
bumpsection is inserted in theStatsVariableChangevariable 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
bumpsection is inserted in theStdDevvariable 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
bumpsection is inserted in thebackground errorsection, with thelocalization methodkey set toBUMP: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
bumpsection is inserted in thebackground errorsection, with thecovariance modelkey set toBUMP: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 weight 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 weight
Here,
static weightandensemble weightcorrespond respectively to the \(\beta_s^2\) and \(\beta_e^2\) coefficients 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.ncfile containing the coordinates.Ensemble members with the following name:
ens$E_$NNNNNN.nc, where:$Eis the ensemble number (1 or 2)$NNNNNNis 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_coordto get the model coordinates,model_$MODEL_readto 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 insrc/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.