easy_vic_build.calibrate

Calibration workflows for VIC/RVIC based on NSGA-II search.

Public classes

NSGAII_VIC_SO

Single-objective calibration using KGE as fitness.

NSGAII_VIC_MO

Minimal multi-objective subclass placeholder.

Classes

NSGAII_VIC_MO(evb_dir, dpc_VIC_level0, ...)

Minimal multi-objective subclass placeholder.

NSGAII_VIC_SO(evb_dir, dpc_VIC_level0, ...)

Single-objective NSGA-II calibrator for VIC/RVIC workflows.
class easy_vic_build.calibrate.NSGAII_VIC_SO(evb_dir, dpc_VIC_level0, dpc_VIC_level1, dpc_VIC_level3, date_period, warmup_date_period, calibrate_date_period, verify_date_period, domain_dataset=None, snaped_outlet_lons=None, snaped_outlet_lats=None, snaped_outlet_names=None, buildParam_level0_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level0_interface'>, buildParam_level1_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level1_interface'>, soillayerresampler=<easy_vic_build.tools.params_func.TransferFunction.SoilLayerResampler object>, TF_VIC_class=<class 'easy_vic_build.tools.params_func.TransferFunction.TF_VIC'>, nlayer_list=[1, 2, 3], rvic_OUTPUT_INTERVAL=86400, rvic_BASIN_FLOWDAYS=50, rvic_SUBSET_DAYS=10, rvic_uhbox_dt=3600, algParams={'cxProb': 0.7, 'maxGen': 250, 'mutateProb': 0.2, 'popSize': 40}, save_path='checkpoint.pkl', reverse_lat=True, parallel=False)[source]

Bases: NSGAII_Base

Single-objective NSGA-II calibrator for VIC/RVIC workflows.

Initialize calibration state and algorithm settings.

Parameters:

  • evb_dir (Evb_dir) – Case directory manager and runtime paths.

  • dpc_VIC_level0 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level1 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level3 (object) – DPC instances used for parameter updates and observations.

  • date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • warmup_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • calibrate_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • verify_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • domain_dataset (netCDF4.Dataset, optional) – Domain dataset. If None, it is loaded from disk.

  • snaped_outlet_lons (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_lats (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_names (list, optional) – Optional outlet definitions for RVIC routing.

  • buildParam_level0_interface_class (type, optional) – Interface classes for parameter generation.

  • buildParam_level1_interface_class (type, optional) – Interface classes for parameter generation.

  • soillayerresampler (object, optional) – Soil-layer resampler for level-0 parameter build.

  • TF_VIC_class (type, optional) – Transfer-function class.

  • nlayer_list (list, optional) – Soil-layer indices used by scaling.

  • rvic_OUTPUT_INTERVAL (int, optional) – RVIC runtime/config defaults.

  • rvic_BASIN_FLOWDAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_SUBSET_DAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_uhbox_dt (int, optional) – RVIC runtime/config defaults.

  • algParams (dict, optional) – NSGA-II control parameters.

  • save_path (str, optional) – Checkpoint path used by NSGAII_Base.

  • reverse_lat (bool, optional) – Whether latitude axis is arranged north-to-south.

  • parallel (bool or int, optional) – VIC parallel execution flag/process count.

__init__(evb_dir, dpc_VIC_level0, dpc_VIC_level1, dpc_VIC_level3, date_period, warmup_date_period, calibrate_date_period, verify_date_period, domain_dataset=None, snaped_outlet_lons=None, snaped_outlet_lats=None, snaped_outlet_names=None, buildParam_level0_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level0_interface'>, buildParam_level1_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level1_interface'>, soillayerresampler=<easy_vic_build.tools.params_func.TransferFunction.SoilLayerResampler object>, TF_VIC_class=<class 'easy_vic_build.tools.params_func.TransferFunction.TF_VIC'>, nlayer_list=[1, 2, 3], rvic_OUTPUT_INTERVAL=86400, rvic_BASIN_FLOWDAYS=50, rvic_SUBSET_DAYS=10, rvic_uhbox_dt=3600, algParams={'cxProb': 0.7, 'maxGen': 250, 'mutateProb': 0.2, 'popSize': 40}, save_path='checkpoint.pkl', reverse_lat=True, parallel=False)[source]

Initialize calibration state and algorithm settings.

Parameters:

  • evb_dir (Evb_dir) – Case directory manager and runtime paths.

  • dpc_VIC_level0 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level1 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level3 (object) – DPC instances used for parameter updates and observations.

  • date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • warmup_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • calibrate_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • verify_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • domain_dataset (netCDF4.Dataset, optional) – Domain dataset. If None, it is loaded from disk.

  • snaped_outlet_lons (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_lats (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_names (list, optional) – Optional outlet definitions for RVIC routing.

  • buildParam_level0_interface_class (type, optional) – Interface classes for parameter generation.

  • buildParam_level1_interface_class (type, optional) – Interface classes for parameter generation.

  • soillayerresampler (object, optional) – Soil-layer resampler for level-0 parameter build.

  • TF_VIC_class (type, optional) – Transfer-function class.

  • nlayer_list (list, optional) – Soil-layer indices used by scaling.

  • rvic_OUTPUT_INTERVAL (int, optional) – RVIC runtime/config defaults.

  • rvic_BASIN_FLOWDAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_SUBSET_DAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_uhbox_dt (int, optional) – RVIC runtime/config defaults.

  • algParams (dict, optional) – NSGA-II control parameters.

  • save_path (str, optional) – Checkpoint path used by NSGAII_Base.

  • reverse_lat (bool, optional) – Whether latitude axis is arranged north-to-south.

  • parallel (bool or int, optional) – VIC parallel execution flag/process count.

set_GlobalParam_dict()[source]

Build and write the default VIC global-parameter configuration.

get_obs()[source]

Load observed streamflow and convert discharge to m3/s.

get_sim()[source]

Read simulated discharge at pour point and resample to daily mean.

createFitness()[source]

Register single-objective fitness in DEAP creator.

samplingInd()[source]

Sample one individual from parameter bounds via LHS.

run_vic()[source]

Execute VIC using the current global parameter file.

run_rvic(conv_cfg_file_dict)[source]

Run RVIC convolution with a loaded configuration dictionary.

adjust_vic_params_level0(g_params)[source]

Update or build level-0 parameters from a candidate vector.

adjust_vic_params_level1(params_dataset_level0)[source]

Update/build level-1 parameters and apply level-0 to level-1 scaling.

cal_constraint_destroy(params_dataset_level0)[source]

Check hard physical constraints on level-0 parameters.

adjust_rvic_params(guh_params, rvic_params)[source]

Rebuild RVIC routing parameters from candidate UH/routing values.

adjust_rvic_conv_params()[source]

Build RVIC convolution config and return it as a dictionary.

evaluate(ind)[source]

Evaluate one individual and return fitness tuple.

simulate(ind, GlobalParam_dict)[source]

Run full VIC+RVIC simulation for one individual.

simulate_vic(ind, GlobalParam_dict)[source]

Run VIC-only simulation for one individual.

simulate_rvic(ind, GlobalParam_dict)[source]

Prepare RVIC inputs for one individual (execution path is incomplete).

get_best_results()[source]

Run best individual and export calibration/verification time series.

static operatorMate(parent1, parent2, low, up)[source]

Defines the crossover operation for mating two individuals.

Parameters:

  • parent1 (Individual) – The first parent individual.

  • parent2 (Individual) – The second parent individual.

Returns:

A tuple containing the offspring resulting from the crossover.

Return type:

tuple

static operatorMutate(ind, low, up, NDim)[source]

Defines the mutation operation for an individual.

Parameters:

ind (Individual) – The individual to mutate.

Returns:

A tuple containing the mutated individual.

Return type:

tuple

static operatorSelect(population, popSize)[source]

Defines the selection operation for choosing individuals from the population.

Parameters:

population (list of Individual) – The population from which to select individuals.

Returns:

A list of selected individuals.

Return type:

list

apply_genetic_operators(offspring)[source]

Applies the genetic operators (crossover and mutation) to the offspring.

Parameters:

offspring (list of Individual) – The offspring to apply the genetic operators to.

createInd()

Creates an individual representation (a list).

evaluatePop(population)

Evaluates the fitness of the entire population.

Parameters:

population (list of Individual) – The population to evaluate.

load_state()

Loads the algorithm state from the specified save path if a saved state exists.

plot_front_pairwise(population, front, gen, names_plot=None, plot_dir='pareto_progress', transform_func=None)

Plot pairwise objective scatter for full population and first front.

Parameters:

  • population (list) – Population to visualize (typically parent + offspring).

  • front (list) – First non-dominated front.

  • gen (int) – Generation index used in figure title.

  • names_plot (list of str, optional) – Objective axis labels. If None, labels are generated as obj1, obj2, …

  • plot_dir (str, optional) – Directory used to store figure output.

  • transform_func (callable, optional) – Optional transformation applied to objective arrays before plotting.

print_results(population)

Prints the results of the best individual from the final population.

Parameters:

population (list of Individual) – The final population.

registerEvaluate()

Registers the evaluation function with the toolbox.

registerInd()

Registers the individual sampling function with the toolbox.

registerOperators()

Registers the genetic operators (mate, mutate, and select) with the toolbox.

registerPop()

Registers the population initialization function with the toolbox.

run(plot_progress=False, plot_dir='pareto_progress', names_plot=None, transform_func=None)

Runs the NSGA-II algorithm for the specified number of generations.

This method applies genetic operators, evaluates individuals, selects the next generation, and stores the results.

Parameters:

  • plot_progress (bool, optional) – Whether to save a pairwise Pareto plot each generation.

  • plot_dir (str, optional) – Output directory for progress plots.

  • names_plot (list of str, optional) – Objective labels passed to plot_front_pairwise().

  • transform_func (callable, optional) – Optional transform function passed to plot_front_pairwise().

Returns:

The final population after all generations.

Return type:

list

save_state()

Saves the current algorithm state (current generation, population, and history) to the specified save path.

select_next_generation(combined)

Selects the next generation from the combined population and offspring.

Parameters:

combined (list of Individual) – The combined population of parents and offspring.

Returns:

The selected next generation.

Return type:

list

set_algorithm_params(popSize=None, maxGen=None, cxProb=None, mutateProb=None, **kwargs)

Sets the parameters for the genetic algorithm.

Parameters:

  • popSize (int, optional) – The population size for each generation (default is 40).

  • maxGen (int, optional) – The maximum number of generations to run the algorithm (default is 250).

  • cxProb (float, optional) – The crossover probability (default is 0.7).

  • mutateProb (float, optional) – The mutation probability (default is 0.2).

class easy_vic_build.calibrate.NSGAII_VIC_MO(evb_dir, dpc_VIC_level0, dpc_VIC_level1, dpc_VIC_level3, date_period, warmup_date_period, calibrate_date_period, verify_date_period, domain_dataset=None, snaped_outlet_lons=None, snaped_outlet_lats=None, snaped_outlet_names=None, buildParam_level0_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level0_interface'>, buildParam_level1_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level1_interface'>, soillayerresampler=<easy_vic_build.tools.params_func.TransferFunction.SoilLayerResampler object>, TF_VIC_class=<class 'easy_vic_build.tools.params_func.TransferFunction.TF_VIC'>, nlayer_list=[1, 2, 3], rvic_OUTPUT_INTERVAL=86400, rvic_BASIN_FLOWDAYS=50, rvic_SUBSET_DAYS=10, rvic_uhbox_dt=3600, algParams={'cxProb': 0.7, 'maxGen': 250, 'mutateProb': 0.2, 'popSize': 40}, save_path='checkpoint.pkl', reverse_lat=True, parallel=False)[source]

Bases: NSGAII_VIC_SO

Minimal multi-objective subclass placeholder.

Initialize calibration state and algorithm settings.

Parameters:

  • evb_dir (Evb_dir) – Case directory manager and runtime paths.

  • dpc_VIC_level0 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level1 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level3 (object) – DPC instances used for parameter updates and observations.

  • date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • warmup_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • calibrate_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • verify_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • domain_dataset (netCDF4.Dataset, optional) – Domain dataset. If None, it is loaded from disk.

  • snaped_outlet_lons (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_lats (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_names (list, optional) – Optional outlet definitions for RVIC routing.

  • buildParam_level0_interface_class (type, optional) – Interface classes for parameter generation.

  • buildParam_level1_interface_class (type, optional) – Interface classes for parameter generation.

  • soillayerresampler (object, optional) – Soil-layer resampler for level-0 parameter build.

  • TF_VIC_class (type, optional) – Transfer-function class.

  • nlayer_list (list, optional) – Soil-layer indices used by scaling.

  • rvic_OUTPUT_INTERVAL (int, optional) – RVIC runtime/config defaults.

  • rvic_BASIN_FLOWDAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_SUBSET_DAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_uhbox_dt (int, optional) – RVIC runtime/config defaults.

  • algParams (dict, optional) – NSGA-II control parameters.

  • save_path (str, optional) – Checkpoint path used by NSGAII_Base.

  • reverse_lat (bool, optional) – Whether latitude axis is arranged north-to-south.

  • parallel (bool or int, optional) – VIC parallel execution flag/process count.

createFitness()[source]

Register single-objective fitness in DEAP creator.

samplingInd()[source]

Sample one individual from parameter bounds via LHS.

evaluate(ind)[source]

Evaluate one individual and return fitness tuple.

evaluatePop(population)[source]

Evaluates the fitness of the entire population.

Parameters:

population (list of Individual) – The population to evaluate.

operatorMate()[source]

Defines the crossover operation for mating two individuals.

Parameters:

  • parent1 (Individual) – The first parent individual.

  • parent2 (Individual) – The second parent individual.

Returns:

A tuple containing the offspring resulting from the crossover.

Return type:

tuple

__init__(evb_dir, dpc_VIC_level0, dpc_VIC_level1, dpc_VIC_level3, date_period, warmup_date_period, calibrate_date_period, verify_date_period, domain_dataset=None, snaped_outlet_lons=None, snaped_outlet_lats=None, snaped_outlet_names=None, buildParam_level0_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level0_interface'>, buildParam_level1_interface_class=<class 'easy_vic_build.tools.params_func.build_Param_interface.buildParam_level1_interface'>, soillayerresampler=<easy_vic_build.tools.params_func.TransferFunction.SoilLayerResampler object>, TF_VIC_class=<class 'easy_vic_build.tools.params_func.TransferFunction.TF_VIC'>, nlayer_list=[1, 2, 3], rvic_OUTPUT_INTERVAL=86400, rvic_BASIN_FLOWDAYS=50, rvic_SUBSET_DAYS=10, rvic_uhbox_dt=3600, algParams={'cxProb': 0.7, 'maxGen': 250, 'mutateProb': 0.2, 'popSize': 40}, save_path='checkpoint.pkl', reverse_lat=True, parallel=False)

Initialize calibration state and algorithm settings.

Parameters:

  • evb_dir (Evb_dir) – Case directory manager and runtime paths.

  • dpc_VIC_level0 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level1 (object) – DPC instances used for parameter updates and observations.

  • dpc_VIC_level3 (object) – DPC instances used for parameter updates and observations.

  • date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • warmup_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • calibrate_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • verify_date_period (list) – Simulation and evaluation date windows (YYYYMMDD strings).

  • domain_dataset (netCDF4.Dataset, optional) – Domain dataset. If None, it is loaded from disk.

  • snaped_outlet_lons (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_lats (list, optional) – Optional outlet definitions for RVIC routing.

  • snaped_outlet_names (list, optional) – Optional outlet definitions for RVIC routing.

  • buildParam_level0_interface_class (type, optional) – Interface classes for parameter generation.

  • buildParam_level1_interface_class (type, optional) – Interface classes for parameter generation.

  • soillayerresampler (object, optional) – Soil-layer resampler for level-0 parameter build.

  • TF_VIC_class (type, optional) – Transfer-function class.

  • nlayer_list (list, optional) – Soil-layer indices used by scaling.

  • rvic_OUTPUT_INTERVAL (int, optional) – RVIC runtime/config defaults.

  • rvic_BASIN_FLOWDAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_SUBSET_DAYS (int, optional) – RVIC runtime/config defaults.

  • rvic_uhbox_dt (int, optional) – RVIC runtime/config defaults.

  • algParams (dict, optional) – NSGA-II control parameters.

  • save_path (str, optional) – Checkpoint path used by NSGAII_Base.

  • reverse_lat (bool, optional) – Whether latitude axis is arranged north-to-south.

  • parallel (bool or int, optional) – VIC parallel execution flag/process count.

adjust_rvic_conv_params()

Build RVIC convolution config and return it as a dictionary.

adjust_rvic_params(guh_params, rvic_params)

Rebuild RVIC routing parameters from candidate UH/routing values.

adjust_vic_params_level0(g_params)

Update or build level-0 parameters from a candidate vector.

adjust_vic_params_level1(params_dataset_level0)

Update/build level-1 parameters and apply level-0 to level-1 scaling.

apply_genetic_operators(offspring)

Applies the genetic operators (crossover and mutation) to the offspring.

Parameters:

offspring (list of Individual) – The offspring to apply the genetic operators to.

cal_constraint_destroy(params_dataset_level0)

Check hard physical constraints on level-0 parameters.

createInd()

Creates an individual representation (a list).

get_best_results()

Run best individual and export calibration/verification time series.

get_obs()

Load observed streamflow and convert discharge to m3/s.

get_sim()

Read simulated discharge at pour point and resample to daily mean.

load_state()

Loads the algorithm state from the specified save path if a saved state exists.

operatorMutate()[source]

Defines the mutation operation for an individual.

Parameters:

ind (Individual) – The individual to mutate.

Returns:

A tuple containing the mutated individual.

Return type:

tuple

plot_front_pairwise(population, front, gen, names_plot=None, plot_dir='pareto_progress', transform_func=None)

Plot pairwise objective scatter for full population and first front.

Parameters:

  • population (list) – Population to visualize (typically parent + offspring).

  • front (list) – First non-dominated front.

  • gen (int) – Generation index used in figure title.

  • names_plot (list of str, optional) – Objective axis labels. If None, labels are generated as obj1, obj2, …

  • plot_dir (str, optional) – Directory used to store figure output.

  • transform_func (callable, optional) – Optional transformation applied to objective arrays before plotting.

print_results(population)

Prints the results of the best individual from the final population.

Parameters:

population (list of Individual) – The final population.

registerEvaluate()

Registers the evaluation function with the toolbox.

registerInd()

Registers the individual sampling function with the toolbox.

registerOperators()

Registers the genetic operators (mate, mutate, and select) with the toolbox.

registerPop()

Registers the population initialization function with the toolbox.

run(plot_progress=False, plot_dir='pareto_progress', names_plot=None, transform_func=None)

Runs the NSGA-II algorithm for the specified number of generations.

This method applies genetic operators, evaluates individuals, selects the next generation, and stores the results.

Parameters:

  • plot_progress (bool, optional) – Whether to save a pairwise Pareto plot each generation.

  • plot_dir (str, optional) – Output directory for progress plots.

  • names_plot (list of str, optional) – Objective labels passed to plot_front_pairwise().

  • transform_func (callable, optional) – Optional transform function passed to plot_front_pairwise().

Returns:

The final population after all generations.

Return type:

list

run_rvic(conv_cfg_file_dict)

Run RVIC convolution with a loaded configuration dictionary.

run_vic()

Execute VIC using the current global parameter file.

save_state()

Saves the current algorithm state (current generation, population, and history) to the specified save path.

select_next_generation(combined)

Selects the next generation from the combined population and offspring.

Parameters:

combined (list of Individual) – The combined population of parents and offspring.

Returns:

The selected next generation.

Return type:

list

set_GlobalParam_dict()

Build and write the default VIC global-parameter configuration.

set_algorithm_params(popSize=None, maxGen=None, cxProb=None, mutateProb=None, **kwargs)

Sets the parameters for the genetic algorithm.

Parameters:

  • popSize (int, optional) – The population size for each generation (default is 40).

  • maxGen (int, optional) – The maximum number of generations to run the algorithm (default is 250).

  • cxProb (float, optional) – The crossover probability (default is 0.7).

  • mutateProb (float, optional) – The mutation probability (default is 0.2).

simulate(ind, GlobalParam_dict)

Run full VIC+RVIC simulation for one individual.

simulate_rvic(ind, GlobalParam_dict)

Prepare RVIC inputs for one individual (execution path is incomplete).

simulate_vic(ind, GlobalParam_dict)

Run VIC-only simulation for one individual.

operatorSelect()[source]

Defines the selection operation for choosing individuals from the population.

Parameters:

population (list of Individual) – The population from which to select individuals.

Returns:

A list of selected individuals.

Return type:

list