User Options Configuration

This guide explains the user_options.yaml configuration file used to control BOAR’s behavior.

General Options

The general_options section controls basic BOAR behavior.

general_options:
  'clear_start': True       # [bool] Re-create output directory on start
  'silent': True            # [bool] Suppress log messages
  'log_dev': False          # [bool] Print all logs including simulation logs

BASEMENT Options

The basement_options section controls BASEMENT simulation settings.

basement_options:
  'cleanup': False          # [bool] Remove previous results before running
  'backend': omp            # [str] Backend: seq, omp, cuda, cudaC, cudaO
  'nthreads': -1            # [int] Number of cores (-1 = all available)

Backend Options

Option

Description

seq

Sequential (single-threaded) execution

omp

OpenMP (multi-threaded) execution

cuda

CUDA execution

cudaC

CUDA execution with sequential CPU processor

cudaO

CUDA execution with OpenMP CPU processor

Simulation Options

Configure discharge files and simulation inputs.

simulation_options:
  'discharge_file': True                                # [bool] Define the model setup discharge using a TXT file. (Default: False)
  'discharge_file_directory': /path/to/discharge_files  # [str] Directory containing discharge files. Only required if 'discharge_file' is True.
  'discharge_file_list': ['Q001.txt', 'Q002.txt']       # [list] List of discharge files to use. Only required if 'discharge_file' is True.

Optimization Variable Options

The optimization_variable_options section defines the calibration parameters.

optimization_variable_options:
  'initial_vector': file                 # [str] file, float, or list. (Default: file)
  'regions': ['floodplain']              # [list] Regions to optimize. (Default: all friction regions)
  'constraints': None                    # [dict] Parameter constraints. (Default: None, see below)
  'bounds': None                         # [list] Optimization bounds. (Default: None)
  'precision': 1e-1                      # [float] Decimal precision. (Default: 1)
  'save_errors': True                    # [bool] Save error points to CSV. (Default: False)
  'save_tried_vectors': False            # [bool] Save all results files. (Default: False)
  'opt_engine': False                    # [str] Optimization engine ("boar" or "optuna"). Default: "boar"

Initial Vector Options

Option

Description

file

Read initial friction from simulation file

float

Use a constant value for initial friction

list

Use array of constant values (region_id, value)

Constraints

It is recommended to avoid constraints as they may lead to local minima.

'constraints': {
    'expression': "x > y or np.isclose(x, y)",  # Constraint expression
    'variables': ['x', 'y']                       # Region/variable names
}

Example expressions:

# Floodplain roughness > main channel roughness
"x > y"

# Floodplain roughness equals main channel roughness
"np.isclose(x, y)"

# Floodplain > main channel OR floodplain equals channel
"x > y or np.isclose(x, y)"

Bounds

Define optimization bounds for each region.

# Single region bounds
'bounds': [!!python/tuple [10, 60]]

# Multiple region bounds
'bounds': [!!python/tuple [1, 12], !!python/tuple [2, 100]]

Sampling Options

The sampling_options section controls initial sampling strategies.

sampling_options:
  'max_lhs_runs': 200   # Number of samples for Latin Hypercube Sampling
  'seed': 42            # Random number generator seed (None for random)

Surrogate Model Options

The surrogate_model_options section controls the Gaussian Process Regression model.

surrogate_model_options:
  'tolerance': 1e-4                 # [float] Stop criterion
  'n_initial': 5                    # [int] Min samples before optimization. (Default: 5)
  'max_tested_vectors': 100         # [int] Max vectors to try. (Default: 100)
  'opt_mem_override': False         # [bool] Override memory check. (Default: False)

# Only used if 'opt_engine' is set to "boar"
  'test_population': 67956            # [int] Surrogate model samples
  'max_no_improvement': 10            # [int] Max iterations without progress (Default: 100)
  'GPR_iterations': 500               # [int] The number of restarts of the optimizer for finding the kernel’s parameters which maximize the log-marginal likelihood. (Default: 500)
  'GPR_alpha': 1e-6                   # [float] Value added to the diagonal of the kernel matrix during fitting. This can prevent a potential numerical issue during fitting, by ensuring that the calculated values form a positive definite matrix. (Default: 1e-6)
  'EI_exploration-exploitation': 0.01 # [float] Exploration-exploitation parameter for Expected Improvement acquisition function. (Default: 0.01)

Memory Override Options

Option

Description

opt_mem_override

Allow new samples even if memory exceeds n_samples

Full Configuration File

Below is the complete default configuration file:

user_options.yaml
 1# =============================================================================
 2# BOAR Configuration File
 3# =============================================================================
 4
 5# -----------------------------------------------------------------------------
 6# General Options
 7# -----------------------------------------------------------------------------
 8general_options:
 9  'clear_start': True     # [bool] Re-create output directory on start
10  'silent': True          # [bool] Suppress log messages
11  'log_dev': False        # [bool] Print all logs including simulation logs
12
13# -----------------------------------------------------------------------------
14# BASEMENT Options
15# -----------------------------------------------------------------------------
16basement_options:
17  'cleanup': False        # [bool] Remove previous results before running
18  'backend': omp          # [str] Backend: seq, omp, cuda, cudaC, cudaO
19  'nthreads': -1          # [int] Number of cores (-1 = all available)
20
21# -----------------------------------------------------------------------------
22# Simulation Options
23# -----------------------------------------------------------------------------
24simulation_options:
25  'discharge_file': True               # [bool] Define the model setup discharge using a TXT file. (Default: False)
26  'discharge_file_directory': /path/to/discharge_files # [str] Directory containing discharge files. Only required if 'discharge_file' is True.
27  'discharge_file_list': ['Q001.txt', 'Q002.txt']  # [list] List of discharge files to use. Only required if 'discharge_file' is True.
28
29# -----------------------------------------------------------------------------
30# Optimization Options
31# -----------------------------------------------------------------------------
32optimization_variable_options:
33  'initial_vector': file              # [str] file, float, or list. (Default: file)
34  'regions': ['main_channel', 'floodplain']           # [list] Regions to optimize. (Default: all friction regions)
35  'constraints':                      # [dict] Parameter constraints. (Default: None)
36    'expression': "x > y or np.isclose(x, y)"
37    'variables': ['x', 'y']
38  'bounds': [!!python/tuple [10, 60]] # [list of tuples] Optimization bounds. (Default: None)
39  'precision': 1e-1                   # [float] Decimal precision. (Default: 1)
40  'save_errors': True                 # [bool] Save error points to CSV. (Default: False)
41  'save_tried_vectors': False         # [bool] Save all results files. (Default: False)
42  'opt_engine': "boar"                # [str] Optimization engine ("boar" or "optuna"). Default: "boar"
43
44# -----------------------------------------------------------------------------
45# Sampling Options
46# -----------------------------------------------------------------------------
47sampling_options:
48  'seed': 42                          # [int] Random seed (None = random)
49
50# -----------------------------------------------------------------------------
51# Surrogate Model Options
52# -----------------------------------------------------------------------------
53surrogate_model_options:
54  'tolerance': 1e-4                   # [float] Stop criterion
55  'test_population': 67956            # [int] Surrogate model samples
56  'opt_mem_override': False           # [bool] Override memory check. (Default: False)
57  'n_initial': 5                      # [int] Min samples before optimization. (Default: 5)
58  'max_tested_vectors': 100           # [int] Max vectors to try. (Default: 100)
59  'max_no_improvement': 10            # [int] Max iterations without progress (Default: 100)
60  'GPR_iterations': 500               # [int] The number of restarts of the optimizer for finding the kernel’s parameters which maximize the log-marginal likelihood. (Default: 500)
61  'GPR_alpha': 1e-6                   # [float] Value added to the diagonal of the kernel matrix during fitting. This can prevent a potential numerical issue during fitting, by ensuring that the calculated values form a positive definite matrix. (Default: 1e-6)
62  'EI_exploration-exploitation': 0.01 # [float] Exploration-exploitation parameter for Expected Improvement acquisition function. (Default: 0.01)