Skip to content

Text edits #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 28, 2023
Merged

Text edits #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
179abe9
Reorder content of Mesh_Tutorial_Intro.ipynb
BHFock Mar 27, 2023
bd9ac43
Remove output from Sec_01_Load_and_Examine.ipynb
BHFock Mar 27, 2023
db82c76
Improve logical flow of Sec_01_Load_and_Examine.ipynb
BHFock Mar 27, 2023
fb65a83
Minor punctuation change in Mesh_Tutorial_Intro.ipynb
BHFock Mar 28, 2023
d90f5b6
Correct number of printed cubes in Sec_01_Load_and_Examine.ipynb
BHFock Mar 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 36 additions & 39 deletions notebooks/.notebook_shadow_copies/Mesh_Tutorial_Intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,55 @@ jupyter:
name: python3
---

# LFRic + Iris tutorial : Unstructured meshes
# LFRic + Iris tutorial: Unstructured meshes

The tutorial is provided as a set of Jupyter notebooks, best viewed in Juptyer lab.
Please see list below for the individual topics.


## Important Preliminary : use + stability of notebooks
## Tutorial sections (links to individual notebooks):
* [01 - Load and Examine some LFRic data](./Sec_01_Load_and_Examine.ipynb)
* [02 - Mesh concepts and Meshes in Iris](./Sec_02_Meshes.ipynb)
* [03 - Plotting and Visualisation](./Sec_03_Plotting.ipynb)
* [04 - Regridding and UM data comparison](./Sec_04_Regridding.ipynb)
* [05 - Regional Extraction](./Sec_05_RegionExtraction.ipynb)

### Bonus and additional material
* [Bonus 01 - Mesh from Numbers](./Bonus_01_Mesh_from_Numbers.ipynb): Manually construct an Iris mesh
* [Bonus 02 - Mesh Connectivities Demo](./Bonus_02_Mesh_Connectivities_Demo.ipynb): Investigate some details of the LFRic mesh, as it appears in Iris
* [Bonus 03 - MeshCube Extraction](./Bonus_03_MeshCube_Extraction.ipynb): Use Geovista to extract a mesh-cube subregion as a new Iris cube

A good deal of the content relies on code which is still experimental.
We must expect that there are various outstanding problems, and things sometimes crash.
<!-- #region jp-MarkdownHeadingCollapsed=true tags=[] -->
## Jargon: a really brief glossary of terms
* [**UM**](https://code.metoffice.gov.uk/trac/um): The Unified Model
* [**LFRic**](https://www.metoffice.gov.uk/research/approach/modelling-systems/lfric): The UM successor model, modelling cells on an unstructured (cube-sphere) mesh
* **mesh**: Description of arbitrary locations and regions in space
* **unstructured**: An _irregular_ arrangement of spatial locations (constrast with 'regular grids')
* **cubesphere**: Mesh of cells on the globe, arranged like a cube with square cells on each face
* [**CF**](https://cfconventions.org/cf-conventions/cf-conventions.html): Conventions for encoding climate and forecast data in netCDF files
* [**UGRID**](https://ugrid-conventions.github.io/ugrid-conventions/): Conventions which extend CF to data on unstructured meshes
* [**XIOS**](https://forge.ipsl.jussieu.fr/ioserver): Software used by LFRic to save model output as UGRID formatted netCDF files
* [**VTK**](https://vtk.org/): 3D modelling and visualisation package, based in c++
* [**PyVista**](https://pyvista.org/): Python package providing control of VTK from Python code
* [**GeoVista**](https://github.com/bjlittle/geovista#readme): Python package adding geo-location support and utilites to PyVista
* [**ESMF**](https://earthsystemmodeling.org/) Earth System Modelling Framework: modelling support code for regridding, coupling etc, based in FORTRAN
* [**iris-esmf-regrid**](https://github.com/SciTools-incubator/iris-esmf-regrid#readme): Python package providing ESMF-based mesh regridders for Iris

<!-- #endregion -->

A particular problem is getting things working *within notebooks*. For that purpose, the following may be useful general notes :

---
## Use and stability of notebooks

A good deal of the content relies on code which is still experimental. We must expect that there are various outstanding problems, and things sometimes crash. A particular problem is getting things working *within notebooks*. For that purpose, the following may be useful general notes:

### Python environment
When opening a notebook, you may be **prompted** to select the Python environment with which to run it (which must contain Iris, Jupyter, PyVista etc).
We suggest that you launch the Jupyter server _itself_ in the dedicated (conda) tutorial env. Then you can simply use the _same_ env as the server, i.e. select "`Python 3 (ipykernel)`".
We suggest that you launch the Jupyter server _itself_ in the dedicated (conda) tutorial env. Then you can simply use the _same_ env as the server, i.e. select "`Python 3 (ipykernel)`".

### When something seems to be taking a long time with no result...
1. ***first*** look at "kernel status" in top-right of the JupyterLab notebook pane
meanings as described in its mouse-over text :
meanings as described in its mouse-over text:
* white circle = "idle" (ok, done)
* grey circle = "busy"
* "electric zap" icon = "connecting" ***-- this one often means "crashed"***
Expand All @@ -45,38 +74,6 @@ We suggest that you launch the Jupyter server _itself_ in the dedicated (conda)
In such cases, *close* the JupyterLab window + restart
* i.e. `$ jupyter-lab`


---
## Tutorial sections (links to individual notebooks):
* [01 - Load and Examine some LFRic data](./Sec_01_Load_and_Examine.ipynb)
* [02 - Mesh concepts and Meshes in Iris](./Sec_02_Meshes.ipynb)
* [03 - Plotting and Visualisation](./Sec_03_Plotting.ipynb)
* [04 - Regridding and UM data comparison](./Sec_04_Regridding.ipynb)
* [05 - Regional Extraction](./Sec_05_RegionExtraction.ipynb)

### Bonus and additional material
* [Bonus 01 - Mesh from Numbers](./Bonus_01_Mesh_from_Numbers.ipynb): Manually construct an Iris mesh
* [Bonus 02 - Mesh Connectivities Demo](./Bonus_02_Mesh_Connectivities_Demo.ipynb): Investigate some details of the LFRic mesh, as it appears in Iris
* [Bonus 03 - MeshCube Extraction](./Bonus_03_MeshCube_Extraction.ipynb): Use Geovista to extract a mesh-cube subregion as a new Iris cube

<!-- #region jp-MarkdownHeadingCollapsed=true tags=[] -->
## Jargon : a really brief glossary of terms
* **UM** : The Unified Model
* [**LFRic**](https://www.metoffice.gov.uk/research/approach/modelling-systems/lfric) : The UM successor model, modelling cells on an unstructured (cube-sphere) mesh
* **mesh** : description of arbitrary locations and regions in space
* **unstructured** : an _irregular_ arrangement of spatial locations (constrast with 'regular grids')
* **cubesphere** : a mesh of cells on the globe, arranged like a cube with square cells on each face
* [**CF**](https://cfconventions.org/cf-conventions/cf-conventions.html) : conventions for encoding climate + forecast data in netCDF files
* [**UGRID**](https://ugrid-conventions.github.io/ugrid-conventions/) : conventions which extend CF to data on unstructured meshes
* [**XIOS**](https://forge.ipsl.jussieu.fr/ioserver) : the software used by LFRic to save model output as UGRID formatted netCDF files
* [**VTK**](https://vtk.org/) : 3D modelling and visualisation package, based in c++
* [**PyVista**](https://pyvista.org/) : Python package providing control of VTK from Python code
* [**GeoVista**](https://github.com/bjlittle/geovista#readme) : Python package adding geo-location support and utilites to PyVista
* [**ESMF**](https://earthsystemmodeling.org/) Earth System Modelling Framework : modelling support code for regridding, coupling etc, based in FORTRAN
* [**iris-esmf-regrid**](https://github.com/SciTools-incubator/iris-esmf-regrid#readme) : Python package providing ESMF-based mesh regridders for Iris

<!-- #endregion -->

```python

```
96 changes: 40 additions & 56 deletions notebooks/.notebook_shadow_copies/Sec_01_Load_and_Examine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,7 @@ Let's dive right in by taking a look at some output file contents.
<!-- #region -->
## Iris unstructured loading

"Unstructured" data can be loaded from UGRID files (i.e. netCDF files containing a UGRID-style mesh).
This is just like normal Iris loading, except that we must *enable* the interpretion of UGRID content,
roughly like this ...
"Unstructured" data can be loaded from UGRID files (i.e. netCDF files containing a UGRID-style mesh). This is just like normal [Iris](https://scitools-iris.readthedocs.io/en/latest) loading, except that we must *enable* the interpretion of UGRID content like this:

```python
with PARSE_UGRID_ON_LOAD.context():
Expand All @@ -39,91 +37,77 @@ with PARSE_UGRID_ON_LOAD.context():

### Enable UGRID loading

Most importantly, we need the `PARSE_UGRID_ON_LOAD` object from `iris.experimental.ugrid.load`
To test loading of UGRID files, like demonstrated above, we need to import `iris`, and the `PARSE_UGRID_ON_LOAD` object from [iris.experimental.ugrid.load](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/experimental/ugrid/load.html#)


```python tags=[]
import iris

```python
from iris.experimental.ugrid.load import PARSE_UGRID_ON_LOAD
```

### Load UGRID data from netCDF files.
The variable `lfric_filepath` is defined in the tutorial helper code `testdata_fetching`:
It points to a suitable test file.

In this case, we use the plain `iris.load` function, as shown above.
The tutorial helper code `testdata_fetching` defines a variable `lfric_filepath` (and `um_filepath`) which points to suitable a test file.

NOTE : ***There are a lot of cubes: Expect this to take a few seconds, and only show a few of the cubes.***

```python
# First do some preliminary Python setup, imports etc ...
```python tags=[]
# import tutorial helper routines for handling access to test data
from testdata_fetching import lfric_filepth, um_filepth
print('LFRic data availble from: ' + str(lfric_filepth))
print('UM data availble from' + str(um_filepth))
```

# import the top-level Iris package
import iris

# import local routines handling access to some test data
from testdata_fetching import lfric_filepth
```
In this case, we use the plain [iris.load](https://scitools-iris.readthedocs.io/en/latest/userguide/loading_iris_cubes.html) function to load the data (but of course with the PARSE_UGRID_ON_LOAD context) from above listed files.

We show the first few of the cubes. Putting just `cubes` at the end triggers noteboook printing output. You can click on each cube to expand it into detail view. Try this. Try also to use `print(cubes)` instead.

```python
```python tags=[]
print('loading...')
with PARSE_UGRID_ON_LOAD.context():
cubes = iris.load(lfric_filepth)

print(f'\n... Loaded {len(cubes)} cubes.')
print('Showing first 4:')
cubes[:4]
print('Showing first 6:')
cubes[:6]
```


---
**NOTES:**
* putting just `cubes` at the end triggers notebook printing output
* this also means you can click on each cube to "expand" it into a detail view -- ***try this***
* the effect of `print(cubes)` is different -- ***try this***
Putting just `cubes` at the end of the code above triggers noteboook printing output. You can click on each cube to expand it into detail view. Try this. Try also to use `print(cubes)` instead. To spot some structual differences between LFRic and UM data also load some cubes from `um_filepath` above.

<!-- #region -->
## What is notable about "mesh cubes"

## Loading a single cube
You can instead load just a _single_ cube from the file.
This is considerably _faster_ in many cases, since a typical file may contain 100s data-variables (i.e. diagnostics).
In the cube printout above, compared to regular UM-style data (try loading data from `um_filepth`), you can see that it has an additional section in the cube printout called "Mesh", which displays the mesh-specific info. The Mesh has "Mesh coordinates", containing information about latitude and longitude but no dimension coordinates for latitude or longitude. Cubes with a mesh are known in Iris as "unstructured cubes" or "mesh cubes". They also always have a specific "mesh dimension": In the above example it is the _last_ cube dimension.

### Load just "relative_humidity_wrt_water" data
(From the same file)
NOTE: it is nicer to use the `load_cube` function.

```python
with PARSE_UGRID_ON_LOAD.context():
lfric_rh = iris.load_cube(lfric_filepth, "relative_humidity_wrt_water")
The cube itself also now has some extra properties : `cube.mesh`, `cube.location` and `cube.mesh_dim()`
(which are otherwise all `None` if the cube is not a mesh cube)

lfric_rh
```
<!-- #endregion -->

**NOTES:**
* putting just the `lfric_rh` variable at the end of the Jupyter cell triggers notebook printing output
* the effect of `print(lfric_rh)` is different -- ***try this***
## Loading a single cube
To print the three mentioned extras properties we load just a single cube from the file (This is considerably faster if a file contains 100s variables). Let's load just `relative_humidity_wrt_water` data from the example file (`fric_filepth`) whith the [load_cube](https://scitools-iris.readthedocs.io/en/latest/generated/api/iris.html?highlight=load_cube#iris.load_cube) function and print those properties:

```python tags=[]
with PARSE_UGRID_ON_LOAD.context():
lfric_rh = iris.load_cube(lfric_filepth,'relative_humidity_wrt_water')

```python
# just uncomment to explore:
#print(lfric_rh)
#print(lfric_rh.mesh)
#print(lfric_rh.location)
#print(lfric_rh.mesh_dim)

```

## What is notable about "mesh cubes"

In the cube printout above, _compared to regular UM-style data_, you can see that it has an additional section in the cube printout called "Mesh", which displays the mesh-specific info.

The cube itself also now has some extra properties : `cube.mesh`, `cube.location` and `cube.mesh_dim()`
(which are otherwise all `None`)

Cubes with a mesh are known in Iris as "unstructured cubes" or "mesh cubes.
They also always have a specific "mesh dimension": In the above example it is the _last_ cube dimension.
If the cube is not a mesh cube these propertise are `None`, which we can demonstrate with a cube from the "UM file":


```python
```python tags=[]
um_cube = iris.load_cube(um_filepth,'air_temperature')
#print(um_cube)
print(um_cube.mesh)

```

## Next notebook
See the next section: [02 - Mesh concepts and Meshes in Iris](./Sec_02_Meshes.ipynb)

```python

```
Loading