Skip to content

Commit 8b8c755

Browse files
erogluorhanerogluorhan
authored
Merge branch 'main' into version-bump-2022.10.0
2 parents 42603df + 9d45b5e commit 8b8c755

File tree

6 files changed

+525
-784
lines changed

6 files changed

+525
-784
lines changed

‎docs/examples.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,5 @@ see the :doc:`contributing`.
1515
:maxdepth: 1
1616
:hidden:
1717

18-
examples/reading-data.ipynb
19-
examples/template.ipynb
18+
examples/001-read-grid-data.ipynb
19+
examples/002-access-grid-info.ipynb

docs/examples/template.ipynb renamed to docs/examples/000-template.ipynb

File renamed without changes.

‎docs/examples/001-read-grid-data.ipynb‎

Lines changed: 230 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/examples/002-access-grid-info.ipynb‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"source": [
6+
"# Accessing Grid Information\n",
7+
"\n",
8+
"Unstructured grids can be represented in one of many different conventions\n",
9+
"(UGRID, SCRIP, EXODUS, etc). These conventions have different definitions\n",
10+
"and representations of the attributes and variables used to describe\n",
11+
"the unstructured grid topology. Even more, the [UGRID conventions](\n",
12+
"https://ugrid-conventions.github.io/ugrid-conventions/) does not\n",
13+
"enforce standard variable namings for most of the attributes and variables\n",
14+
"(other than just a few required ones).\n",
15+
"\n",
16+
"UXarray unifies all of these conventions at the data loading step by\n",
17+
"representing grids in the UGRID convention regardless of the original grid\n",
18+
"type that is read in from the file. Furthermore, it uses a set of\n",
19+
"standardized names for topology attributes and variables, while still\n",
20+
"providing the user with the original attribute names and variables that\n",
21+
"came from the grid definition file.\n",
22+
"\n",
23+
"## Overview\n",
24+
"\n",
25+
"This notebook will showcase the different methods available for accessing\n",
26+
"the grid topology attributes and variables stored in the `UXarray.Grid`\n",
27+
"object.\n",
28+
"\n",
29+
"For more details on how to load in data, check out our [previous usage\n",
30+
"example](https://uxarray.readthedocs.io/en/latest/examples/read-grid-data.html)\n",
31+
"\n",
32+
"**Methods**\n",
33+
"1. Indexing with Original Variable Names\n",
34+
"2. Indexing with UXarray Variable Dictionary\n",
35+
"3. UXarray's Standardized UGRID Names (Most convenient)"
36+
],
37+
"metadata": {
38+
"collapsed": false
39+
}
40+
},
41+
{
42+
"cell_type": "markdown",
43+
"source": [
44+
"## Data\n",
45+
"\n",
46+
"We will be using two grid files, both of which are in the UGRID convention.\n",
47+
"However, the key difference between them is the names used to describe the\n",
48+
"attributes and variables.\n",
49+
"\n",
50+
"Let us first read in the data:"
51+
],
52+
"metadata": {
53+
"collapsed": false
54+
}
55+
},
56+
{
57+
"cell_type": "code",
58+
"execution_count": 4,
59+
"outputs": [],
60+
"source": [
61+
"import uxarray as ux\n",
62+
"import xarray as xr"
63+
],
64+
"metadata": {
65+
"collapsed": false
66+
}
67+
},
68+
{
69+
"cell_type": "code",
70+
"execution_count": 5,
71+
"outputs": [],
72+
"source": [
73+
"# Base data path\n",
74+
"base_path = \"../../test/meshfiles/\"\n",
75+
"\n",
76+
"# Path to Grid files\n",
77+
"ugrid_01_path = base_path + \"outCSne30.ug\"\n",
78+
"ugrid_02_path = base_path + \"geoflow-small/grid.nc\"\n",
79+
"\n",
80+
"# Load grid files and create UXarray Grid objects\n",
81+
"ugrid_01_ds = xr.open_dataset(ugrid_01_path)\n",
82+
"ugrid_02_ds = xr.open_dataset(ugrid_02_path)\n",
83+
"\n",
84+
"ugrid_01 = ux.Grid(ugrid_01_ds)\n",
85+
"ugrid_02 = ux.Grid(ugrid_02_ds)"
86+
],
87+
"metadata": {
88+
"collapsed": false
89+
}
90+
},
91+
{
92+
"cell_type": "markdown",
93+
"source": [
94+
"The output of the bottom cell showcases the slight differences\n",
95+
"in variable names:"
96+
],
97+
"metadata": {
98+
"collapsed": false
99+
}
100+
},
101+
{
102+
"cell_type": "code",
103+
"execution_count": 16,
104+
"outputs": [
105+
{
106+
"name": "stdout",
107+
"output_type": "stream",
108+
"text": [
109+
"\n",
110+
"Variable Names\n",
111+
"ugrid_01 variable names: ['Mesh2', 'Mesh2_face_nodes', 'Mesh2_node_x', 'Mesh2_node_y', 'nMesh2_face', 'nMaxMesh2_face_nodes', 'nMesh2_node']\n",
112+
"ugrid_02 variable names: ['mesh', 'mesh_face_nodes', 'mesh_depth', 'mesh_node_x', 'mesh_node_y', 'nMeshFaces', 'nFaceNodes', 'nMeshNodes', 'meshLayers']\n"
113+
]
114+
}
115+
],
116+
"source": [
117+
"# Extract variable names\n",
118+
"ugrid_01_names = list(ugrid_01.ds.keys()) + \\\n",
119+
" list(ugrid_01.ds.coords) + \\\n",
120+
" list(ugrid_01.ds.dims)\n",
121+
"ugrid_02_names = list(ugrid_02.ds.keys()) + \\\n",
122+
" list(ugrid_02.ds.coords) + \\\n",
123+
" list(ugrid_02.ds.dims)\n",
124+
"\n",
125+
"print(\"\\nAttribute and variable names for each grid:\")\n",
126+
"print(\"ugrid_01 variable names:\", ugrid_01_names)\n",
127+
"print(\"ugrid_02 variable names:\", ugrid_02_names)"
128+
],
129+
"metadata": {
130+
"collapsed": false
131+
}
132+
},
133+
{
134+
"cell_type": "markdown",
135+
"source": [
136+
"## 1. Indexing with Original Variable Names\n",
137+
"\n",
138+
"The simplest approach is to use the original variable name as an index\n",
139+
"into the grid dataset, `Grid.ds`. Since `ugrid_01` and `ugrid_02` have\n",
140+
"different names for most of their topology attributes and variables, the\n",
141+
"index for accessing them will be different for both grids."
142+
],
143+
"metadata": {
144+
"collapsed": false
145+
}
146+
},
147+
{
148+
"cell_type": "code",
149+
"execution_count": 20,
150+
"outputs": [],
151+
"source": [
152+
"x_1 = ugrid_01.ds['Mesh2_node_x']\n",
153+
"y_1 = ugrid_01.ds['Mesh2_node_y']\n",
154+
"face_nodes_1 = ugrid_01.ds['Mesh2_face_nodes']\n",
155+
"n_face_nodes_1 = ugrid_01.ds['nMaxMesh2_face_nodes']\n",
156+
"\n",
157+
"x_2 = ugrid_02.ds['mesh_node_x']\n",
158+
"y_2 = ugrid_02.ds['mesh_node_y']\n",
159+
"face_nodes_2 = ugrid_02.ds['mesh_face_nodes']\n",
160+
"n_face_nodes_2 = ugrid_02.ds['nFaceNodes']"
161+
],
162+
"metadata": {
163+
"collapsed": false
164+
}
165+
},
166+
{
167+
"cell_type": "markdown",
168+
"source": [
169+
"## 2. Indexing with UXarray Variable Dictionary\n",
170+
"\n",
171+
"UXarray provides a dictionary, `Grid.ds_var_names`, to map the original\n",
172+
"topology attribute and variable names that come from the grid file into\n",
173+
"a standardized set of names. In other words, the dictionary uses a\n",
174+
"standardized set of UGRID attribute and variable names as keys, and the\n",
175+
"original variable names that come from the grid file as values.\n",
176+
"\n",
177+
"This allows us to use the same index into either dataset. However, this\n",
178+
"makes the indexing code much longer than the previous method."
179+
],
180+
"metadata": {
181+
"collapsed": false
182+
}
183+
},
184+
{
185+
"cell_type": "code",
186+
"execution_count": 24,
187+
"outputs": [],
188+
"source": [
189+
"var_names_dict = ugrid_01.ds_var_names\n",
190+
"x_1 = ugrid_01.ds[var_names_dict['Mesh2_node_x']]\n",
191+
"y_1 = ugrid_01.ds[var_names_dict['Mesh2_node_y']]\n",
192+
"face_nodes_1 = ugrid_01.ds[var_names_dict['Mesh2_face_nodes']]\n",
193+
"n_face_nodes_1 = ugrid_01.ds[var_names_dict['nMesh2_node']]\n",
194+
"\n",
195+
"var_names_dict = ugrid_02.ds_var_names\n",
196+
"x_2 = ugrid_02.ds[var_names_dict['Mesh2_node_x']]\n",
197+
"y_2 = ugrid_02.ds[var_names_dict['Mesh2_node_y']]\n",
198+
"face_nodes_2 = ugrid_02.ds[var_names_dict['Mesh2_face_nodes']]\n",
199+
"n_face_nodes_2 = ugrid_02.ds[var_names_dict['nMesh2_node']]"
200+
],
201+
"metadata": {
202+
"collapsed": false
203+
}
204+
},
205+
{
206+
"cell_type": "markdown",
207+
"source": [
208+
"Please note, for instance, we accessed the actual variable `mesh_node_x`\n",
209+
"of `ugrid_02` via indexing the dictionary with the standardized name\n",
210+
"`Mesh2_node_x`, likewise in `ugrid_01`."
211+
],
212+
"metadata": {
213+
"collapsed": false
214+
}
215+
},
216+
{
217+
"cell_type": "markdown",
218+
"source": [
219+
"## 3. UXarray's Standardized UGRID Names\n",
220+
"The last way of accessing grid topology attributes and variables is to use\n",
221+
"the standardized UGRID namings provided by UXarray. This method still\n",
222+
"utilizes the dictionary, `ds_var_names`, under the hood to return a\n",
223+
"reference to the variable or attribute that is stored withing\n",
224+
"`UXarray.Grid.ds`.\n",
225+
"\n",
226+
"This eliminates the need to remember the original variable names and\n",
227+
"needing to index through the `ds_var_names` dictionary. Because of this,\n",
228+
"we find this as the most convenient approach."
229+
],
230+
"metadata": {
231+
"collapsed": false
232+
}
233+
},
234+
{
235+
"cell_type": "code",
236+
"execution_count": 22,
237+
"outputs": [],
238+
"source": [
239+
"x_1 = ugrid_01.Mesh2_node_x\n",
240+
"y_1 = ugrid_01.Mesh2_node_y\n",
241+
"face_nodes_1 = ugrid_01.Mesh2_face_nodes\n",
242+
"n_face_nodes_1 = ugrid_01.nMesh2_node\n",
243+
"\n",
244+
"x_2 = ugrid_02.Mesh2_node_x\n",
245+
"y_2 = ugrid_02.Mesh2_node_y\n",
246+
"face_nodes_2 = ugrid_02.Mesh2_face_nodes\n",
247+
"n_face_nodes_2 = ugrid_02.nMesh2_node"
248+
],
249+
"metadata": {
250+
"collapsed": false
251+
}
252+
},
253+
{
254+
"cell_type": "markdown",
255+
"source": [
256+
"In conclusion, there are three ways of accessing the grid attributes and\n",
257+
"variables. Even though the UXarray developers recommend using the\n",
258+
"standardized UGRID names method, users can find each various pros/cons with\n",
259+
"each of these access ways."
260+
],
261+
"metadata": {
262+
"collapsed": false
263+
}
264+
}
265+
],
266+
"metadata": {
267+
"kernelspec": {
268+
"display_name": "Python 3",
269+
"language": "python",
270+
"name": "python3"
271+
},
272+
"language_info": {
273+
"codemirror_mode": {
274+
"name": "ipython",
275+
"version": 2
276+
},
277+
"file_extension": ".py",
278+
"mimetype": "text/x-python",
279+
"name": "python",
280+
"nbconvert_exporter": "python",
281+
"pygments_lexer": "ipython2",
282+
"version": "2.7.6"
283+
}
284+
},
285+
"nbformat": 4,
286+
"nbformat_minor": 0
287+
}

0 commit comments

Comments
 (0)