Skip to content

Commit 5200c91

Browse files
jsimkins2jsimkins2
authored
Merge pull request #5 from ESMG/dev
Merge dev to main for a 0.1.1 release
2 parents c43a90d + 6387aa5 commit 5200c91

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+2484
-1721
lines changed

‎.github/workflows/base.yml

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# This is a basic workflow to help you get started with Actions
2+
3+
name: CI
4+
5+
# Controls when the action will run.
6+
on:
7+
# Triggers the workflow on push or pull request events but only for the main branch
8+
push:
9+
branches: [ exp/** ]
10+
pull_request:
11+
branches: [ exp/** ]
12+
13+
# Allows you to run this workflow manually from the Actions tab
14+
workflow_dispatch:
15+
16+
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
17+
jobs:
18+
# Create one of more workflows at this level, the next is called "build"
19+
build:
20+
# The type of runner that the job will run on
21+
runs-on: ubuntu-latest
22+
defaults:
23+
run:
24+
shell: bash -l {0}
25+
26+
# Steps represent a sequence of tasks that will be executed as part of the job
27+
steps:
28+
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
29+
- uses: actions/checkout@v2
30+
# Initialize conda environment
31+
- uses: conda-incubator/setup-miniconda@v2
32+
with:
33+
auto-update-conda: true
34+
auto-activate-base: true
35+
activate-environment: ""
36+
37+
# Show the environment of the runner
38+
- name: Environment
39+
run: |
40+
echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
41+
echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
42+
echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
43+
echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
44+
echo "🖥️ The workflow is now ready to test your code on the runner."
45+
uname -a
46+
printenv
47+
48+
# The worker drops you in the middle of your checked out repository
49+
- name: Install
50+
run: |
51+
conda env create -f=conda/gridTools_export.yml
52+
conda activate gridTools
53+
python -m pip install .
54+
55+
# Run tests
56+
- name: Tests
57+
run: |
58+
cd ${{ github.workspace }}
59+
conda activate gridTools
60+
cd tests
61+
pytest
62+
63+

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ __pycache__/
66
# C extensions
77
*.so
88

9+
# VIM
10+
*.swp
11+
912
# Distribution / packaging
1013
.Python
1114
build/
@@ -125,3 +128,6 @@ dmypy.json
125128

126129
# Pyre type checker
127130
.pyre/
131+
132+
# Ignore MacOSX items
133+
.DS_Store

‎CONTRIBUTING.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Please make contributions to this project through discussion or
2+
proposing material on the [issues]() tab.
3+
4+
Direct code contributions should be made by creating a
5+
[fork]() of this projection and providing a
6+
[pull request]() to the `dev` branch.
7+
8+
Developers with `commit` access to this repository
9+
should develop on a branch using the name `exp/`.
10+
When finished, send a **pull request** to the
11+
`dev` branch for inclusion.
12+
13+
As milestones are reached, a pull request from
14+
the `dev` branch will be sent to the `main`
15+
branch and eventually tagged and released.

‎README.md

+96-73
Original file line numberDiff line numberDiff line change
@@ -10,132 +10,134 @@ For in depth details about the MOM6 ocean model, please visit provided
1010
details about this repository can be found below. For usage of
1111
the GridUtils library, please visit the [user manual](docs/manual/GridUtils.md).
1212

13-
Required items:
14-
* spherical.py
15-
* gridutils.py
16-
* app.py
17-
18-
Optional items:
19-
* sysinfo.py
20-
21-
Various tools are available to manipulation of new and existing grids in
22-
an iterative or interactive form.
13+
Various examples are available to demonstrate manipulation of new and existing
14+
grids in an iterative or interactive (application) form.
2315

2416
Python notebooks:
25-
* mkGridIterative.ipynb
26-
* mkGridInteractive.ipynb
17+
* [mkGridIterative.ipynb](examples/mkGridIterative.ipynb)
18+
* [mkGridInteractive.ipynb](examples/mkGridInteractive.ipynb)
19+
* The [gridtools application tutorial](docs/manual/gridtoolAppTutorial.ipynb)
2720

28-
With this software, you should be able to operate in any mode you prefer.
21+
Python scripts:
22+
* [examples](examples)
2923

3024
# Operational Modes
3125

3226
## Command Line
3327

34-
Using the command line or writing your own python scripts possible utilizing this library.
35-
To look at a few examples, please look at the mkGridsExample1.py, mkGridsExample2.py and
36-
mkGridsExample3.py programs.
28+
Using the command line or writing your own python scripts is also
29+
possible utilizing this library. Please see the python scripts
30+
in the [examples](examples) folder.
3731

3832
## Command Line Widget Mode
3933

4034
* ipython --pylab
4135

42-
The interpreter, ipython, can run python scripts and notebook scripts. To run a notebook
43-
script, you can use `ipython -c "%run your_script.ipynb"`. Or start ipython, and then
36+
The interpreter, ipython, can run python scripts and notebook scripts.
37+
To run a notebook script, you can use
38+
`ipython -c "%run your_script.ipynb"`. Or start ipython, and then
4439
`%run your_script.ipynb`.
4540

46-
Again, the mkGridsExample.py programs can be run with ipython.
41+
The [example](examples) python scripts can also be run with ipython.
4742

4843
## Jupyter notebook
4944

5045
* jupyter notebook
5146

52-
These prefer notebook files (ipynb). Please see the mkGridIterative.ipynb program for a hands
53-
on way to access the grid generation library.
47+
These prefer notebook files (ipynb). Please see the
48+
mkGridIterative.ipynb notebook for a hands on way to access the grid
49+
generation library.
5450

55-
A simple graphical user interface (GUI) was built and is available when you run the
51+
A simple graphical user interface (GUI) was built and is available using the
5652
mkGridInteractive.ipynb notebook.
5753

5854
## Jupyter lab
5955

6056
* jupyter lab
6157

62-
These prefer notebook files (ipynb). Please see the mkGridIterative.ipynb program for a hands
63-
on way to access the grid generation library.
58+
These prefer notebook files (ipynb). Please see the
59+
mkGridIterative.ipynb notebook for a hands on way to access the grid
60+
generation library. Jupyter lab also provides a command console
61+
for running python scripts.
6462

65-
A simple graphical user interface (GUI) was built and is available when you run the
66-
mkGridInteractive.ipynb notebook.
63+
## Application
6764

68-
## mybinder
65+
The grid generation application, mkGridInteractive.ipynb, can be run
66+
using jupyter on a cloud hosting system.
67+
68+
### mybinder.org
6969

7070
* Main: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ESMG/gridtools/main)
7171
* Dev: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ESMG/gridtools/dev)
7272

73-
Instead of loading software on your computer, the library and application is hosted on a cloud system. You do not
74-
have to install anything on your system to use the cloud system's copy of the grid generation library.
75-
76-
# Application
73+
NOTE: This is provided as a point of demonstration. These cloud
74+
system instances do not persist for a long period of time and should
75+
not be used in production. Any information created on these systems
76+
should be backed up as soon as possible.
7777

78-
The grid generation application, mkGridInteractive.ipynb, can be run on a cloud hosting system. The application has been adapted to work on mybinder.org.
79-
NOTICE: The mybinder application can take upwards to 30 minutes to build.
80-
81-
Use the following options:
78+
The form at mybinder.org can be manually filled out instead of useing the links
79+
above:
8280
* GitHub=https://github.com/ESMG/gridtools
8381
* Git ref=main
8482
* Launch
8583
* Once the server loads, navigate to gridTools/mkMapInteractive.ipynb
8684
* Re-run all the cells
8785
* Have fun with the grid editor.
8886

89-
# Code contributions
90-
91-
## Lambert Conformal Conic Grid Generation
92-
Author: Niki Zadeh [REPO](https://github.com/nikizadehgfdl/grid_generation)
93-
* [regional_grid_spheical.ipynb](https://github.com/nikizadehgfdl/grid_generation/blob/dev/jupynotebooks/regional_grid_spherical.ipynb)
94-
95-
## Numpy bitwise-the-same floating-point values
96-
Author: Alistair Adcroft [REPO](https://github.com/adcroft/numpypi)
97-
* To obtain bitwise-the-same floating-point values in certain non-time-critical calculations.
98-
99-
## ROMS to MOM6 Grid Converter
100-
Authors: Mehmet Ilicak; Alistair Adcroft [REPO](https://github.com/ESMG/pyroms)
101-
* [convert_ROMS_grid_to_MOM6.py](https://raw.githubusercontent.com/ESMG/pyroms/python3/examples/grid_MOM6/convert_ROMS_grid_to_MOM6.py)
102-
10387
# Installation
10488

105-
If you plan to use the grid generation software on your system, you need to peform the following steps.
89+
If you plan to use the grid generation software on your system, you
90+
need to peform the following steps or follow the
91+
[local installation tutorial](docs/manual/local_installation_tutorial.ipynb).
10692

10793
## Step 1
10894

109-
[Download](https://github.com/ESMG/gridtools/archive/refs/heads/main.zip) or [clone](https://github.com/ESMG/gridtools.git) the
110-
[ESMG/gridtools](https://github.com/ESMG/gridtools) repository.
95+
Install conda or manually install the python libraries and software
96+
dependencies that would allow you to run the python scripts or notebooks.
11197

112-
Discover the full directory path to gridtools/gridTools/lib. Place the full path in the environment variable `LIBROOT` if you are planning to run
113-
the python notebooks. If you are going to use the library in your scripts, simply append the full path to `PYTHONPATH`. In the future, we will enable
114-
installation using ptyhon pip.
98+
We have pulled together some pre-defined environments. You may also
99+
install an environment yourself. Please review the
100+
[conda](docs/conda/README.md) page for more information about conda.
115101

116-
## Step 2
102+
We currently recommend the *gridTools* environment for use with this
103+
library.
117104

118-
Install conda or manually install the python libraries and software dependencies that would allow you to run the python scripts or notebooks.
105+
NOTE: If **conda** cannot be used,
106+
a list of [required software](docs/development/Requirements.md) is
107+
provided. Once software and libraries are installed, the remaining
108+
software should be installable via pip and/or python's virtual
109+
environment (venv).
119110

120-
We have pulled together some pre-defined environments. You may also install an environment yourself. Please look at the [conda](docs/conda/README.md)
121-
page for more information about conda.
111+
## Step 2
122112

123-
We currently recommend the *xesmfTools* environment for use with this libaray.
113+
[Download](https://github.com/ESMG/gridtools/archive/refs/heads/main.zip)
114+
or [clone](https://github.com/ESMG/gridtools.git) the
115+
[ESMG/gridtools](https://github.com/ESMG/gridtools) repository.
124116

125-
## Step 3
117+
The `python setup.py install` method is now considered a legacy installation
118+
method. Please use the `python -m pip install` method.
126119

127-
Follow any steps in the "Workarounds" section.
120+
### pip
121+
122+
```
123+
$ cd gridtools
124+
$ python -m pip install .
125+
```
128126

129127
# Workarounds
130128

131-
These are the current workarounds that are required for the grid toolset
132-
package. You will need to perform these steps once if you plan to install a
133-
copy of the grid generation software.
129+
These are the current workarounds that are required for the grid
130+
toolset package. You may need to perform these steps once if you
131+
plan to install a copy of the grid generation software.
132+
133+
NOTE: These workarounds should be automatically installed with
134+
an installation of gridtools.
134135

135136
## datashader
136137

137-
The lastest version from github is required for proper operation of bokeh, holoviews and panel which
138-
are used by the interactive portions of the grid generation library.
138+
The lastest version from github is required for proper operation of
139+
bokeh, holoviews and panel which are used by the interactive portions
140+
of the grid generation library.
139141

140142
[REPO](https://github.com/holoviz/datashader)
141143

@@ -145,13 +147,29 @@ Installation:
145147
* Make sure your conda enviroment is active.
146148
* `pip install -e .`
147149

148-
## numpypi
150+
NOTE: The datashader library should be automatically installed as a
151+
dependency of gridtools.
149152

150-
NOTE: This has not been fully implemented yet. Do not worry about this just yet.
153+
## numpypi
151154

155+
Portable intrinsics for numpy ([REPO](https://github.com/adcroft/numpypi)).
152156
For bitwise-the-same reproducable results, a numpy subset of computational functions are
153-
provided. These routines are slower than the numpy native routines.
154-
[REPO](https://github.com/adcroft/numpypi)
157+
provided. These routines are slower than the numpy native routines.
158+
A repackaged installable [REPO](https://github.com/jr3cermak/numpypi/tree/dev) of the library.
159+
160+
# Code contributions
161+
162+
## Lambert Conformal Conic Grid Generation
163+
Author: Niki Zadeh [REPO](https://github.com/nikizadehgfdl/grid_generation)
164+
* [regional_grid_spheical.ipynb](https://github.com/nikizadehgfdl/grid_generation/blob/dev/jupynotebooks/regional_grid_spherical.ipynb)
165+
166+
## Portable intrinsics for numpy
167+
Author: Alistair Adcroft [REPO](https://github.com/adcroft/numpypi)
168+
* To obtain bitwise-the-same floating-point values in certain non-time-critical calculations.
169+
170+
## ROMS to MOM6 Grid Converter
171+
Authors: Mehmet Ilicak; Alistair Adcroft [REPO](https://github.com/ESMG/pyroms)
172+
* [convert_ROMS_grid_to_MOM6.py](https://raw.githubusercontent.com/ESMG/pyroms/python3/examples/grid_MOM6/convert_ROMS_grid_to_MOM6.py)
155173

156174
# More
157175

@@ -163,6 +181,7 @@ to upkeep of a manual index.
163181
* [development](docs/development)
164182
* [CHANGELOG](docs/development/CHANGELOG.md): Development log of changes
165183
* [CREDITS](docs/development/CREDITS.md)
184+
* [DEPLOY](docs/development/DEPLOY.md)
166185
* [Design](docs/development/Design.md): Design elements for the grid generation library
167186
* [Important References](docs/development/ImportantReferences.md): Things that helped this project work
168187
* [Jupyter](docs/development/Jupyter.md): Notes on embeddeding applications within a notebook
@@ -178,10 +197,14 @@ to upkeep of a manual index.
178197
* [MOM6ROMS](docs/grids/MOM6ROMS.md): Important things between MOM6 and ROMS grids
179198
* [ROMS](docs/grids/ROMS.md): ROMS grids
180199
* [manual](docs/manual/GridUtils.md): User manual for the GridUtils library
200+
* [Installation tutorial](docs/manual/local_installation_tutorial.ipynb)
201+
* [Gridtools application tutorial](docs/manual/gridtoolAppTutorial.ipynb)
181202
* [resources](docs/resources)
182203
* [Bathymetry](docs/resources/Bathymetry)
183204

184205
# Development
185206

186-
This project is soliciting help in development. Please contribute ideas or bug requests using the issues tab.
187-
Code contributions can be sent via github's pull request process.
207+
This project is soliciting help in development. Please contribute
208+
ideas or bug requests using the issues tab. Code contributions can
209+
be sent via github's pull request process. Code adoption will follow
210+
the [contribution](CONTRIBUTING.md) process.

0 commit comments

Comments
 (0)