A generic set of grid manipulation tools for computer models. These tools are adapted from the ROMS ocean model and for specific use in the MOM6 ocean model. One could hope it can be kept generic enough to support any model. The focus is on supporting the MOM6 ocean model.
For in depth details about the MOM6 ocean model, please visit provided wiki pages. Technical details about this repository can be found below. For usage of the GridUtils library, please visit the user manual.
Various examples are available to demonstrate manipulation of new and existing grids in an iterative or interactive (application) form.
Python notebooks:
Python scripts:
Using the command line or writing your own python scripts is also possible utilizing this library. Please see the python scripts in the examples folder.
- ipython --pylab
The interpreter, ipython, can run python scripts and notebook scripts.
To run a notebook script, you can use
ipython -c "%run your_script.ipynb". Or start ipython, and then
%run your_script.ipynb.
The example python scripts can also be run with ipython.
- jupyter notebook
These prefer notebook files (ipynb). Please see the mkGridIterative.ipynb notebook for a hands on way to access the grid generation library.
A simple graphical user interface (GUI) was built and is available using the mkGridInteractive.ipynb notebook.
- jupyter lab
These prefer notebook files (ipynb). Please see the mkGridIterative.ipynb notebook for a hands on way to access the grid generation library. Jupyter lab also provides a command console for running python scripts.
The grid generation application, mkGridInteractive.ipynb, can be run using jupyter on a cloud hosting system.
- Main:
- Dev:
NOTE: This is provided as a point of demonstration. These cloud system instances do not persist for a long period of time and should not be used in production. Any information created on these systems should be backed up as soon as possible.
The form at mybinder.org can be manually filled out instead of useing the links above:
- GitHub=https://github.com/ESMG/gridtools
- Git ref=main
- Launch
- Once the server loads, navigate to gridTools/mkMapInteractive.ipynb
- Re-run all the cells
- Have fun with the grid editor.
If you plan to use the grid generation software on your system, you need to peform the following steps or follow the local installation tutorial.
Install conda or manually install the python libraries and software dependencies that would allow you to run the python scripts or notebooks.
We have pulled together some pre-defined environments. You may also install an environment yourself. Please review the conda page for more information about conda.
We currently recommend the gridTools environment for use with this library.
NOTE: If conda cannot be used, a list of required software is provided. Once software and libraries are installed, the remaining software should be installable via pip and/or python's virtual environment (venv).
WARNING: If a new enviroment is to be prepared with conda/gridTools.yml,
be prepared to wait a VERY LONG TIME for conda to resolve the
environment. It is highly recommened to load a new environment with
conda/gridTools_export.yml or conda/gridTools_explicit-linux-64.txt.
Download or clone the ESMG/gridtools repository.
The python setup.py install method is now considered a legacy installation
method. Please use the python -m pip install . method.
$ cd gridtools
$ python -m pip install .
If using conda, only minimal changes will be noted.
These are the current workarounds that are required for the grid toolset package. You may need to perform these steps once if you plan to install a copy of the grid generation software.
NOTE: These workarounds should be automatically installed with an installation of gridtools in step 2 using pip.
OPTIONAL: This package is optional. If not using conda, this package is needed to avoid a warning when starting up jupyter.
Could not determine jupyterlab build status without nodejs.
Portable intrinsics for numpy (REPO). For bitwise-the-same reproducable results, a numpy subset of computational functions are provided. These routines are slower than the numpy native routines. A repackaged installable REPO of the library.
A slight modification to xesmf is required to fix a periodic boundary problem when regridding. Note that conda loads an older version of xesmf and then pip replaces it with a fixed copy.
Users using venv, a working compiled copy of ESMF and ESMPy need to be installed prior to installing gridutils via pip.
Until we can activate Sphinx to create our body of documentation we will have to resort to upkeep of a manual index.
Documentation:
- conda
- development
- CHANGELOG: Development log of changes
- CREDITS and citations
- Documentation
- DEPLOY
- Design: Design elements for the grid generation library
- Important References: Things that helped this project work
- Jupyter: Notes on embeddeding applications within a notebook
- python
- TODO: Milestones, tasks, todos and wish list items
- grids
- manual: User manual for the GridUtils library
- Installation tutorial
- Gridtools application tutorial
- API : Gridtools library
- resources
This project is soliciting help in development. Please contribute ideas or bug requests using the issues tab. Code contributions can be sent via github's pull request process. Code adoption will follow the contribution process. Development can be discussed in the MOM6 forum.