Merged PICO split into dev

.mailmap

@@ -21,3 +21,11 @@ Julien Seguinot <julien.seguinot@natgeo.su.se>      <seguinot@vaw.baug.ethz.ch>
 Matthias Mengel <mengel@pik-potsdam.de>             <mengel@login01.(none)>
 Ronja Reese <reese@pik-potsdam.de>
 Torsten Albrecht <albrecht@pik-potsdam.de>          <torsten.albrecht@pik-potsdam.de>
+Enrico Degregori <degregori@dkrz.de>                Enrico <k202136@dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin100.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin101.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin102.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin103.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin104.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin105.hpc.dkrz.de>
+Enrico Degregori <degregori@dkrz.de>                k202136 <k202136@mlogin108.hpc.dkrz.de>

CHANGES.rst

@@ -48,6 +48,17 @@ Changes since v1.2
 - Adjust PICO ocean input average across covered basins, in which the ice shelf has 
   in fact a connection to the ocean. Large ice shelves, that cover across two basins, 
   that do not share an ocean boundary, are split into two separate ice shelf instances 
+- Implement scaling of calving rates using a time-dependent factor. Set
+  `calving.rate_scaling.file` to the name of the file containing `frac_calving_rate`
+  (units: "1").
+- Add the new command-line option `-refinement_factor N`. Use this to select a regional
+  modeling domain using `-x_range ... -y_range ...`, with use a grid that is `N` times
+  finer.
+- Fix a bug in the code managing time step restrictions (this affected the last time step
+  of runs using `-skip` and runs with `-skip` in which `-max_dt` is active).
+- Adjust PICO ocean input average across covered basins, in which the ice shelf has
+  in fact a connection to the ocean. Large ice shelves, that cover across two basins,
+  that do not share an ocean boundary, are split into two separate ice shelf instances
   with individual ocean inputs.
 
 Changes from v1.1 to v1.2

CMakeLists.txt

@@ -29,6 +29,11 @@ if (CMAKE_CXX_COMPILER_ID MATCHES "Intel" AND NOT CMAKE_CXX_FLAGS MATCHES "-std=
   set (CMAKE_CXX_FLAGS "-std=c++11 ${CMAKE_CXX_FLAGS}" CACHE STRING "C++ compiler flags" FORCE)
 endif()
 
+# Add a flag that makes it easier to use LLDB to debug code compiled with Clang:
+if (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-fstandalone-debug)
+endif()
+
 include ("CMake/PISM_CMake_macros.cmake")
 list (APPEND CMAKE_MODULE_PATH "${Pism_SOURCE_DIR}/CMake")
 

doc/Makefile

@@ -1,3 +1,3 @@
 update_funding:
-	python ./acknowledge.py > ../ACKNOWLEDGE.rst
-	python ./acknowledge.py --manual > sphinx/funding.txt
+	python3 ./acknowledge.py > ../ACKNOWLEDGE.rst
+	python3 ./acknowledge.py --manual > sphinx/funding.txt

doc/acknowledge.py

@@ -26,8 +26,8 @@
 To cite PISM please use at least one of Bueler and Brown (2009) or Winkelmann et al.
 (2011), below, as appropriate to the application.
 
-If your results came from source code modifications to PISM then we request that your
-publication say so explicitly.
+Do not forget to specify the PISM *version* you use. If your results came from source code
+modifications to PISM then we request that your publication say so explicitly.
 
 If your study relies heavily on certain PISM sub-models (such as hydrology, calving,
 fracture mechanics, thermodynamics) please contact the corresponding author/developer for

doc/ice-bib.bib

@@ -1,3 +1,13 @@
+@TechReport{Salinger2002,
+  author    = {Andrew G Salinger and Nawaf M Bou-rabee and Elizabeth A Burroughs and Roger P Pawlowski and Richard B Lehoucq and Louis Romero and Edward D Wilkes},
+  title     = {{LOCA} 1.0 Library of Continuation Algorithms: Theory and Implementation Manual},
+  year      = {2002},
+  month     = {mar},
+  doi       = {10.2172/800778},
+  publisher = {Office of Scientific and Technical Information ({OSTI})},
+  institution = {Office of Scientific and Technical Information ({OSTI})}
+}
+
 @Article{Eisenstat1996,
   author    = {Stanley C. Eisenstat and Homer F. Walker},
   journal   = {{SIAM} Journal on Scientific Computing},
@@ -5149,9 +5159,9 @@ @InProceedings{petsc-efficient
 @TechReport{petsc-user-ref,
     Author     = "S. Balay and others",
    Title       = "{PETS}c {U}sers {M}anual",
-   Number      = "ANL-95/11 - Revision 3.5",
+   Number      = "ANL-95/11 - Revision 3.15",
    Institution = "Argonne National Laboratory",
-   Year        = "2014",
+   Year        = "2021",
 }
 
 

doc/pismpython/inverse/design.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 =====================
 Inverse Code Overview
 =====================

doc/pismpython/inverse/index.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 =====================
 PISM Inverse Problems
 =====================

doc/pismpython/inverse/pism_ssa.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 .. _PISM_SSA:
 
 PISM's SSA Model

doc/pismpython/inverse/pismi.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 .. _pismi:
 
 ``pismi.py``

doc/pismpython/inverse/refresher.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 .. _inverse-background:
 
 ============================

doc/pismpython/inverse/ssa_forward.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 .. _SSAForward:
 
 SSA Forward Problems

doc/pismpython/inverse/ssa_inverse.rst

@@ -1,5 +1,3 @@
-.. include:: ../math-definitions.txt
-
 .. _SSAInverse:
 
 SSA Inverse Problems

doc/sphinx/CMakeLists.txt

@@ -46,13 +46,14 @@ if (SPHINX_EXECUTABLE AND PDFLATEX_COMPILER)
   find_program (MAKE_EXECUTABLE NAMES make gmake)
 
   add_custom_command (OUTPUT pism_manual.pdf
-    COMMAND ${SPHINX_EXECUTABLE} -E -b latex -t latex -D pism_config_file=${CMAKE_CURRENT_BINARY_DIR}/pism_config.nc ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
+    COMMAND ${SPHINX_EXECUTABLE} -T -W -E -b latex -t latex -D pism_config_file=${CMAKE_CURRENT_BINARY_DIR}/pism_config.nc ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
     COMMAND ${MAKE_EXECUTABLE} -C ${CMAKE_CURRENT_BINARY_DIR} all
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
 
   add_custom_target(manual_pdf ALL
+    DEPENDS pism_config.nc
     DEPENDS pism_manual.pdf
-    DEPENDS pism_config.nc)
+    )
 
   if (Pism_DOC_DIR)
     install (FILES ${CMAKE_CURRENT_BINARY_DIR}/pism_manual.pdf

doc/sphinx/Makefile

@@ -65,13 +65,13 @@ diag.json: dummy.nc surface_input.nc
 # entries from diag-2.json will override ones in diag.json (in other words, the order
 # matters here)
 update_diagnostics: diag.json diag-2.json
-	python ./list_diagnostics.py $^ > manual/diagnostics/diagnostics-list.txt
+	python3 ./list_diagnostics.py $^ > manual/diagnostics/diagnostics-list.txt
 
 pism_config.nc: ../../src/pism_config.cdl
 	ncgen -o $@ $^
 
 installation/code/install_libraries.sh: installation/debian-packages.csv Makefile
-	/bin/echo -n "sudo apt-get install -y " > $@
+	/bin/echo -n "apt-get install -y " > $@
 	cut -f1 -d, $< | sed "s/\`//g" | xargs >> $@
 
 clean:

doc/sphinx/climate_forcing/atmosphere.rst

@@ -395,11 +395,11 @@ followed by post-processing:
 .. note::
 
    - Discontinuities in the surface gradient (e.g. at ice margins) may cause oscillations
-     in the computed precipitation field probably due to the Gibbs phenomenon. To address
+     in the computed precipitation field (probably due to the Gibbs phenomenon). To address
      this our implementation includes the ability to smooth the surface topography using a
      Gaussian filter. Set
      :config:`atmosphere.orographic_precipitation.smoothing_standard_deviation` to a
-     positive number to enable smoothing. Values around `\Delta x` appear to be effective.
+     positive number to enable smoothing. Values around `\dx` appear to be effective.
 
    - The spectral method used to implement this model requires that the input (i.e.
      surface elevation `h`) is periodic in `x` and `y`. To simulate periodic `h` the

doc/sphinx/climate_forcing/surface.rst

@@ -95,8 +95,6 @@ Elevation-dependent temperature and mass balance
 :|variables|: none
 :|implementation|: ``pism::surface::Elevation``
 
-.. include:: ../math-definitions.txt
-
 This surface model component parameterizes the ice surface temperature `T_{h}` =
 :var:`ice_surface_temp` and the mass balance `m` = :var:`climatic_mass_balance` as
 *piecewise-linear* functions of surface elevation `h`.
@@ -288,6 +286,13 @@ individual components:
 
    SMB = surface_accumulation_flux - surface_runoff_flux
 
+.. rubric:: Parameters
+
+Prefix: ``surface.pdd.``.
+
+.. pism-parameters::
+   :prefix: surface.pdd.
+
 .. _sec-surface-pik:
 
 PIK
@@ -377,24 +382,12 @@ Two methods of adjusting the SMB are available:
 
   To use this method, set :opt:`-smb_adjustment shift`.
 
-It uses the following options.
-
-- :opt:`-temp_lapse_rate` gives the temperature lapse rate, in `K/km`. Note that we
-  use the following definition of the temperature lapse rate:
-- :opt:`-smb_adjustment` chooses SMB lapse rate (``shift``) or SMB scaling (``scale``).
-- :opt:`-smb_exp_factor` specifies the exponential factor used to scale the SMB
-- :opt:`-smb_lapse_rate` gives the surface mass balance lapse rate, in `m/year/km`.
-  Here, `\gamma_M=-\frac{dM}{dz}`.
-- :opt:`-surface_elevation_change_file` specifies the file containing the reference surface
-  elevation field (standard name: :var:`surface_altitude`). This file can contain several
-  surface elevation records to use lapse rate corrections relative to time-dependent
-  surface. If one record is provided, the reference surface elevation is assumed to be
-  time-independent.
-- :opt:`-surface_elevation_change_period` gives the period, in model years, to use when
-  interpreting data in the file given with ``-surface_given_file``,
-- :opt:`-surface_elevation_change_reference_year` takes the time `T` in model years. The
-  record for `t` years in ``-surface_given_file`` is interpreted as corresponding to
-  `t` years since `T`.
+.. rubric:: Parameters
+
+Prefix: ``surface.elevation_change.``.
+
+.. pism-parameters::
+   :prefix: surface.elevation_change.
 
 .. _sec-surface-forcing:
 

doc/sphinx/climate_forcing/testing.rst

@@ -27,7 +27,7 @@ options as in an actual modeling run. Note that :opt:`-test_climate_models` does
 disable geometry updates, so one can check if surface elevation feedbacks modeled using
 lapse rates (and similar) work correctly. Please use the :opt:`-no_mass` command-line
 option to fix ice geometry. (This may be necessary if the mass balance rate data would
-result in extreme ice sheet growth that is not balanced by ice flow in this setup.
+result in extreme ice sheet growth that is not balanced by ice flow in this setup.)
 
 As an example, set up an ice sheet state file and check if climate data is read in
 correctly:
@@ -47,7 +47,7 @@ same values as from ``state.nc``, in variables :var:`climatic_mass_balance`,
 :var:`ice_surface_temp`, reported back to us as the time- and space-dependent climate at
 times ``ys:dt:ye``. It is a boring "movie."
 
-A more interesting example uses a :ref:`positive degree-day scheme <sec-surface-pdd>`).
+A more interesting example uses a :ref:`positive degree-day scheme <sec-surface-pdd>`.
 This scheme uses a variable called :var:`precipitation`, and a calculation of melting, to
 get the surface mass balance :var:`climatic_mass_balance`.
 

doc/sphinx/conf.py

@@ -11,6 +11,7 @@
 # extension.
 import os
 import sys
+import re
 
 sys.path.append(os.path.abspath("."))
 
@@ -147,3 +148,23 @@ def git(command):
     'releasename': "version",
     'preamble': r'\usepackage{txfonts}'
 }
+
+mathjax_config = {"TeX": {"Macros": {}}}
+
+# Add math definitions to the LaTeX preamble and MathJax settings:
+for line in open("math-definitions.tex"):
+    M = re.match(r"\\newcommand{\\([a-zA-Z]+)}(\[([0-9]+)\])?(\[(.+)\])?{(.+)}", line)
+
+    if M:
+        name = M.group(1)
+        definition = M.group(6)
+        if M.group(2):
+            args = M.group(3)
+            if M.group(4):
+                default = M.group(5)
+                mathjax_config["TeX"]["Macros"][name] = [definition, args, default]
+            else:
+                mathjax_config["TeX"]["Macros"][name] = [definition, args]
+        else:
+            mathjax_config["TeX"]["Macros"][name] = definition
+        latex_elements["preamble"] += line

doc/sphinx/contributing/development-workflow.rst

@@ -117,6 +117,16 @@ To further speed up re-compiling PISM, install ccache_ and configure PISM as fol
 
    CC="ccache mpicc" CXX="ccache mpicxx" cmake ...
 
+It may be helpful to use LLD_ to link PISM during development since it is a lot faster
+than GNU ld. Add the following CMake_ options to give this a try.
+
+.. code-block:: bash
+
+   -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" \
+   -DCMAKE_SHARED_LINKER_FLAGS="-fuse-ld=lld" \
+   -DCMAKE_MODULE_LINKER_FLAGS="-fuse-ld=lld"
+
+
 .. _sec-debugging-pism:
 
 Debugging
@@ -213,9 +223,12 @@ of tests.
 It is often helpful to be able to run the same tests locally. To do this, install Docker_
 and `CircleCI CLI`_ (command-line interface), then run
 
-.. code-block:: none
+.. code-block:: bash
 
-   circleci local execute
+   circleci local execute --job={job}
+   # where job is one of
+   # build-gcc build-clang
+   # build-clang-minimal build-gcc-minimal build-manual
 
 in PISM's source code directory.
 
@@ -250,6 +263,9 @@ Here are some test writing tips:
   - Repeat the test twice, once using a refinement path along `x` and the second time
     along `y`; make sure that you see the same convergence rate.
 - It is good to check if the implementation preserves symmetries if the setup has any.
+- If a test uses a temporary file, make sure that it will not clash with names of files
+  used by other tests. One easy way to do this is by generating a unique file name using
+  ``mktemp`` (in Bash scripts) or ``str(uuid.uuid4())`` (in Python).
 
 Python bindings make it possible to test many PISM's components in isolation from the rest
 of the code. See tests in `test/regression` for some examples.
@@ -259,6 +275,18 @@ of the code. See tests in `test/regression` for some examples.
    This manual should cover PISM's Python bindings. If you see this, please e-mail
    |pism-email| and remind us to document them.
 
+Running tests
+~~~~~~~~~~~~~
+
+Run ``make test`` in parallel by adding
+
+.. code-block:: bash
+
+   export CTEST_PARALLEL_LEVEL=N
+
+to your ``.bashrc``. This will tell ``ctest`` to run ``N`` at the same time. Or run
+``ctest -j N`` instead of ``make test``.
+
 .. _sec-editing-the-manual:
 
 Editing PISM's manual

doc/sphinx/global.txt

@@ -109,6 +109,7 @@
 .. _Emacs: https://www.gnu.org/software/emacs/
 .. _GDB: https://www.gnu.org/software/gdb/
 .. _LLDB: https://lldb.llvm.org/
+.. _LLD: https://lld.llvm.org/
 .. _Valgrind: http://www.valgrind.org/
 .. _ccache: https://ccache.dev/
 

doc/sphinx/installation/code/install_libraries.sh

@@ -1 +1 @@
-sudo apt-get install -y cmake g++ git libfftw3-dev libgsl-dev libnetcdf-dev libudunits2-dev netcdf-bin petsc-dev cdo cmake-curses-gui libpnetcdf-dev libproj-dev libx11-dev nco ncview python3-dev python3-netcdf4 python3-nose python3-numpy python3-petsc4py python3-pyproj python3-scipy swig
+apt-get install -y cmake g++ git libfftw3-dev libgsl-dev libnetcdf-dev libudunits2-dev netcdf-bin petsc-dev cdo cmake-curses-gui libpnetcdf-dev libproj-dev libx11-dev nco ncview python3-dev python3-netcdf4 python3-nose python3-numpy python3-petsc4py python3-pyproj python3-scipy swig

doc/sphinx/installation/code/petsc-mkl-mumps-hypre.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# Install the latest PETSc with Intel MKL, MUMPS and hypre in ~/local/petsc using
+# ~/local/build/petsc as the build directory.
+
+prefix=$HOME/local/petsc
+build_dir=~/local/build/petsc
+
+rm -rf ${build_dir}
+mkdir -p ${build_dir}
+pushd ${build_dir}
+
+git clone -b release --depth=1 https://gitlab.com/petsc/petsc.git .
+
+PETSC_DIR=$PWD
+PETSC_ARCH="linux-opt"
+
+source $HOME/intel/oneapi/setvars.sh
+
+set -e
+set -u
+set -x
+
+./configure \
+  COPTFLAGS='-O3 -march=native -mtune=native' \
+  CXXOPTFLAGS='-O3 -march=native -mtune=native' \
+  FOPTFLAGS='-O3 -march=native -mtune=native' \
+  --prefix=${prefix} \
+  --with-blas-lapack-dir=$MKLROOT \
+  --with-cc=mpicc \
+  --with-cxx=mpicxx \
+  --with-fc=mpifort \
+  --with-shared-libraries \
+  --with-debugging=0 \
+  --with-petsc4py \
+  --download-hypre \
+  --download-mumps --download-scalapack
+
+export PYTHONPATH=${prefix}/lib
+make all
+make install
+make PETSC_DIR=${prefix} PETSC_ARCH="" check
+
+popd