oggm.tasks.run_dynamic_melt_f_calibration

oggm.tasks.run_dynamic_melt_f_calibration(gdir, settings_filesuffix='', observations_filesuffix='', overwrite_observations=False, ref_mb=None, ref_mb_err=None, ref_mb_err_scaling_factor=1, ref_mb_period=None, melt_f_min=None, melt_f_max=None, melt_f_max_step_length_minimum=0.1, maxiter=20, ignore_errors=False, output_filesuffix=None, model_flowlines_filesuffix=None, mb_model_class=None, save_mb_diagnostics_filesuffix=None, ys=None, ye=None, target_yr=None, run_function=<function dynamic_melt_f_run_with_dynamic_spinup>, kwargs_run_function=None, fallback_function=<function dynamic_melt_f_run_with_dynamic_spinup_fallback>, kwargs_fallback_function=None, init_model_filesuffix=None, init_model_yr=None, init_model_fls=None, first_guess_diagnostic_msg='dynamic spinup only')

Calibrate melt_f to match a geodetic mass balance incorporating a dynamic model run.

This task iteratively search for a melt_f to match a provided geodetic mass balance. How one model run looks like is defined in the ‘run_function’. This function should take a new melt_f guess, conducts a dynamic run and calculate the geodetic mass balance. The goal is to match the geodetic mass blanance ‘ref_mb’ inside the provided error ‘ref_mb_err’ (by default the values from Hugonnet are used). If the minimisation of the mismatch between the provided and modeled geodetic mass balance is not working the ‘fallback_function’ is called. In there it is decided what run should be conducted in such a failing case. Further if ‘ignore_error’ is set to True and we could not find a satisfying mismatch the best run so far is saved (if not one successful run with ‘run_function’ the ‘fallback_function’ is called).

Parameters:

gdiroggm.GlacierDirectory

the glacier directory to process

settings_filesuffix: str

You can use a different set of settings by providing a filesuffix. This is useful for sensitivity experiments. Code-wise the settings_filesuffix is set in the @entity-task decorater.

observations_filesuffix: str

The observations filesuffix, from where the reference calibration data ‘ref_mb’ should be used. Code-wise the observations_filesuffix is set in the @entity-task decorater.

overwrite_observationsbool

If you want to overwrite already existing observation values in the provided observations file set this to True. Default is False.

ref_mbfloat or None

The reference geodetic mass balance to match (units: kg m-2 yr-1). If None the data from the observation file is used. Default is None

ref_mb_errfloat or None

The error of the reference geodetic mass balance to match (unit: kg m-2 yr-1). Must always be a positive number. If None the data from the observation file is used. Default is None

ref_mb_err_scaling_factorfloat

The error of the geodetic mass balance is multiplied by this factor. When looking at more glaciers you should set this factor smaller than 1 (Default), but the smaller this factor the more glaciers will fail during calibration. The idea is that we reduce the uncertainty of individual observations to count for correlated uncertainties when looking at regional or global scales. If err_scaling_factor is 1 (Default) and you look at the results of more than one glacier this equals that all errors are uncorrelated. Therefore the result will be outside the uncertainty boundaries given in Hugonett 2021 e.g. for the global estimate, because some correlation of the individual errors is assumed during aggregation of glaciers to regions (for more details see paper Hugonett 2021).

ref_mb_periodstr or None

The valid period of ref_mb in the format ‘2000-01-01_2020-01-01’. If None the data from the observation file is used. Default is None.

melt_f_minfloat or None

Lower absolute limit for melt_f. Default is None (-> gdir.settings[‘melt_f_min’])

melt_f_maxfloat or None

Upper absolute limit for melt_f. Default is None (-> gdir.settings[‘melt_f_max’])

melt_f_max_step_length_minimumfloat

Defines a minimum maximal change of melt_f between two iterations. The maximum step length is needed to avoid too large steps, which likely lead to an error. Default is 0.1

maxiterint

Maximum number of minimisation iterations of minimising mismatch to dmdtda by changing melt_f. Each of this iterations conduct a complete run defined in the ‘run_function’. If maxiter reached and ‘ignore_errors=False’ an error is raised. Default is 20

ignore_errorsbool

If True and the ‘run_function’ with melt_f calibration is not working to match dmdtda inside the provided uncertainty fully, but their where some successful runs which improved the first guess, they are saved as part success, and if not a single run was successful the ‘fallback_function’ is called. If False and the ‘run_function’ with melt_f calibration is not working fully an error is raised. Default is True

output_filesuffixstr

For the output file. If None the settings_filesuffix will be used. Default is None

model_flowlines_filesuffixstr

for the model flowline to use if no other flowlines for initialisation are provided. If None the settings_filesuffix will be used. Default is None

mb_model_classMassBalanceModel, default MonthlyTIModel

The MassBalanceModel class to use.

save_mb_diagnostics_filesuffixstr, optional

if provided, the mass balance model state is saved to mb_diagnostics{save_mb_diagnostics_filesuffix}.nc after the run completes, via MultipleFlowlineMassBalance.save_to_file(). Useful for saving a historical run before branching into multiple projection scenarios.

ysint or None

The start year of the conducted run. If None the first year of the provided climate file. Default is None

yeint or None

The end year of the conducted run. If None the last year of the provided climate file. Default is None

target_yrint or None

The target year for a potential dynamic spinup (see run_dynamic_spinup function for more info). If None, gdir.rgi_date + 1 is used (the default). Default is None

run_functionfunction

This function defines how a new defined melt_f is used to conduct the next model run. This function must contain the arguments ‘gdir’, ‘settings_filesuffix’, ‘melt_f’, ‘yr0_ref_mb’, ‘yr1_ref_mb’, ‘fls_init’, ‘ys’, ‘ye’ and ‘output_filesuffix’. Further this function must return the final model and the calculated geodetic mass balance dmdtda in kg m-2 yr-1.

kwargs_run_functionNone or dict

Can provide additional keyword arguments to the run_function as a dictionary.

fallback_functionfunction

This is a fallback function if the calibration is not working using ‘run_function’ it is called. This function must contain the arguments ‘gdir’, ‘settings_filesuffix’, ‘melt_f’, ‘fls_init’, ‘ys’, ‘ye’, and ‘output_filesuffix’. Further this function should return the final model.

kwargs_fallback_functionNone or dict

Can provide additional keyword arguments to the fallback_function as a dictionary.

init_model_filesuffixstr or None

If you want to start from a previous model run state. This state should be at time yr_rgi_date. Default is None

init_model_yrint or None

the year of the initial run you want to start from. The default is to take the last year of the simulation.

init_model_fls[]

List of flowlines to use to initialise the model (the default is the present_time_glacier file from the glacier directory). Ignored if init_model_filesuffix is set.

first_guess_diagnostic_msgstr

This message will be added to the glacier diagnostics if only the default melt_f resulted in a successful ‘run_function’ run. Default is ‘dynamic spinup only’

Returns:

oggm.core.flowline.evolution_model

The final dynamically spined-up model. Type depends on the selected evolution_model.

Notes

Files written to the glacier directory:

inversion_flowlines.pkl

A “better” version of the centerlines, now on a regular spacing i.e., not on the gridded (i, j) indices. The tails of the tributaries are cut out to make more realistic junctions. They are now “1.5D” i.e., with a width.