Merge pull request #24 from AquaticEcoDynamics/next-release

Merge for 0.4.0
AquaticEcoDynamics · Jan 17, 2025 · 7d62858 · 7d62858
2 parents f75e5ca + c206ab6
commit 7d62858
Show file tree

Hide file tree

Showing 20 changed files with 583 additions and 1,007 deletions.
diff --git a/.github/workflows/test-glmpy.yml b/.github/workflows/test-glmpy.yml
@@ -16,6 +16,8 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Install system dependencies
+      run: sudo apt-get install libjpeg-dev
     - name: Install dependencies
       run: |
         python -m pip install pip --upgrade

diff --git a/docs/blog/index.md b/docs/blog/index.md
@@ -1 +1,2 @@
-## Latest Posts
+# Blog
+
diff --git a/docs/blog/posts/glmpy-v0_1_3.md b/docs/blog/posts/glmpy-v0_1_3.md
diff --git a/docs/blog/posts/glmpy-v0_2_0.md b/docs/blog/posts/glmpy-v0_2_0.md
diff --git a/docs/blog/posts/glmpy-v0_3_1.md b/docs/blog/posts/glmpy-v0_3_1.md
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -43,5 +43,5 @@ actively developed.
 - An `aed_nml` sub-module for the `nml` module that mirrors the functionality
 of the `glm_nml` sub-module. 
 - Parameter documentation for the `glm_nml` sub-module.
-- Additional simple morphometries the `dimensions` module.
+- Additional simple morphometries in the `dimensions` module.
 
diff --git a/docs/how_to/how-to-nml.md b/docs/how_to/how-to-nml.md
@@ -186,24 +186,19 @@ custom_nml = {
     "custom_block2": {
         "param1": [1, 2, 3],
         "param2": ["foo", "bar", "baz"],
-        "param3": [
-            [True, False, True], 
-            [True, False, True], 
-            [True, False, True]
-        ]
+        "param3": [True, False, True]
     }
 }
 ```
 
 This is your NML file in Python syntax. Be mindful of the Python data types you
 use for your parameter values. They map to the respective syntax of data types
 in a NML file. Python integers will be converted to NML integers, floats to 
-floats, etc. Notice too the use of Python lists for NML comma-separated lists
-and nested Python lists for NML arrays. 
+floats, etc. Notice too the use of Python lists for NML comma-separated lists.
 
 !!! note
 
-    For lists and arrays, don't mix and match your Python data types - 
+    For lists, don't mix and match your Python data types - 
     especially integers and floats. 
 
 
@@ -242,11 +237,7 @@ custom_nml = {
     "custom_block2": {
         "param1": [1, 2, 3],
         "param2": ["foo", "bar", "baz"],
-        "param3": [
-            [True, False, True], 
-            [True, False, True], 
-            [True, False, True]
-        ]
+        "param3": [True, False, True]
     }
 }
 ```
@@ -268,15 +259,15 @@ methods:
         "param2": lambda x: nml.NMLWriter.write_nml_list(
             x, nml.NMLWriter.write_nml_str
         ),
-        "param3": lambda x: nml.NMLWriter.write_nml_array(
+        "param3": lambda x: nml.NMLWriter.write_nml_list(
             x, nml.NMLWriter.write_nml_bool
         )
     }
 }
 ```
-What are `write_nml_str`, `write_nml_bool`, `write_nml_list`, and
-`write_nml_array`? These are static methods that you can call independently 
-of initialising `NMLWriter` to convert Python syntax to NML syntax:
+What are `write_nml_str`, `write_nml_bool`, and `write_nml_list`? These are 
+static methods that you can call independently of initialising `NMLWriter` to 
+convert Python syntax to NML syntax:
 
 ```python
 nml_string = nml.NMLWriter.write_nml_str("GLM")
@@ -299,31 +290,11 @@ print(nml_list)
 ```
 1,2,3
 ```
-```python
-nml_array = nml.NMLWriter.write_nml_array(
-    [
-        [1.1, 1.2, 1.3, 1.2, 1.3],
-        [2.1, 2.2, 2.3, 1.2, 1.3],
-        [3.1, 3.2, 3.3, 1.2, 1.3],
-        [4.1, 4.2, 4.3, 1.2, 1.3],
-        [5.1, 5.2, 5.3, 1.2, 1.3],
-        [6.1, 6.2, 6.3, 1.2, 1.3]
-    ]
-)
-print(nml_array)
-```
-```
-1.1,1.2,1.3,1.2,1.3,
-2.1,2.2,2.3,1.2,1.3,
-3.1,3.2,3.3,1.2,1.3,
-4.1,4.2,4.3,1.2,1.3,
-5.1,5.2,5.3,1.2,1.3,
-6.1,6.2,6.3,1.2,1.3
-```
+
 !!! note
     No static methods are required for converting integers and floats. 
 
-    When writing lists/arrays with string or boolean elements, lambda functions 
+    When writing lists with string or boolean elements, lambda functions 
     can used create new combinations of these methods.
 
 By creating a nested dictionary in the same fashion as shown above, you can 
@@ -384,7 +355,6 @@ my_nml.set_converters(custom_converters)
 my_nml.write_nml(nml_file="custom_nml.nml")
 ```
 
-
 ### Reading a NML file with `NMLReader`
 
 glm-py makes it easy to run simulations from pre-existing NML files with the 
@@ -586,20 +556,6 @@ print(type(python_list))
 <class 'list'>
 ```
 
-```python
-nml_array = ['1.1,1.2,1.3', '2.1,2.2,2.3', '2.1,2.2,2.3']
-python_array = nml.NMLReader.read_nml_array(
-    nml_array,
-    nml.NMLReader.read_nml_float
-)
-print(python_array)
-print(type(python_array))
-```
-```
-[[1.1, 1.2, 1.3], [2.1, 2.2, 2.3], [2.1, 2.2, 2.3]]
-<class 'list'>
-```
-
 To read the tracer block, we need to create a nested dictionary that tells
 `NMLReader` which static methods to use:
 

diff --git a/docs/installation.md b/docs/installation.md
@@ -33,6 +33,7 @@ The following table lists the GLM version that is bundled with the built distrib
 
 | glm-py version | GLM version     |
 | -------------- | -----------     |
+| `0.4.*`        | `3.3.1a12 `     |
 | `0.3.*`        | `3.3.1a12 `     |
 | `0.2.*`        | `3.3.1a12 `     |
 | `0.1.*`        | `3.3.1a12 `     |
diff --git a/docs/release_notes/index.md b/docs/release_notes/index.md
@@ -0,0 +1,56 @@
+# Release Notes
+
+## glm-py
+
+### 0.4.0 <small>(17 January, 2025)</small> { id="0.4.0" }
+
+- Added `restart_variables` to `InitProfilesBlock`, 
+`NMLReader._default_converters`, and `NMLWriter._default_converters`
+- Added `subm_elev` to `InflowBlock`, 
+`NMLReader._default_converters`, and `NMLWriter._default_converters`
+- Added `list_len` parameter to `NMLWriter.write_nml_list` which inserts line 
+breaks to the comma-separated output after a specified number of items. 
+`list_len` parameter also added to `NMLWriter` and `GLMNML`.
+- Removed `NMLWriter.write_nml_array` and `NMLReader.read_nml_array`. Usage 
+replaced in `glm_nml` and `nml` modules with 
+`NMLWriter.write_nml_list`/`NMLReader.read_nml_list`
+
+### 0.3.1 <small>(13 December, 2024)</small> { id="0.3.1" }
+
+- Added a `plots` module for visualising GLM's output files with Matplotlib
+  - `LakePlotter` class for plotting the `lake.csv` file
+  - `NCProfile` class for plotting a timeseries profile of variables in the 
+    `output.nc` file
+  - `matplotlib` and `netcdf4` dependencies added
+  - Added a how-to documentation page for the `plots` module
+- Added a `example_sims.sparkling` sub-module for running the Sparkling Lake
+simulation
+  - `load_nml` function for returning a dictionary of the Sparkling NML
+  - `load_bcs` function for returning a pandas dataframe of the boundary 
+  condition data
+  - `run_sim` function for running the Sparkling simulation
+- Added `InvertedTruncatedPyramid` class to the `dimensions` module
+  - Deprecation warning added to `InvertedTruncatedSquarePyramid`
+
+### 0.2.0 <small>(24 June, 2024)</small> { id="0.2.0" }
+
+- The `nml` module has been split into `nml` and `glm_nml` sub-modules.
+- The `glm_nml` sub-module provides high-level NML tools and implements all the 
+existing classes from the `nml` module in `0.1.3`.
+  - Classes from `0.1.3` are automatically imported using 
+  `from glmpy import nml` to maintain backwards compatibility until `1.0.0`.
+  - Class names from `0.1.3` will be deprecated by `1.0.0` in favour of a new 
+  naming convention that ensures forwards compatibility with AED. Warnings are 
+  raised to encourage you to migrate to the new class names.
+- The new `nml` sub-module provides low-level tools for reading and writing any
+NML file (GLM or AED).
+  - `NMLWriter` converts a nested Python dictionary to an NML file. 
+  - `NMLReader` converts an NML file to a nested Python dictionary. 
+  - Both classes provide functionality to explicitly control how each parameter
+  is read/written to file.
+- `InvertedTruncatedCone` class added to the `dimensions` module to calculate
+morphometry parameters for simple circular water bodies.
+
+### 0.1.3 <small>(22 March, 2024)</small> { id="0.1.3" }
+
+- glm-py released! 🚀
diff --git a/docs/blog/authors.yml → docs/tutorials/authors.yml b/docs/blog/authors.yml → docs/tutorials/authors.yml
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -0,0 +1 @@
+# Tutorials
diff --git a/docs/blog/posts/sparkling-lake-tutorial.md → ...utorials/posts/tutorial-sparkling-lake.md b/docs/blog/posts/sparkling-lake-tutorial.md → ...utorials/posts/tutorial-sparkling-lake.md
diff --git a/glmpy/data/sparkling_sim/glm3.json b/glmpy/data/sparkling_sim/glm3.json
@@ -127,48 +127,36 @@
    "OGM_poc"
   ],
   "wq_init_vals": [
-   [
     1.1,
     1.2,
     1.3,
     1.2,
-    1.3
-   ],
-   [
+    1.3,
     2.1,
     2.2,
     2.3,
     1.2,
-    1.3
-   ],
-   [
+    1.3,
     3.1,
     3.2,
     3.3,
     1.2,
-    1.3
-   ],
-   [
+    1.3,
     4.1,
     4.2,
     4.3,
     1.2,
-    1.3
-   ],
-   [
+    1.3,
     5.1,
     5.2,
     5.3,
     1.2,
-    1.3
-   ],
-   [
+    1.3,
     6.1,
     6.2,
     6.3,
     1.2,
     1.3
-   ]
   ]
  },
  "meteorology": {
-Original file line number
+Diff line change
@@ Expand Up / @@ -127,48 +127,36 @@ @@
        "OGM_poc"
       ],
       "wq_init_vals": [
-       [
 .1,
 .2,
 .3,
 .2,
-.3
-       ],
-       [
+.3,
 .1,
 .2,
 .3,
 .2,
-.3
-       ],
-       [
+.3,
 .1,
 .2,
 .3,
 .2,
-.3
-       ],
-       [
+.3,
 .1,
 .2,
 .3,
 .2,
-.3
-       ],
-       [
+.3,
 .1,
 .2,
 .3,
 .2,
-.3
-       ],
-       [
+.3,
 .1,
 .2,
 .3,
 .2,
 .3
-       ]
       ]
      },
      "meteorology": {
@@ Expand Down @@