PyGEM-Community · btobers · May 28, 2025 · May 5, 2025 · May 5, 2025 · May 5, 2025
diff --git a/.github/workflows/test_suite.yml b/.github/workflows/test_suite.yml
@@ -57,11 +57,14 @@ jobs:
 
       - name: 'Clone the PyGEM-notebooks repo'
         run: |
-          # Use PyGEM-notebook:main for master branch and PyGEM-notebooks:dev otherwise
           BRANCH=${GITHUB_REF#refs/heads/}
-          git clone --depth 1 --branch $([[ "$BRANCH" == "master" ]] && echo "main" || echo "dev") \
-            https://github.com/pygem-community/PyGEM-notebooks.git
-          echo "PYGEM_NOTEBOOKS_DIRPATH=$(pwd)/PyGEM-notebooks" >> $GITHUB_ENV
+          if [ "$BRANCH" = "master" ]; then
+            NOTEBOOK_BRANCH="main"
+          else
+            NOTEBOOK_BRANCH="dev"
+          fi
+          git clone --depth 1 --branch "$NOTEBOOK_BRANCH" https://github.com/pygem-community/PyGEM-notebooks.git
+          echo "PYGEM_NOTEBOOKS_DIRPATH=$(pwd)/PyGEM-notebooks" >> "$GITHUB_ENV"
 
       - name: 'Run tests'
         run: |

diff --git a/README.md b/README.md
@@ -27,6 +27,8 @@ To support model testing and demonstration, a suite of Jupyter notebooks can be
     <td style="width: 50%;"><b>Citation</b></td>
     <td style="width: 50%;">
       <a href="https://www.science.org/doi/10.1126/science.abo1324"><img src="https://img.shields.io/badge/citation-Rounce%20et%20al.%20(2023;%20Science)-orange.svg"></a>
+      &nbsp;
+      <a href="https://doi.org/10.5281/zenodo.15045308"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.15045308.svg" alt="DOI"></a>
     </td>
   </tr>
   <tr>

diff --git a/docs/conf.py b/docs/conf.py
@@ -56,11 +56,11 @@
 
 
 html_theme = 'sphinx_book_theme'
-html_static_path = ['_static']
 
 html_theme_options = {
     'repository_url': 'https://github.com/PyGEM-Community/PyGEM',
     'use_repository_button': True,
-    'show_nav_level': 2,
-    'navigation_depth': 3,
+    'show_nav_level': 1,
+    'navigation_depth': 4,
+    'toc_title': 'On this page',
 }
diff --git a/docs/configuration.md b/docs/configuration.md
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -12,7 +12,7 @@ Next, clone PyGEM. This will place the code at your current directory, so you ma
 ```
 git clone https://github.com/PyGEM-Community/PyGEM.git
 ```
-If you opted to create your own fork, clone using appropriate repo URL: `git clone https://github.com/YOUR-USERNAME/PyGEM.git`
+If you opted to create your own fork, clone using appropriate repo URL: `git clone https://github.com/<YOUR-USERNAME>/PyGEM.git`
 
 Navigate to root project directory:
 ```

diff --git a/docs/index.rst b/docs/index.rst
@@ -48,17 +48,22 @@ with respect to modeling glacier dynamics and ice thickness inversions.
    :caption: Getting Started:
 
    install_pygem
-   test_pygem
+   configuration
    scripts_overview
+   test_pygem
    model_output
 
 .. toctree::
    :maxdepth: 1
    :caption: Contributing:
 
    contributing
-   citing
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Citing:
+
+   citing
 .. Indices and tables
 .. ==================
 

diff --git a/docs/install_pygem.md b/docs/install_pygem.md
@@ -1,6 +1,8 @@
 (install_pygem_target)=
 # Installation
-The Python Glacier Evolution Model has been packaged using Poetry and is hosted on the Python Package Index ([PyPI](https://pypi.org/project/pygem/)), to ensure that all dependencies install seamlessly. It is recommended that users create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html) environment from which to install the model dependencies and core code. If you do not yet have conda installed, see [conda's documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install) for instructions.
+PyGEM has been tested successfully on Linux and macOS systems. For Windows users (Windows 10/11), we recommend installing the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl) (WSL), and then installing and running PyGEM from there.
+
+PyGEM has been packaged using [Poetry](https://python-poetry.org/) and is hosted on the Python Package Index ([PyPI](https://pypi.org/project/pygem/)), to ensure that all dependencies install seamlessly. It is recommended that users create a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/index.html) environment from which to install the model dependencies and core code. If you do not yet have conda installed, see [conda's documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install) for instructions.
 
 Next, choose your preferred PyGEM installation option:<br>
 - [**stable**](stable_install_target): this is the latest version that has been officially released to PyPI, with a fixed version number (e.g. v1.0.1). It is intended for general use.

diff --git a/docs/mb_ablation.md b/docs/mb_ablation.md
@@ -3,20 +3,20 @@ There are currently two model options for ablation. Both model options use a deg
 
 ### Option 1: monthly temperatures
 The first calculates ablation ($a$) using the mean monthly temperature:
-$$a=f_{snow/ice/firn/debris} \cdot T_{m}^{+} \cdot n$$
+$a=f_{snow/ice/firn/debris} \cdot T_{m}^{+} \cdot n$
 
-where $f$ is the degree-day factor of snow, ice, firn, or debris (m w.e. d-1 °C$^{-1}$), $T_{m}^{+}$ is the positive monthly mean temperature (°C), and $n$ is the number of days per month. 
+where $f$ is the degree-day factor of snow, ice, firn, or debris (m w.e. d$^{-1}$ °C$^{-1}$), $T_{m}^{+}$ is the positive monthly mean temperature (°C), and $n$ is the number of days per month. 
 
 ### Option 2: monthly temperatures with daily variance
 The second option incorporates the daily variance associated with the temperature for each month according to [Huss and Hock (2015)](https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full):
-$$a=f_{snow/ice/firn/debris} \cdot \sum_{i=1}^{ndays} T_{d,i}^{+} $$
+$a=f_{snow/ice/firn/debris} \cdot \sum_{i=1}^{ndays} T_{d,i}^{+} $
 
 where $T_{d}$ is the daily positive mean air temperature and is estimated by superimposing random variability from the standard deviation of the daily temperature for each month.
 
 The degree-day factors for snow, ice, firn, and debris depend on the surface type option that is chosen by the user (see Section 5). The values of $f$ for these various surface types are assumed to be related to one another to reduce the number of model parameters. The default ratio of the $f_{snow}$ to the $f_{ice}$ is 0.7, and $f_{firn}$ is assumed to be the mean of the $f_{snow}$ and $f_{ice}$; however, the user may change these values in the input file if desired. The values for $f_{debris}$ are equal to $f_{ice}$ multiplied by the mean sub-debris melt enhancement factor [(Rounce et al. 2021)](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2020GL091311) for the given elevation bin.
 
 ### Temperature at elevation bins
 Temperature for each elevation bin ($T_{bin}$) is determined by selecting the temperature from the gridded climate data ($T_{gcm}$) based on the nearest neighbor, which is then downscaled to the elevation bins on the glacier according to:
-$$T_{bin} = T_{gcm} + lr_{gcm} \cdot (z_{ref} - z_{gcm}) + lr_{glac} \cdot (z_{bin} - z_{ref}) + T_{bias}$$
+$T_{bin} = T_{gcm} + lr_{gcm} \cdot (z_{ref} - z_{gcm}) + lr_{glac} \cdot (z_{bin} - z_{ref}) + T_{bias}$
 
 where $lr_{gcm}$ and $lr_{glac}$ are lapse rates (°C m-1) associated with downscaling the climate data to the glacier and then over the glacier elevation bins, respectively; $z_{ref}$, $z_{gcm}$, and $z_{bin}$ are the elevations from the glacier’s reference point (median or mean elevation), the climate data, and the elevation bin, respectively; and $T_{bias}$ is the temperature bias. The temperature bias is one of three model parameters that is calibrated and serves to account for any biases resulting from the use of coarse climate data that is unable to capture local topographic variations. By default, the $lr_{gcm}$ and $lr_{glac}$ are assumed to be equal.
diff --git a/docs/mb_accumulation.md b/docs/mb_accumulation.md
@@ -3,7 +3,7 @@ Accumulation ($c$) is calculated for each elevation bin as a function of the pre
 
 ### Option 1: Threshold +/- 1$^{\circ}$C
 The first (default) option is to estimate the ratio of liquid and solid precipitation based on the air temperature:
-$$c = \delta \cdot P_{bin}$$
+$c = \delta \cdot P_{bin}$
 
 where $\delta=1$; if $T_{bin} \leq T_{snow}-1$
 
@@ -18,9 +18,9 @@ The alternative option is to classify precipitation as snow or rain based on a s
 
 ### Precipitation at elevation bins
 Precipitation at each elevation bin of the glacier ($P_{bin}$) is determined by selecting the precipitation from the gridded climate data ($P_{gcm}$) based on the nearest neighbor, which is then downscaled to the elevation bins on the glacier:
-$$P_{bin} = P_{GCM} \cdot k_{p} \cdot (1 + d_{prec} \cdot (z_{bin} - z_{ref}))$$
+$P_{bin} = P_{GCM} \cdot k_{p} \cdot (1 + d_{prec} \cdot (z_{bin} - z_{ref}))$
 <br>where $k_{p}$ is the precipitation factor and $d_{prec}$ is the precipitation gradient. The precipitation factor is a model parameter that is used to adjust from the climate data to the glacier, which could be caused by local topographic effects due to differences in elevation, rain shadow effects, etc. The precipitation gradient is another model parameter, which is used to redistribute the precipitation along the glacier and can be thought of as a precipitation lapse rate. Typical values for the precipitation gradient vary from 0.01 – 0.025% m$^{-1}$([Huss and Hock, 2015](https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full) who cited [WGMS, 2012](https://wgms.ch/products_fog/)). The default assumes a precipitation gradient of 0.01% m$^{-1}$ to reduce the number of model parameters.
 
 Additionally, for glaciers with high relief (> 1000 m), the precipitation in the uppermost 25% of the glacier’s elevation is reduced using an exponential function ([Huss and Hock, 2015](https://www.frontiersin.org/articles/10.3389/feart.2015.00054/full)):
-$$P_{bin,exp} = P_{bin} \cdot exp(\frac{z_{bin} - z_{75\%}}{z_{max} - z_{75\%}}) $$
+$P_{bin,exp} = P_{bin} \cdot exp(\frac{z_{bin} - z_{75\%}}{z_{max} - z_{75\%}}) $
 where $P_{bin,exp}$ is the adjusted precipitation, and $z_{max}$ and $z_{75\%}$ are the elevation of the glacier maximum and the glacier’s 75th percentile elevation, respectively. The adjusted precipitation cannot be lower than 87.5% of the maximum precipitation on the glacier. This adjustment accounts for the reduced air moisture and increased wind erosion at higher elevations ([Benn and Lehmkuhl, 2000](https://risweb.st-andrews.ac.uk/portal/en/researchoutput/mass-balance-and-equilibriumline-altitudes-of-glaciers-in-highmountain-environments(080f17fc-33dd-4805-bc97-a5aaa018a457)/export.html)).
diff --git a/docs/mb_refreezing.md b/docs/mb_refreezing.md
@@ -3,7 +3,7 @@ There are two model options for computing refreezing.  The default option estima
 
 ### Option 1: Mean annual air temperature
 For the default option, refreezing (R) is calculated for each elevation bin as a function of its weighted annual mean air temperature (Ta) following [Woodward et al. (1997)](https://www.cambridge.org/core/journals/annals-of-glaciology/article/influence-of-superimposedice-formation-on-the-sensitivity-of-glacier-mass-balance-to-climate-change/84DFA08E9CC8F28BE0729F1EBF4DA4E1)):
-$$R = -0.0069 \cdot T_{a} + 0.000096$$
+$R = -0.0069 \cdot T_{a} + 0.000096$
 The weighted annual mean accounts for the number of days in each month. Refreezing cannot be negative. The model assumes that refreezing occurs in the snowpack as opposed to being superimposed ice, so in the ablation zone the refreezing cannot exceed the snow depth. Since this option estimates annual refreezing, the equation above provides the maximum amount of potential refreezing. Each year, the potential refreezing is reset in October as this is the transition season from predominantly summer melt to winter accumulation. Therefore, it is possible that accumulated snow may melt and refreeze diurnally. The model replicates this physical behavior by first determining the amount of snow that has melted in that month. If the refreezing potential is greater than zero, the model assumes the snow melts and refreezes in the snow pack. Refreezing cannot exceed the amount of snow melt in any given month. The amount of refreezing is then subtracted from the potential refreezing until the potential refreezing is fully depleted or reset. Once the snow and refreezing completely melts, the model can melt the underlying ice/firn/snow.  This model is used as the default because it is computationally cheap compared to the alternative.
 
 ### Option 2: Heat conduction

diff --git a/docs/model_output.md b/docs/model_output.md
@@ -1,6 +1,8 @@
 (model_output_overview_target)=
 # Model Output 
-The model outputs a variety of data including monthly mass balance and its components (accumulation, melt, refreezing, frontal ablation, glacier runoff), and annual mass, mass below sea level, and area. Results are written as a netcdf file (.nc) for each glacier. If multiple simulations are performed (e.g., for Monte Carlo simulations), then statistics related to the median and median absolute deviation are output for each parameter. In addition to this standard glacier-wide output, binned output is also available, which include the bins surface elevation, volume, thickness, and climatic mass balance annually.
+The model outputs a variety of data including monthly mass balance and its components (accumulation, melt, refreezing, frontal ablation, glacier runoff), and annual mass, mass below sea level, and area. Results are written as a netcdf file (.nc) for each glacier. If multiple simulations are performed (e.g., for Monte Carlo simulations), then statistics related to the median and median absolute deviation are output for each parameter. 
+
+In addition to this standard glacier-wide output, binned outputs are also available (by setting `sim["out"]["export_binned_data"]` to `true` in the [PyGEM configuration file](contributing_pygem_target)), which include each bins initial surface elevation, annual area, annual mass, annual thickness, annual climatic mass balance, and monthly climatic mass balance. Monthly climatic mass balance components can also be stored by setting `sim["out"]["export_binned_components"]` to `true`.
 
 ## Post-processing Data
 PyGEM simulations are output for each glacier individually. For most analyses, it is useful to aggregate or merge analyses to a regional or global scale. PyGEM's *postproc.compile_simulations.py* is designed to do just so.

diff --git a/docs/model_structure.md b/docs/model_structure.md
@@ -15,7 +15,7 @@ Currently, the model does not have a “required” set of directories. The rela
 
 ~/pygem_data/<br>
 ├ [DEMs](input_mb_data_target): geodetic mass balance data derived from DEM differencing that is used for calibration.<br>
-├ [IceThickness_Farinotti](input_thickness_data_target): consensus ice thickness estimates (Farinotti et al. 2019). The directory is optional unless you want to match the consensus ice thickness estimates<br>
+├ [IceThickness_Farinotti](input_thickness_data_target): reference ice thickness estimates (Farinotti et al. 2019). The directory is optional unless you want to match the reference ice thickness estimates<br>
 ├ [oggm_gdirs](input_glacier_data_target): glacier directories downloaded from OGGM. This directory will be automatically generated by the pre-processing steps from OGGM.<br>
 ├ Output: model output data<br>
 ├ [RGI](input_glacier_inventory_target): Randolph Glacier Inventory information<br>
@@ -33,7 +33,7 @@ The model code itself is heavily commented with the hope that the code is easy t
 * [Pre-process data](preprocessing_target) <em>(optional if including more data)</em>
 * [Set up configuration file](config_workflow_target)
 * [Calibrate frontal ablation parameter](workflow_cal_frontalablation_target) <em>(optional for marine-terimating glaciers)</em>
-* [Calibrate mass balance parameters](workflow_cal_prms_target)
+* [Calibrate climatic mass balance parameters](workflow_cal_prms_target)
 * [Calibrate ice viscosity parameter](workflow_cal_glena_target)
 * [Run model simulation](workflow_sim_target)
 * [Post-process output](workflow_post_target)
@@ -57,7 +57,7 @@ The only critical component of the configuration file which must be set prior to
 For more details, see the [configuration file overview](pygem_config_overview_target).
 
 ```{note}
-The first time you process glacier directories (e.g., happens automatically with the run_calibration.py), you want to set <em>overwrite_gdirs=True</em> in *~/PyGEM/config.yaml*. This will add the mass balance and consensus ice thickness data to the glacier directories.  To avoid redownloading/reprocessing the glacier directories every time, after performed once set <em>overwrite_gdirs=False</em>.
+The first time you process glacier directories (e.g., happens automatically with the run_calibration.py), you want to set <em>overwrite_gdirs=True</em> in *~/PyGEM/config.yaml*. This will add the mass balance and reference ice thickness data to the glacier directories.  To avoid redownloading/reprocessing the glacier directories every time, after performed once set <em>overwrite_gdirs=False</em>.
 ```
 
 (workflow_cal_prms_target)=
@@ -94,7 +94,7 @@ Circularity issues exist in calibrating the frontal ablation parameter as the ma
 
 (workflow_cal_glena_target)=
 ### Calibrate ice viscosity model parameter
-The ice viscosity ("Glen A") model parameter is calibrated such that the ice volume estimated using the calibrated mass balance gradients are consistent with the consensus ice volume estimates ([Farinotti et al. (2019)](https://www.nature.com/articles/s41561-019-0300-3)) for each RGI region. This is done by running the following:
+The ice viscosity ("Glen A") model parameter is calibrated such that the ice volume estimated using the calibrated mass balance gradients are consistent with the reference ice volume estimates ([Farinotti et al. (2019)](https://www.nature.com/articles/s41561-019-0300-3)) for each RGI region. This is done by running the following:
 ```
 run_calibration_reg_glena
 ```

diff --git a/docs/publications.md b/docs/publications.md
@@ -1,5 +1,10 @@
 (publications_target)=
-# Select Publications
+# Publications
+## Publications describing PyGEM
 * Rounce, D.R., Hock, R., Maussion, F., Hugonnet, R., Kochtitzky, W., Huss, M., Berthier, E., Brinkerhoff, D., Compagno, L., Copland, L., Farinotti, D., Menounos, B., and McNabb, R.W. (2023). “[Global glacier change in the 21st century: Every increase in temperature matters](https://www.science.org/doi/10.1126/science.abo1324)”, Science, 379(6627), pp. 78-83, doi:10.1126/science.abo1324
 * Rounce, D.R., Hock, R., and Shean, D.E. (2020). “[Glacier mass change in High Mountain Asia through 2100 using the open-source Python Glacier Evolution Model (PyGEM)](https://www.frontiersin.org/articles/10.3389/feart.2019.00331/full)”, Frontiers in Earth Science, 7(331), pp. 1-20, doi:10.3389/feart.2019.00331
-* Rounce, D.R., Khurana, T., Short, M.B., Hock, R., Shean, D.E., and Brinkherhoff, D.J. (2020). “[Quantifying parameter uncertainty in a large-scale glacier evolution model using Bayesian inference – Application to High Mountain Asia](https://www.cambridge.org/core/journals/journal-of-glaciology/article/quantifying-parameter-uncertainty-in-a-largescale-glacier-evolution-model-using-bayesian-inference-application-to-high-mountain-asia/61D8956E9A6C27CC1A5AEBFCDADC0432)”, Journal of Glaciology, 66(256), pp. 175-187, doi:10.1017/jog.2019.91
+* Rounce, D.R., Khurana, T., Short, M.B., Hock, R., Shean, D.E., and Brinkherhoff, D.J. (2020). “[Quantifying parameter uncertainty in a large-scale glacier evolution model using Bayesian inference – Application to High Mountain Asia](https://www.cambridge.org/core/journals/journal-of-glaciology/article/quantifying-parameter-uncertainty-in-a-largescale-glacier-evolution-model-using-bayesian-inference-application-to-high-mountain-asia/61D8956E9A6C27CC1A5AEBFCDADC0432)”, Journal of Glaciology, 66(256), pp. 175-187, doi:10.1017/jog.2019.91
+
+## Publications using PyGEM
+* Yang, R, Hock, R., Rounce, D., Kang, S. (2024). "[Regional-scale response of glacier speed to seasonal runoff variations on the Kenai Peninsula, Alaska.](https://doi.org/10.1029/2025GL115248)", Geophysical Research Letters. 52, e2025GL115248, doi:10.1029/2025GL115248.
+* Kochtitzky W., Copland, L., Van Wychen, W., Hock, R., Rounce, D.R., Jiskoot, H., Scambos, T.A., Morlighem, M., King, M., Cha, L., Gould, L., Merrill,P-M., Glazovsky, A., Hugonnet, R., Strozzi, T., Noël, B., Navarro, F., Millan, R., Dowdeswell, J.A., Cook, A., Dalton, A., Khan, S., Jania, J. (2023). "[Progress towards globally complete frontal ablation estimates of marine-terminating glaciers](https://doi.org/10.1017/aog.2023.35)". Annals of Glaciology. doi:10.1017/aog.2023.35.