Merge pull request #166 from xylar/add-jigsaw-as-submodule

Add `jigsaw-python` as a submodule

.github/workflows/build_workflow.yml

@@ -88,6 +88,7 @@ jobs:
       - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
         name: Install polaris
         run: |
+          git config --global url."https://github.com/".insteadOf "git@github.com:"
           ./configure_polaris_envs.py \
             --conda_env_only \
             --env_name polaris_test \

.github/workflows/docs_workflow.yml

@@ -44,6 +44,7 @@ jobs:
       - if: ${{ steps.skip_check.outputs.should_skip != 'true' }}
         name: Install polaris
         run: |
+          git config --global url."https://github.com/".insteadOf "git@github.com:"
           ./configure_polaris_envs.py \
             --conda_env_only \
             --env_name polaris_test \

.gitmodules

@@ -7,3 +7,6 @@
 [submodule "e3sm_submodules/Omega"]
 	path = e3sm_submodules/Omega
 	url = git@github.com:E3SM-Project/Omega.git
+[submodule "jigsaw-python"]
+	path = jigsaw-python
+	url = git@github.com:dengwirda/jigsaw-python.git

configure_polaris_envs.py

@@ -114,7 +114,8 @@ def main():
                    f'git clone -b {args.mache_branch} ' \
                    f'git@github.com:{args.mache_fork}.git mache && ' \
                    f'cd mache && ' \
-                   f'python -m pip install .'
+                   f'conda install -y --file spec-file.txt && ' \
+                   f'python -m pip install --no-deps .'
 
         check_call(commands, logger=logger)
 

deploy/bootstrap.py

@@ -9,6 +9,7 @@
 import socket
 import stat
 import subprocess
+import time
 from configparser import ConfigParser
 from typing import Dict
 
@@ -214,13 +215,16 @@ def get_env_setup(args, config, machine, compiler, mpi, env_type, source_path,
         ver = version.parse(polaris_version)
         release_version = '.'.join(str(vr) for vr in ver.release)
         spack_env = f'dev_polaris_{release_version}{env_suffix}'
+        conda_env = f'dev_polaris_{polaris_version}{env_suffix}'
     elif env_type == 'test_release':
         spack_env = f'test_polaris_{polaris_version}{env_suffix}'
+        conda_env = spack_env
     else:
         spack_env = f'polaris_{polaris_version}{env_suffix}'
+        conda_env = spack_env
 
     if env_name is None or env_type != 'dev':
-        env_name = spack_env
+        env_name = conda_env
 
     # add the compiler and MPI library to the spack env name
     spack_env = f'{spack_env}_{compiler}_{mpi}{lib_suffix}'
@@ -241,7 +245,7 @@ def get_env_setup(args, config, machine, compiler, mpi, env_type, source_path,
 def build_conda_env(config, env_type, recreate, mpi, conda_mpi, version,
                     python, source_path, conda_template_path, conda_base,
                     env_name, env_path, activate_base, use_local,
-                    local_conda_build, logger, local_mache):
+                    local_conda_build, logger, local_mache, update_jigsaw):
 
     if env_type != 'dev':
         install_miniforge(conda_base, activate_base, logger)
@@ -287,9 +291,9 @@ def build_conda_env(config, env_type, recreate, mpi, conda_mpi, version,
                             mpi_prefix=mpi_prefix,
                             include_mache=not local_mache)
 
-        for package in ['esmf', 'geometric_features', 'jigsaw', 'jigsawpy',
-                        'mache', 'mpas_tools', 'netcdf_c', 'netcdf_fortran',
-                        'otps', 'parallelio', 'pnetcdf']:
+        for package in ['esmf', 'geometric_features', 'mache', 'mpas_tools',
+                        'netcdf_c', 'netcdf_fortran', 'otps', 'parallelio',
+                        'pnetcdf']:
             replacements[package] = config.get('deploy', package)
 
         spec_file = template.render(**replacements)
@@ -300,7 +304,10 @@ def build_conda_env(config, env_type, recreate, mpi, conda_mpi, version,
     else:
         spec_filename = None
 
-    if not os.path.exists(env_path) or recreate:
+    if not os.path.exists(env_path):
+        recreate = True
+
+    if recreate:
         print(f'creating {env_name}')
         if env_type == 'dev':
             # install dev dependencies and polaris itself
@@ -309,13 +316,6 @@ def build_conda_env(config, env_type, recreate, mpi, conda_mpi, version,
                 f'conda create -y -n {env_name} {channels} ' \
                 f'--file {spec_filename} {packages}'
             check_call(commands, logger=logger)
-
-            commands = \
-                f'{activate_env} && ' \
-                f'cd {source_path} && ' \
-                f'python -m pip install --no-deps -e .'
-            check_call(commands, logger=logger)
-
         else:
             # conda packages don't like dashes
             version_conda = version.replace('-', '')
@@ -332,16 +332,57 @@ def build_conda_env(config, env_type, recreate, mpi, conda_mpi, version,
                 f'conda install -y -n {env_name} {channels} ' \
                 f'--file {spec_filename} {packages}'
             check_call(commands, logger=logger)
+        else:
+            print(f'{env_name} already exists')
+
+    if env_type == 'dev':
+        if recreate or update_jigsaw:
+            # remove conda jigsaw and jigsaw-python
+            t0 = time.time()
+            commands = \
+                f'{activate_env} && ' \
+                f'conda remove -y --force-remove jigsaw jigsawpy'
+            check_call(commands, logger=logger)
 
             commands = \
                 f'{activate_env} && ' \
                 f'cd {source_path} && ' \
-                f'python -m pip install --no-deps -e .'
+                f'git submodule update --init jigsaw-python'
             check_call(commands, logger=logger)
-        else:
-            print(f'{env_name} already exists')
 
-    if env_type == 'dev':
+            print('Building JIGSAW\n')
+            # add build tools to deployment env, not compass env
+            commands = \
+                f'conda install -y cxx-compiler cmake && ' \
+                f'cd {source_path}/jigsaw-python && ' \
+                f'python setup.py build_external'
+            check_call(commands, logger=logger)
+
+            print('Installing JIGSAW and JIGSAW-Python\n')
+            commands = \
+                f'{activate_env} && ' \
+                f'cd {source_path}/jigsaw-python && ' \
+                f'python -m pip install --no-deps -e . && ' \
+                f'cp jigsawpy/_bin/* ${{CONDA_PREFIX}}/bin'
+            check_call(commands, logger=logger)
+
+            t1 = time.time()
+            total = int(t1 - t0 + 0.5)
+            message = f'JIGSAW install took {total:.1f} s.'
+            if logger is None:
+                print(message)
+            else:
+                logger.info(message)
+
+        # install (or reinstall) polaris in edit mode
+        print('Installing polaris\n')
+        commands = \
+            f'{activate_env} && ' \
+            f'cd {source_path} && ' \
+            f'rm -rf polaris.egg-info && ' \
+            f'python -m pip install --no-deps -e .'
+        check_call(commands, logger=logger)
+
         print('Installing pre-commit\n')
         commands = \
             f'{activate_env} && ' \
@@ -1066,14 +1107,17 @@ def main():  # noqa: C901
                 config, env_type, recreate, mpi, conda_mpi, polaris_version,
                 python, source_path, conda_template_path, conda_base,
                 conda_env_name, conda_env_path, activate_base, args.use_local,
-                args.local_conda_build, logger, local_mache)
+                args.local_conda_build, logger, local_mache,
+                args.update_jigsaw)
 
             if local_mache:
                 print('Install local mache\n')
                 commands = f'source {conda_base}/etc/profile.d/conda.sh && ' \
                            f'conda activate {conda_env_name} && ' \
-                           'cd ../build_mache/mache && ' \
-                           'python -m pip install .'
+                           f'conda install -y importlib_resources jinja2' \
+                           f'  lxml pyyaml progressbar2 && ' \
+                           f'cd ../build_mache/mache && ' \
+                           f'python -m pip install --no-deps .'
                 check_call(commands, logger=logger)
 
             previous_conda_env = conda_env_name

deploy/conda-dev-spec.template

@@ -16,8 +16,6 @@ holoviews
 hvplot
 importlib_resources
 ipython
-jigsaw={{ jigsaw }}
-jigsawpy={{ jigsawpy }}
 jupyter
 lxml
 {% if include_mache %}

deploy/default.cfg

@@ -21,8 +21,6 @@ mpi = nompi
 
 # versions of conda packages
 geometric_features = 1.2.0
-jigsaw = 0.9.14
-jigsawpy = 0.3.3
 mache = 1.16.0
 mpas_tools = 0.27.0
 otps = 2021.10

deploy/shared.py

@@ -35,6 +35,10 @@ def parse_args(bootstrap):
                              "for building E3SM components).")
     parser.add_argument("--recreate", dest="recreate", action='store_true',
                         help="Recreate the environment if it exists.")
+    parser.add_argument("--update_jigsaw", dest="update_jigsaw",
+                        action='store_true',
+                        help="Reinstall JIGSAW even if not recreating conda "
+                             "environment.")
     parser.add_argument("-f", "--config_file", dest="config_file",
                         help="Config file to override deployment config "
                              "options.")

docs/developers_guide/quick_start.md

@@ -168,6 +168,10 @@ with the developers.
 In addition to installing Miniforge3 and creating the conda environment for you,
 this script will also:
 
+- install [Jigsaw](https://github.com/dengwirda/jigsaw) and
+  [Jigsaw-Python](https://github.com/dengwirda/jigsaw-python) from source
+  from the `jigsaw-python` submodule. These tools are used to create many of
+  the meshes used in Polaris.
 - install the `polaris` package from the local branch in "development" mode
   so changes you make to the repo are immediately reflected in the conda
   environment.
@@ -212,10 +216,14 @@ this script will also:
   to something other than the default (`dev_polaris_<version>` or
   `dev_polaris_<version>_<mpi>`).
 
-`--with_albany`
+`--update_jigsaw`
 
-: Install Albany for full MALI support (currently only with `gnu`
-  compilers)
+: Used to reinstall Jigsaw and Jigsaw-Python into the conda environment if
+  you have made changes to the Jigsaw (c++) code in the `jigsaw-python`
+  submodule. You should not need to reinstall Jigsaw-Python if you have made
+  changes only to the python code in `jigsaw-python`, as the python package
+  is installed in
+  [edit mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
 
 ### Activating the environment
 
@@ -329,14 +337,14 @@ current branch.  If the two don't match, an error like the following results
 and the environment is not activated:
 
 ```
-$ source load_polaris_test_morpheus_gnu_openmpi.sh 
+$ source load_polaris_test_morpheus_gnu_openmpi.sh
 This load script is for a different version of polaris:
 __version__ = '0.2.0'
 
 Your code is version:
 __version__ = '0.3.0-alpha.1'
 
-You need to run ./configure_polaris_envs.py to update your conda 
+You need to run ./configure_polaris_envs.py to update your conda
 environment and load script.
 ```
 
@@ -378,7 +386,7 @@ the root directory of your polaris branch.  The activation script will also
 check if the current polaris version matches the one used to create the
 activation script, thus catching situations where the dependencies are out
 of date and the configure script needs to be rerun.  Since sourcing the
-activation script is substantially faster than rerunning the configure script, 
+activation script is substantially faster than rerunning the configure script,
 it is best to try the activation script first and run the configure script only
 if you have to.
 :::

docs/index.md

@@ -5,41 +5,49 @@
 :width: 384 px
 ```
 
-Polaris is a python package that provides an automated system to set up test 
-cases or analysis tasks for several components of the Exascale Energy Earth 
+Polaris is a python package that provides an automated system to set up test
+cases or analysis tasks for several components of the Exascale Energy Earth
 System  Model ([E3SM](https://e3sm.org/).  The development version
-of polaris will be kept closely synchronized with the development repositories
-for the components it supports. Release versions will be compatible with 
+of Polaris will be kept closely synchronized with the development repositories
+for the components it supports. Release versions will be compatible with
 specific tags of the MPAS components.
 
-Many polaris tasks are idealized, and are used for things like
+Many Polaris tasks are idealized, and are used for things like
 performing convergence tests or regression tests on particular parts of the
-model code.  Many other polaris tasks, such as those under the
-{ref}`ocean-global-ocean` and {ref}`landice-greenland` test 
-groups, are "realistic" in the sense that they use data sets from observations 
+model code.  Many other Polaris tasks, such as those under the
+{ref}`ocean-global-ocean` and {ref}`landice-greenland` test
+groups, are "realistic" in the sense that they use data sets from observations
 to create  create global and regional meshes,  initial conditions, and boundary
 conditions.
 
 Polaris will be the tool used to create new land-ice and ocean meshes and
-initial conditions for future versions of E3SM. 
+initial conditions for future versions of E3SM.
 
 ```{note} Polaris does *not* provide the tools for creating many of the
 files needed for full E3SM coupling, a process that requires expert help from
 the E3SM development team.
 ```
 
-The ``polaris`` python package defines the tasks and analysis tasks along 
-with the commands  to list and set up both tasks and suites (groups 
-of tasks or analysis tasks).  Polaris currently supports ``landice`` 
+The ``polaris`` python package defines the tasks and analysis tasks along
+with the commands  to list and set up both tasks and suites (groups
+of tasks or analysis tasks).  Polaris currently supports ``landice``
 and ``ocean`` components.  Nearly all tasks include calls that launch one
-of these E3SM components, built in "standalone" (uncoupled) mode.  These runs 
-are configured with config files (e.g. YAML or namelist files) and one of the 
-benefits of using polaris over attempting to run one of the components directly
-is that polaris begins with default values for all these config options
-for a given version of the component, modifying only those options where the 
-default is not  appropriate. In this way, polaris requires little alteration 
+of these E3SM components, built in "standalone" (uncoupled) mode.  These runs
+are configured with config files (e.g. YAML or namelist files) and one of the
+benefits of using Polaris over attempting to run one of the components directly
+is that Polaris begins with default values for all these config options
+for a given version of the component, modifying only those options where the
+default is not  appropriate. In this way, Polaris requires little alteration
 as the model components themselves evolves and new functionality is added.
 
+Polaris makes extensive use of the
+[Jigsaw](https://github.com/dengwirda/jigsaw) and
+[Jigsaw-Python](https://github.com/dengwirda/jigsaw-python) tools to make all
+but the simplest meshes for Polaris tasks.  These tools, without which Polaris'
+ mesh generation capabilities would not be possible, are developed primarily by
+[Darren Engwirda](https://dengwirda.github.io/).
+
+
 ```{toctree}
 :caption: User's guide
 :maxdepth: 2
@@ -91,7 +99,7 @@ glossary
 (compass)=
 # Compass
 
-The ``compass`` package is the predecessor of polaris. Documentation for 
+The ``compass`` package is the predecessor of Polaris. Documentation for
 compass can be found at:
 
 <https://mpas-dev.github.io/compass/latest/>

setup.cfg

@@ -27,7 +27,7 @@ install_requires =
     cmocean
     importlib_resources
     ipython
-    jigsawpy==0.3.3
+    jigsawpy
     jupyter
     lxml
     matplotlib>=3.6.0,!=3.7.2