ParameterOptimization Configuration

The optimization.json file configures parameter optimization settings, including the optimization algorithm, target parameters, observational constraints, and cost calculation methods.

ParameterOptimization Algorithm

The algorithm_optimization field specifies the optimization scheme, which can be either:

• A direct algorithm name

• A path to a JSON file with detailed algorithm settings

"algorithm_optimization": "Path to algorithm configuration or algorithm name"

Algorithm Configuration File

The algorithm configuration file specifies detailed optimization settings:

{
    "method": "ParameterOptimization method name",
    "options": {
        "maxfevals": "Maximum function evaluations",
        "multi_threading": "Enable multi-threading support"
    },
    "package": "Source package for optimization"
}

Algorithm Selection

• The same method may be available through different packages

• Both method and package must be specified

• Options can be customized for each method/package combination

Available Methods To list all implemented optimization methods:

using Sindbad.ParameterOptimization
using OmniTools: show_methods_of
show_methods_of(ParameterOptimizationMethod)

ParameterOptimization Parameters

This section defines default parameter properties and lists parameters to optimize.

Default Parameter Settings

"model_parameter_default": {
    "distribution": ["Distribution type", "Distribution parameters"],
    "is_ml": "Flag for machine learning optimization"
}

Parameter List

"model_parameters_to_optimize": {
    "approach,parameter_name": "Override settings or null for defaults"
}

Parameter Naming

Parameters follow the convention: ${approach},${parameter_name}

ParameterOptimization Objective

This section configures observational constraints and cost combination methods.

{
    "multi_constraint_method": "Method to combine variable costs",
    "multi_objective_algorithm": "Flag for multi-objective optimization",
    "observational_constraints": ["List of variables for cost calculation"]
}

Available Methods

• Use show_methods_of(SpatialMetricAggr) for supported multi_constraint_method options

Observational Constraints

Default Cost Settings

"default_cost": {
    "aggr_func": "Spatial/temporal aggregation function",
    "aggr_obs": "Flag for observational data aggregation",
    "aggr_order": "Aggregation order (time_space or space_time)",
    "cost_metric": "Cost calculation method",
    "cost_weight": "Variable weight in cost calculation",
    "min_data_points": "Minimum valid data points required",
    "spatial_data_aggr": "Spatial data aggregation method",
    "spatial_cost_aggr": "Spatial cost aggregation method",
    "spatial_weight": "Enable area-based weighting",
    "temporal_data_aggr": "Temporal aggregation method (from TimeSamplers.jl)"
}

Temporal Aggregation

The temporal_data_aggr field uses temporal sampling methods from TimeSamplers.jl. Common values include:

• "day", "month", "year" for basic time aggregation

• See TimeSamplers.jl documentation for the complete list of available temporal sampling methods

== Example

"default_cost": {
    "aggr_func": "nanmean",
    "aggr_obs": false,
    "aggr_order": "time_space",
    "cost_metric": "NNSE_inv",
    "cost_weight": 1.0,
    "min_data_points": 1,
    "spatial_data_aggr": "concat_data",
    "spatial_cost_aggr": "metric_spatial",
    "spatial_weight": false,
    "temporal_data_aggr": "day"
}

:::

Data Quality Settings

{
    "use_quality_flag": "Apply data quality flags",
    "use_spatial_weight": "Apply spatial area weights",
    "use_uncertainty": "Consider data uncertainty"
}

Available Methods

• Use show_methods_of(PerfMetric) for cost metrics

• Use show_methods_of(SpatialMetricAggr) for spatial aggregation

• Use show_methods_of(TimeSampleMethod) for temporal methods

Default Observation Settings

"default_observation": {
    "additive_unit_conversion": "Additive (true) or multiplicative (false) unit conversion",
    "bounds": "Valid data range after conversion",
    "data_path": "Path to observation data file",
    "is_categorical": "Flag for categorical data",
    "standard_name": "Descriptive variable name",
    "sindbad_unit": "Unit used within SINDBAD",
    "source_product": "Data source identifier",
    "source_to_sindbad_unit": "Unit conversion factor",
    "source_unit": "Original data unit",
    "source_variable": "Variable name in source file",
    "space_time_type": "Data type classification"
}

Data Handling

• Values outside bounds are replaced with NaN/missing

• Unit conversions are applied during data processing

• Ensure data paths are accessible from the experiment environment