changed some variable names inside run_dynamic_mu_star_calibration to…

… make it more consistent with names of run_dynamic_spinup

oggm/core/dynamic_spinup.py

@@ -891,10 +891,11 @@ def define_new_mu_star_in_gdir(gdir, new_mu_star, bias=0):
 def dynamic_mu_star_run_with_dynamic_spinup(
         gdir, mu_star, yr0_ref_mb, yr1_ref_mb, fls_init, ys, ye,
         output_filesuffix='', evolution_model=FluxBasedModel,
+        mb_model_historical=None, mb_model_spinup=None,
         minimise_for='area', climate_input_filesuffix='', spinup_period=20,
-        min_spinup_period=10, yr_rgi=None, precision_percent_dyn_spinup=1,
-        precision_absolute_dyn_spinup=1, min_ice_thickness=None,
-        first_guess_t_bias=-2, t_bias_max_step_length=2, maxiter_dyn_spinup=30,
+        min_spinup_period=10, yr_rgi=None, precision_percent=1,
+        precision_absolute=1, min_ice_thickness=None,
+        first_guess_t_bias=-2, t_bias_max_step_length=2, maxiter=30,
         store_model_geometry=True, store_fl_diagnostics=None,
         local_variables=None, set_local_variables=False, do_inversion=True,
         **kwargs):
@@ -933,6 +934,15 @@ def dynamic_mu_star_run_with_dynamic_spinup(
     evolution_model : class:oggm.core.FlowlineModel
         Evolution model to use.
         Default is FluxBasedModel
+    mb_model_historical : :py:class:`core.MassBalanceModel`
+        User-povided MassBalanceModel instance for the historical run. Default
+        is to use a PastMassBalance model  together with the provided
+        parameter climate_input_filesuffix.
+    mb_model_spinup : :py:class:`core.MassBalanceModel`
+        User-povided MassBalanceModel instance for the spinup before the
+        historical run. Default is to use a ConstantMassBalance model together
+        with the provided parameter climate_input_filesuffix and during the
+        period of spinup_start_yr until rgi_year (e.g. 1979 - 2000).
     minimise_for : str
         The variable we want to match at yr_rgi. Options are 'area' or 'volume'.
         Default is 'area'.
@@ -956,18 +966,18 @@ def dynamic_mu_star_run_with_dynamic_spinup(
         The rgi date, at which we want to match area or volume.
         If None, gdir.rgi_date + 1 is used (the default).
         Default is None
-    precision_percent_dyn_spinup : float
+    precision_percent : float
         Gives the precision we want to match for the selected variable
         ('minimise_for') at rgi_date in percent. The algorithm makes sure that
         the resulting relative mismatch is smaller than precision_percent, but
         also that the absolute value is smaller than precision_absolute.
         Default is 1, meaning the difference must be within 1% of the given
         value (area or volume).
-    precision_absolute_dyn_spinup : float
+    precision_absolute : float
         Gives an minimum absolute value to match. The algorithm makes sure that
         the resulting relative mismatch is smaller than
-        precision_percent_dyn_spinup, but also that the absolute value is
-        smaller than precision_absolute_dyn_spinup.
+        precision_percent, but also that the absolute value is
+        smaller than precision_absolute.
         The unit of precision_absolute depends on minimise_for (if 'area' in
         km2, if 'volume' in km3)
         Default is 1.
@@ -987,7 +997,7 @@ def dynamic_mu_star_run_with_dynamic_spinup(
         Defines the maximums allowed change of t_bias between two iteratons. Is
         needed to avoid to large changes.
         Default is 2
-    maxiter_dyn_spinup : int
+    maxiter : int
         Maximum number of minimisation iterations per dynamic spinup where area
         or volume is tried to be matched. If reached and 'ignore_errors=False'
         an error is raised.
@@ -1051,18 +1061,7 @@ def dynamic_mu_star_run_with_dynamic_spinup(
         spinup_period = yr_rgi - ys
         min_ice_thickness = 0
 
-    # Here we start with the actual model run
-    if mu_star == gdir.read_json('local_mustar')['mu_star_glacierwide']:
-        # we do not need to define a new mu_star or do an inversion
-        do_inversion = False
-    else:
-        define_new_mu_star_in_gdir(gdir, mu_star)
-
-    # this variable is used if an inverison is conducted to keep the original
-    # model_flowline unchanged (-> to be able to conduct different dynamic
-    # calibration runs in the same gdir)
-    model_flowline_filesuffix = ''
-
+    # check that inversion is only possible without providing own fls
     if do_inversion:
         if not np.all([np.all(getattr(fl_prov, 'surface_h') ==
                               getattr(fl_orig, 'surface_h')) and
@@ -1076,15 +1075,26 @@ def dynamic_mu_star_run_with_dynamic_spinup(
                                        'provide your own flowlines! (fls_init '
                                        'should be None or '
                                        'the original model_flowlines)')
+
+    # Here we start with the actual model run
+    if mu_star == gdir.read_json('local_mustar')['mu_star_glacierwide']:
+        # we do not need to define a new mu_star or do an inversion
+        do_inversion = False
+    else:
+        define_new_mu_star_in_gdir(gdir, mu_star)
+
+    if do_inversion:
         apparent_mb_from_any_mb(gdir)
         # do inversion with A calibration to current volume
         calibrate_inversion_from_consensus(
             [gdir], apply_fs_on_mismatch=True, error_on_mismatch=False,
             filter_inversion_output=True,
             volume_m3_reference=local_variables['vol_m3_ref'])
-        # And finally initialise the new model flowlines
-        model_flowline_filesuffix = '_dyn_mu_calib'
-        init_present_time_glacier(gdir, filesuffix=model_flowline_filesuffix)
+
+    # this is used to keep the original model_flowline unchanged (-> to be able
+    # to conduct different dynamic calibration runs in the same gdir)
+    model_flowline_filesuffix = '_dyn_mu_calib'
+    init_present_time_glacier(gdir, filesuffix=model_flowline_filesuffix)
 
     # Now do a dynamic spinup to match area
     # do not ignore errors in dynamic spinup, so all 'bad' files are
@@ -1095,15 +1105,18 @@ def dynamic_mu_star_run_with_dynamic_spinup(
             continue_on_error=False,  # force to raise an error in @entity_task
             init_model_fls=fls_init,
             climate_input_filesuffix=climate_input_filesuffix,
-            evolution_model=evolution_model, spinup_period=spinup_period,
+            evolution_model=evolution_model,
+            mb_model_historical=mb_model_historical,
+            mb_model_spinup=mb_model_spinup,
+            spinup_period=spinup_period,
             spinup_start_yr=ys,
             spinup_start_yr_max=yr0_ref_mb,
             min_spinup_period=min_spinup_period, yr_rgi=yr_rgi,
-            precision_percent=precision_percent_dyn_spinup,
-            precision_absolute=precision_absolute_dyn_spinup,
+            precision_percent=precision_percent,
+            precision_absolute=precision_absolute,
             min_ice_thickness=min_ice_thickness,
             t_bias_max_step_length=t_bias_max_step_length,
-            maxiter=maxiter_dyn_spinup,
+            maxiter=maxiter,
             minimise_for=minimise_for,
             first_guess_t_bias=local_variables['t_bias'][-1],
             output_filesuffix=output_filesuffix,
@@ -1137,10 +1150,11 @@ def dynamic_mu_star_run_with_dynamic_spinup(
 def dynamic_mu_star_run_with_dynamic_spinup_fallback(
         gdir, mu_star, fls_init, ys, ye, local_variables, output_filesuffix='',
         evolution_model=FluxBasedModel, minimise_for='area',
+        mb_model_historical=None, mb_model_spinup=None,
         climate_input_filesuffix='', spinup_period=20, min_spinup_period=10,
-        yr_rgi=None, precision_percent_dyn_spinup=1,
-        precision_absolute_dyn_spinup=1, min_ice_thickness=10,
-        first_guess_t_bias=-2, t_bias_max_step_length=2, maxiter_dyn_spinup=30,
+        yr_rgi=None, precision_percent=1,
+        precision_absolute=1, min_ice_thickness=10,
+        first_guess_t_bias=-2, t_bias_max_step_length=2, maxiter=30,
         store_model_geometry=True, store_fl_diagnostics=None,
         do_inversion=True, **kwargs):
     """
@@ -1172,6 +1186,15 @@ def dynamic_mu_star_run_with_dynamic_spinup_fallback(
     evolution_model : class:oggm.core.FlowlineModel
         Evolution model to use.
         Default is FluxBasedModel
+    mb_model_historical : :py:class:`core.MassBalanceModel`
+        User-povided MassBalanceModel instance for the historical run. Default
+        is to use a PastMassBalance model  together with the provided
+        parameter climate_input_filesuffix.
+    mb_model_spinup : :py:class:`core.MassBalanceModel`
+        User-povided MassBalanceModel instance for the spinup before the
+        historical run. Default is to use a ConstantMassBalance model together
+        with the provided parameter climate_input_filesuffix and during the
+        period of spinup_start_yr until rgi_year (e.g. 1979 - 2000).
     minimise_for : str
         The variable we want to match at yr_rgi. Options are 'area' or 'volume'.
         Default is 'area'.
@@ -1195,18 +1218,18 @@ def dynamic_mu_star_run_with_dynamic_spinup_fallback(
         The rgi date, at which we want to match area or volume.
         If None, gdir.rgi_date + 1 is used (the default).
         Default is None
-    precision_percent_dyn_spinup : float
+    precision_percent : float
         Gives the precision we want to match for the selected variable
         ('minimise_for') at rgi_date in percent. The algorithm makes sure that
         the resulting relative mismatch is smaller than precision_percent, but
         also that the absolute value is smaller than precision_absolute.
         Default is 1, meaning the difference must be within 1% of the given
         value (area or volume).
-    precision_absolute_dyn_spinup : float
+    precision_absolute : float
         Gives an minimum absolute value to match. The algorithm makes sure that
         the resulting relative mismatch is smaller than
-        precision_percent_dyn_spinup, but also that the absolute value is
-        smaller than precision_absolute_dyn_spinup.
+        precision_percent, but also that the absolute value is
+        smaller than precision_absolute.
         The unit of precision_absolute depends on minimise_for (if 'area' in
         km2, if 'volume' in km3)
         Default is 1.
@@ -1226,7 +1249,7 @@ def dynamic_mu_star_run_with_dynamic_spinup_fallback(
         Defines the maximums allowed change of t_bias between two iteratons. Is
         needed to avoid to large changes.
         Default is 2
-    maxiter_dyn_spinup : int
+    maxiter : int
         Maximum number of minimisation iterations per dynamic spinup where area
         or volume is tried to be matched. If reached and 'ignore_errors=False'
         an error is raised.
@@ -1289,17 +1312,19 @@ def dynamic_mu_star_run_with_dynamic_spinup_fallback(
             init_model_fls=fls_init,
             climate_input_filesuffix=climate_input_filesuffix,
             evolution_model=evolution_model,
+            mb_model_historical=mb_model_historical,
+            mb_model_spinup=mb_model_spinup,
             spinup_period=spinup_period,
             spinup_start_yr=ys,
             min_spinup_period=min_spinup_period,
             yr_rgi=yr_rgi,
             minimise_for=minimise_for,
-            precision_percent=precision_percent_dyn_spinup,
-            precision_absolute=precision_absolute_dyn_spinup,
+            precision_percent=precision_percent,
+            precision_absolute=precision_absolute,
             min_ice_thickness=min_ice_thickness,
             first_guess_t_bias=first_guess_t_bias,
             t_bias_max_step_length=t_bias_max_step_length,
-            maxiter=maxiter_dyn_spinup,
+            maxiter=maxiter,
             output_filesuffix=output_filesuffix,
             store_model_geometry=store_model_geometry,
             store_fl_diagnostics=store_fl_diagnostics,
@@ -1501,7 +1526,7 @@ def dynamic_mu_star_run_fallback(
 def run_dynamic_mu_star_calibration(
         gdir, ref_dmdtda=None, err_ref_dmdtda=None,
         ref_period='', ignore_hydro_months=False, min_mu_star=None,
-        max_mu_star=None, mu_star_max_step_length=5, maxiter_mu_star=20,
+        max_mu_star=None, mu_star_max_step_length=5, maxiter=20,
         ignore_errors=False, output_filesuffix='_dynamic_mu_star',
         ys=None, ye=None,
         run_function=dynamic_mu_star_run_with_dynamic_spinup,
@@ -1556,7 +1581,7 @@ def run_dynamic_mu_star_calibration(
         Defines the maximum allowed change of mu_star between two iteratons.
         Is needed to avoid to large changes.
         Default is 5
-    maxiter_mu_star : int
+    maxiter : int
         Maximum number of minimisation iterations of minimising mismatch to
         dmdtda by changing mu_star. Each of this iterations conduct a complete
         run defined in the 'run_function'. If maxiter_mu_star reached and
@@ -2021,7 +2046,7 @@ def get_mismatch(mu_star):
             return mismatch[-1], new_mu_star
 
         # Now start with splin fit for guessing
-        while len(mu_star_guess) < maxiter_mu_star:
+        while len(mu_star_guess) < maxiter:
             # get next guess from splin (fit partial linear function to
             # previously calculated (mismatch, mu_star) pairs and get mu_star
             # value where mismatch=0 from this fitted curve)
@@ -2055,7 +2080,7 @@ def get_mismatch(mu_star):
         raise RuntimeError(f'Could not find mismatch smaller '
                            f'{err_ref_dmdtda} kg m-2 yr-1 (only '
                            f'{np.min(np.abs(mismatch))} kg m-2 yr-1) in '
-                           f'{maxiter_mu_star} Iterations!')
+                           f'{maxiter} Iterations!')
 
     # wrapper to get values for intermediate (mismatch, mu_star) guesses if an
     # error is raised