Add conda environment to run on personal computers

configuration/scripts/cice.batch.csh

@@ -242,6 +242,12 @@ cat >> ${jobfile} << EOFB
 # nothing to do
 EOFB
 
+else if (${ICE_MACHINE} =~ conda*) then
+cat >> ${jobfile} << EOFB
+# nothing to do
+EOFB
+
+
 else
   echo "${0} ERROR: ${ICE_MACHINE} unknown"
   exit -1

configuration/scripts/cice.launch.csh

@@ -212,6 +212,19 @@ endif
 #srun -n ${ntasks} -c ${nthrds} ./cice >&! \$ICE_RUNLOG_FILE
 #EOFR
 
+#=======
+else if (${ICE_MACHINE} =~ conda*) then
+if (${ICE_COMMDIR} =~ serial*) then
+cat >> ${jobfile} << EOFR
+./cice >&! \$ICE_RUNLOG_FILE
+EOFR
+else
+cat >> ${jobfile} << EOFR
+mpirun -np ${ntasks} ./cice >&! \$ICE_RUNLOG_FILE
+EOFR
+endif
+
+
 #=======
 else
   echo "${0} ERROR ${ICE_MACHINE} unknown"

configuration/scripts/machines/Macros.conda_linux

@@ -0,0 +1,51 @@
+#==============================================================================
+# Makefile macros for conda environment, GNU/Linux systems
+#==============================================================================
+
+# Preprocessor macros
+CPPDEFS    := -DFORTRANUNDERSCORE ${ICE_CPPDEFS}
+
+# Flags for the C compiler
+CFLAGS     := -c -O2
+
+# Flags for the Fortran compiler
+FREEFLAGS  := -ffree-form
+FFLAGS     := -fconvert=big-endian -fbacktrace -ffree-line-length-none
+
+# Additional flags for the Fortran compiler when compiling in debug mode
+ifeq ($(ICE_BLDDEBUG), true)
+  FFLAGS   += -O0 -g -fcheck=bounds -finit-real=nan -fimplicit-none -ffpe-trap=invalid,zero,overflow
+else
+  FFLAGS   += -O2
+endif
+
+# C and Fortran compilers and MPI wrappers
+SCC   := gcc
+SFC   := gfortran
+MPICC := mpicc
+MPIFC := mpifort
+
+ifeq ($(ICE_COMMDIR), mpi)
+  FC := $(MPIFC)
+  CC := $(MPICC)
+else
+  FC := $(SFC)
+  CC := $(SCC)
+endif
+
+# Linker
+LD:= $(FC)
+
+# Location of the compiled Fortran modules (NetCDF)
+MODDIR  += -I$(CONDA_PREFIX)/include
+
+# Libraries to be passed to the linker
+SLIBS   := -lnetcdf -lnetcdff
+
+# Necessary flag to compile with OpenMP support
+ifeq ($(ICE_THREADED), true)
+   LDFLAGS += -fopenmp
+   CFLAGS  += -fopenmp
+   FFLAGS  += -fopenmp
+endif
+

configuration/scripts/machines/Macros.conda_macos

@@ -0,0 +1,51 @@
+#==============================================================================
+# Makefile macros for conda environment, macOS systems
+#==============================================================================
+
+# Preprocessor macros
+CPPDEFS    := -DFORTRANUNDERSCORE ${ICE_CPPDEFS}
+
+# Flags for the C compiler
+CFLAGS     := -c -O2
+
+# Flags for the Fortran compiler
+FREEFLAGS  := -ffree-form
+FFLAGS     := -fconvert=big-endian -fbacktrace -ffree-line-length-none
+
+# Additional flags for the Fortran compiler when compiling in debug mode
+ifeq ($(ICE_BLDDEBUG), true)
+  FFLAGS   += -O0 -g -fcheck=bounds -finit-real=nan -fimplicit-none -ffpe-trap=invalid,zero,overflow
+else
+  FFLAGS   += -O2
+endif
+
+# C and Fortran compilers and MPI wrappers
+SCC   := clang
+SFC   := gfortran
+MPICC := mpicc
+MPIFC := mpifort
+
+ifeq ($(ICE_COMMDIR), mpi)
+  FC := $(MPIFC)
+  CC := $(MPICC)
+else
+  FC := $(SFC)
+  CC := $(SCC)
+endif
+
+# Linker
+LD:= $(FC)
+
+# Location of the compiled Fortran modules (NetCDF)
+MODDIR  += -I$(CONDA_PREFIX)/include
+
+# Libraries to be passed to the linker
+SLIBS   := -lnetcdf -lnetcdff
+
+# Necessary flag to compile with OpenMP support
+ifeq ($(ICE_THREADED), true)
+   LDFLAGS += -fopenmp
+   CFLAGS  += -fopenmp
+   FFLAGS  += -fopenmp
+endif
+

configuration/scripts/machines/env.conda_linux

@@ -0,0 +1,29 @@
+#!/bin/csh -f
+
+set inp = "undefined"
+if ($#argv == 1) then
+  set inp = $1
+endif
+
+if ("$inp" != "-nomodules") then
+
+# Init conda
+source `conda info --base`/etc/profile.d/conda.csh
+# Activate "cice" conda environment
+conda activate cice
+
+endif
+
+setenv ICE_MACHINE_ENVNAME conda
+setenv ICE_MACHINE_COMPILER conda
+setenv ICE_MACHINE_MAKE make
+setenv ICE_MACHINE_WKDIR  $HOME/cice-dirs/runs
+setenv ICE_MACHINE_INPUTDATA $HOME/cice-dirs/input
+setenv ICE_MACHINE_BASELINE $HOME/cice-dirs/baseline
+setenv ICE_MACHINE_SUBMIT " "
+setenv ICE_MACHINE_TPNODE 4
+setenv ICE_MACHINE_ACCT P0000000
+setenv ICE_MACHINE_QUEUE "debug"
+setenv ICE_MACHINE_BLDTHRDS 4
+setenv ICE_MACHINE_QSTAT " "
+

configuration/scripts/machines/env.conda_macos

@@ -0,0 +1,29 @@
+#!/bin/csh -f
+
+set inp = "undefined"
+if ($#argv == 1) then
+  set inp = $1
+endif
+
+if ("$inp" != "-nomodules") then
+
+# Init conda
+source `conda info --base`/etc/profile.d/conda.csh
+# Activate "cice" conda environment
+conda activate cice
+
+endif
+
+setenv ICE_MACHINE_ENVNAME conda
+setenv ICE_MACHINE_COMPILER macos
+setenv ICE_MACHINE_MAKE make
+setenv ICE_MACHINE_WKDIR  $HOME/cice-dirs/runs
+setenv ICE_MACHINE_INPUTDATA $HOME/cice-dirs/input
+setenv ICE_MACHINE_BASELINE $HOME/cice-dirs/baseline
+setenv ICE_MACHINE_SUBMIT " "
+setenv ICE_MACHINE_TPNODE 4
+setenv ICE_MACHINE_ACCT P0000000
+setenv ICE_MACHINE_QUEUE "debug"
+setenv ICE_MACHINE_BLDTHRDS 4
+setenv ICE_MACHINE_QSTAT " "
+

configuration/scripts/machines/environment.yml

@@ -0,0 +1,18 @@
+name: cice
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+# Build dependencies
+  - compilers
+  - netcdf-fortran
+  - openmpi
+  - make
+# Python dependencies for plotting scripts
+  - numpy
+  - matplotlib-base
+  - basemap
+  - netcdf4
+# Python dependencies for building the HTML documentation
+  - sphinx
+  - sphinxcontrib-bibtex

doc/source/user_guide/ug_running.rst

@@ -465,7 +465,7 @@ and write permissions such that a set of users can update the inputdata area as
 new datasets are available.
 
 CICE input datasets are stored on an anonymous ftp server.  More information about
-how to download the input data can be found at https://github.com/CICE-Consortium/CICE/wiki.
+how to download the input data can be found at https://github.com/CICE-Consortium/CICE/wiki/CICE-Input-Data.
 Test forcing datasets are available for various grids at the ftp site.  
 These data files are designed only for testing the code, not for use in production runs 
 or as observational data. Please do not publish results based on these data sets.
@@ -582,3 +582,139 @@ To use the C-Shell version of the script, ::
 
 $ ./timeseries.csh /p/work1/turner/CICE_RUNS/conrad_intel_smoke_col_1x1_diag1_run1year.t00/
 
+
+Running CICE on laptop/personal computers
+-----------------------------------------
+To get the required software necessary to build and run CICE, and use the plotting and quality control scripts included in the repository, a `conda <https://docs.conda.io/en/latest/>`_ environment file is available at :
+
+``configuration/scripts/machines/environment.yml``.
+
+This configuration is supported by the Consortium on a best-effort basis on macOS and GNU/Linux. It is untested under Windows, but might work using the `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
+
+Installing Miniconda
+~~~~~~~~~~~~~~~~~~~~
+
+We recommend the use of the `Miniconda distribution <https://docs.conda.io/en/latest/miniconda.html>`_ to create a self-contained conda environment from the ``environment.yml`` file. If you do not have Miniconda or Anaconda installed, you can install Miniconda by following the `official instructions  <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_, or with these steps:
+
+On macOS:
+
+.. code-block:: bash
+
+  # Download the Miniconda installer to ~/Downloads/miniconda.sh
+  wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -O ~/Downloads/miniconda.sh
+  # Install Miniconda
+  bash ~/Downloads/miniconda.sh
+
+  # Answer 'yes' when the installer asks you if you want to initialize your shell to use conda
+
+  # Close and reopen your shell
+
+  # Don't activate the "base" conda environment on shell startup
+  conda config --set auto_activate_base false
+
+On GNU/Linux:
+
+.. code-block:: bash
+
+  # Download the Miniconda installer to ~/miniconda.sh
+  wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
+  # Install Miniconda
+  bash ~/miniconda.sh
+
+  # Answer 'yes' when the installer asks you if you want to initialize your shell to use conda
+
+  # Close and reopen your shell
+
+  # Don't activate the "base" conda environment on shell startup
+  conda config --set auto_activate_base false
+
+
+Creating CICE directories and the conda environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The conda configuration expects some directories to be present at ``$HOME/cice-dirs``:
+
+.. code-block:: bash
+
+  cd $HOME
+  mkdir -p cice-dirs/runs cice-dirs/baseline cice-dirs/input
+  # Download the required forcing from https://github.com/CICE-Consortium/CICE/wiki/CICE-Input-Data
+  # and untar it at $HOME/cice-dirs/input
+
+Create the conda environment from the ``environment.yml`` file:
+
+.. code-block:: bash
+
+  conda env create -f configuration/scripts/machines/environment.yml
+
+
+Using the conda configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the general instructions in :ref:`overview`, using the ``conda`` machine name and ``macos`` or ``linux`` as compiler names.
+
+On macOS:
+
+.. code-block:: bash
+
+  ./cice.setup -m conda -e macos -c ~/cice-dirs/cases/case1
+  cd ~/cice-dirs/cases/case1
+  ./cice.build
+  ./cice.run
+
+On GNU/Linux:
+
+.. code-block:: bash
+
+  ./cice.setup -m conda -e linux -c ~/cice-dirs/cases/case1
+  cd ~/cice-dirs/cases/case1
+  ./cice.build
+  ./cice.run
+
+A few notes about the conda configuration:
+
+- This configuration always runs the model interactively, such that ``./cice.run`` and ``./cice.submit`` are the same.
+- Depending on the numbers of CPUs in your machine, you might not be able to run with the default MPI configuration (``-p 4x1``). You likely will get an OpenMPI error such as:
+
+    There are not enough slots available in the system to satisfy the 4 slots that were requested by the application:  ./cice
+
+  You can run CICE in serial mode by specifically requesting only one process:
+
+  .. code-block:: bash
+
+    ./cice.setup -m conda -e linux -p 1x1 ...
+
+  If you do want to run with more MPI processes than the number of available CPUs in your machine, you can add the ``--oversubscribe`` flag to the ``mpirun`` call in ``cice.run``:
+
+  .. code-block:: bash
+
+    # For a specific case:
+    # Open cice.run and replace the line
+    mpirun -np <num> ./cice >&! $ICE_RUNLOG_FILE
+    # with
+    mpirun -np <num> --oversubscribe ./cice >&! $ICE_RUNLOG_FILE
+
+    # For all future cases:
+    # Open configuration/scripts/cice.launch.csh and replace the line
+    mpirun -np ${ntasks} ./cice >&! \$ICE_RUNLOG_FILE
+    # with
+    mpirun -np ${ntasks} --oversubscribe ./cice >&! \$ICE_RUNLOG_FILE
+
+- It is not recommeded to run other test suites than ``quick_suite`` or ``travis_suite`` on a personal computer.
+- The conda environment is automatically activated when compiling or running the model using the ``./cice.build`` and ``./cice.run`` scripts. To use the environment with the Python plotting (see :ref:`timeseries`) and quality control scripts (see :ref:`CodeCompliance`), you must manually activate the environment:
+
+  .. code-block:: bash
+
+    cd ~/cice-dirs/cases/case1
+    conda activate cice
+    python timeseries.py ~/cice-dirs/cases/case1/logs
+    conda deactivate  # to deactivate the environment
+
+- The environment also contains the Sphinx package necessesary to build the HTML documentation :
+
+  .. code-block:: bash
+
+    cd doc
+    conda activate cice
+    make html
+    # Open build/html/index.html in your browser
+    conda deactivate  # to deactivate the environment