diff --git a/docs/developers_guide/quick_start.md b/docs/developers_guide/quick_start.md index 5b7dd49e0..ebf155761 100644 --- a/docs/developers_guide/quick_start.md +++ b/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_` or `dev_polaris__`). -`--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. ::: diff --git a/docs/index.md b/docs/index.md index 50fc6e0d3..59a8ccd01 100644 --- a/docs/index.md +++ b/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: