Optimization#

Getting Started#

Install requirements:

Note

Make sure to install Ax inside your fetch-dev environment

Todo

Future version will move all optimization requirements to the fetch3 environment file for easier installation

Prepare optimizaion configuration file#

See optimization_config_template.yml for an example of the optimization configuration file.

The optimization configuration file is similar to the FETCH3 configuration file.

To prepare this file:

  1. Update the optimization_options section:

    • obsfile: path to the data file containing sapflux observations

    • obsvar: column header for the variable of interest in the observations file

    • model_dir: path to the fetch3 repository

    • data_path: path to the input data directory for the model

    • output_dir: directory where the optimization output will be written

    • output_fname: Don’t change. Name of model output file

    • experiment_name: Name to label this optimization experiment with

    • objective_name: Don’t change for now - future version will have more options. Objective function to use for optimization.

    • ntrials: number of trials to run in the optimization

  2. Prepare the model_options section. This is identical to the model options section in the FETCH3 config file.

  3. Prepare the parameters section. The parameters listed in this section are identical to those in the FETCH3 config file, but here you must specify additional information. For each parameter, you must specify:

    • type: fixed or range. Fixed parameters will not be optimized. Range parameters will be optimized.

    • value or bounds: For fixed parameters, you must specify the value of the parameter. For range parameters, you must specify bounds for the optimization.

Todo

Will be updated soon:

  • cleaner options for specifying files and directories

  • additional options for objective functions

Running an optimization#

To run an optimization, cd into the fetch3_nhl directory, then run:

python -m boa --config-path /path/to/your/config/file

Outputs will be saved in a folder inside the working_dir you specified under optimization_options or script_options , labeled with the experiment name and timestamp of the optimization run.

Note

Replace the paths and filenames in this example with the actual paths and files you are using.

See optimization_results.ipynb for an example of how to explore the optimization results.

You can also resume an interrupted optimization run with:

python -m boa --scheduler-path /path/to/scheduler.json

the scheduler.json is outputted every couple trials during the optimization to ensure the ability to resume an interrupted optimization.

Updating boa#

To update to the latest version of boa, from your fetch3 conda environment run:

pip install -U git+https://github.com/madeline-scyphers/boa.git