Update examples + check repository health (#33)

mdpiper · web-flow · commit 040d0726377f · 2024-10-18T13:59:44.000-06:00
* Add directory README and launch notebook. * Touch up text and code in notebooks * Update ruff setting * Make pretty * Use Miniforge in place of Mambaforge Mambaforge is being retired: https://conda-forge.org/news/2024/07/29/sunsetting-mambaforge/. * Drop Python 3.9, add 3.13 * Also update Python version information in metadata * Use absolute path to working directory with bmi_tester
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -20,14 +20,13 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4
 
       - uses: conda-incubator/setup-miniconda@v3
         with:
-          miniforge-variant: Mambaforge
           miniforge-version: latest
           python-version: ${{ matrix.python-version }}
 
diff --git a/examples/README-bmi-example-python.ipynb b/examples/README-bmi-example-python.ipynb
@@ -0,0 +1,44 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Examples: Python BMI"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "Here are examples of using the *Heat* model and its Python *BMI*.\n",
+    "\n",
+    "* [run-model.ipynb](./run-model.ipynb) and [run-model-from-bmi.ipynb](./run-model-from-bmi.ipynb): These Jupyter Notebooks show how to interact with the *Heat* model through its API and its BMI, respectively.\n",
+    "* [heat.yaml](./heat.yaml): A configuration file used to pass parameters to the *Heat* BMI."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "CSDMS",
+   "language": "python",
+   "name": "csdms"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,6 @@
+# Examples: Python BMI
+
+Here are examples of using the *Heat* model and its Python BMI.
+
+* [run-model.ipynb](./run-model.ipynb) and [run-model-from-bmi.ipynb](./run-model-from-bmi.ipynb): These Jupyter Notebooks show how to interact with the *Heat* model through its API and its BMI, respectively.
+* [heat.yaml](./heat.yaml): A configuration file used to pass parameters to the *Heat* BMI.
diff --git a/examples/run-model-from-bmi.ipynb b/examples/run-model-from-bmi.ipynb
@@ -4,21 +4,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Run the `Heat` model through its BMI"
+    "# Run the *Heat* model through its BMI"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`Heat` models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the source code for the [model](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) and its [BMI](https://github.com/csdms/bmi-example-python/blob/master/heat/bmi_heat.py) on GitHub."
+    "*Heat* models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the source code for the [model](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) and its [BMI](https://github.com/csdms/bmi-example-python/blob/master/heat/bmi_heat.py) on GitHub."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Start by importing `os`, `numpy` and the `Heat` BMI:"
+    "Start by importing *numpy* and the *Heat* BMI:"
    ]
   },
   {
@@ -27,7 +27,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import os\n",
     "import numpy as np\n",
     "\n",
     "from heat import BmiHeat"
@@ -62,14 +61,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(x.get_component_name())"
+    "x.get_component_name()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Start the `Heat` model through its BMI using a configuration file:"
+    "Start the *Heat* model through its BMI using a configuration file:"
    ]
   },
   {
@@ -78,7 +77,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "cat heat.yaml"
+    "!cat heat.yaml"
    ]
   },
   {
@@ -193,8 +192,9 @@
    "outputs": [],
    "source": [
     "temperature = np.zeros(shape)\n",
-    "temperature[3, 4] = 100.0\n",
-    "x.set_value(\"plate_surface__temperature\", temperature)"
+    "temperature[tuple(shape//2)] = 100.0\n",
+    "temperature_flat = temperature.flatten()\n",
+    "x.set_value(\"plate_surface__temperature\", temperature_flat)"
    ]
   },
   {
@@ -268,7 +268,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "distant_time = 2.0\n",
+    "distant_time = 10 * x.get_time_step()\n",
     "while x.get_current_time() < distant_time:\n",
     "    x.update()"
    ]
diff --git a/examples/run-model.ipynb b/examples/run-model.ipynb
@@ -4,21 +4,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Run the `Heat` model"
+    "# Run the *Heat* model"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`Heat` models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the [source code](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) for the model on GitHub."
+    "*Heat* models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the [source code](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) for the model on GitHub."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Start by importing `numpy` and `Heat`:"
+    "Start by importing *numpy* and *Heat*:"
    ]
   },
   {
@@ -35,7 +35,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Create an instance of the model, setting `shape` and `alpha` parameters:"
+    "Create an instance of the model, setting the `shape` and `alpha` parameters:"
    ]
   },
   {
@@ -71,7 +71,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "What does the initial temperature field look like?"
+    "Zero out the initial temperature field:"
    ]
   },
   {
@@ -97,7 +97,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m.temperature[3, 4] = 100.0\n",
+    "m.temperature[n_rows//2, n_cols//2] = 100.0\n",
     "print(m.temperature)"
    ]
   },
@@ -153,7 +153,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "distant_time = 2.0\n",
+    "distant_time = 10 * m.time_step\n",
     "while m.time < distant_time:\n",
     "    m.advance_in_time()"
    ]
@@ -162,7 +162,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "View the new state of the temperature field (with help from `np.set_printoptions`):"
+    "View the new state of the temperature field (with help from *np.set_printoptions*):"
    ]
   },
   {
@@ -179,7 +179,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note that temperature is set to zero at the boundaries."
+    "Note that temperature is set to zero at the boundaries, so it's not conserved on the plate:"
    ]
   },
   {
diff --git a/heat/__init__.py b/heat/__init__.py
@@ -1,4 +1,5 @@
 """Model the diffusion of heat over a 2D plate."""
+
 from ._version import __version__
 from .bmi_heat import BmiHeat
 from .heat import Heat, solve_2d
diff --git a/heat/bmi_heat.py b/heat/bmi_heat.py
@@ -8,7 +8,6 @@
 
 
 class BmiHeat(Bmi):
-
     """Solve the heat equation for a 2D plate."""
 
     _name = "The 2D Heat Equation"
diff --git a/pyproject.toml b/pyproject.toml
@@ -26,14 +26,14 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Scientific/Engineering :: Physics",
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "numpy",
     "scipy",
@@ -93,7 +93,7 @@ line_length = 88
 
 [tool.ruff]
 line-length = 88
-ignore = [
+lint.ignore = [
 	"E203",
 	"E501",
 ]

Original file line number	Diff line number	Diff line change
`@@ -4,21 +4,21 @@`
`4`	`4`	`"cell_type": "markdown",`
`5`	`5`	`"metadata": {},`
`6`	`6`	`"source": [`
`7`		- "# Run the `Heat` model through its BMI"
	`7`	`+ "# Run the Heat model through its BMI"`
`8`	`8`	`]`
`9`	`9`	`},`
`10`	`10`	`{`
`11`	`11`	`"cell_type": "markdown",`
`12`	`12`	`"metadata": {},`
`13`	`13`	`"source": [`
`14`		- "`Heat` models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the source code for the [model](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) and its [BMI](https://github.com/csdms/bmi-example-python/blob/master/heat/bmi_heat.py) on GitHub."
	`14`	`+ "Heat models the diffusion of temperature on a uniform rectangular plate with Dirichlet boundary conditions. View the source code for the [model](https://github.com/csdms/bmi-example-python/blob/master/heat/heat.py) and its [BMI](https://github.com/csdms/bmi-example-python/blob/master/heat/bmi_heat.py) on GitHub."`
`15`	`15`	`]`
`16`	`16`	`},`
`17`	`17`	`{`
`18`	`18`	`"cell_type": "markdown",`
`19`	`19`	`"metadata": {},`
`20`	`20`	`"source": [`
`21`		- "Start by importing `os`, `numpy` and the `Heat` BMI:"
	`21`	`+ "Start by importing numpy and the Heat BMI:"`
`22`	`22`	`]`
`23`	`23`	`},`
`24`	`24`	`{`
`@@ -27,7 +27,6 @@`
`27`	`27`	`"metadata": {},`
`28`	`28`	`"outputs": [],`
`29`	`29`	`"source": [`
`30`		`- "import os\n",`
`31`	`30`	`"import numpy as np\n",`
`32`	`31`	`"\n",`
`33`	`32`	`"from heat import BmiHeat"`
`@@ -62,14 +61,14 @@`
`62`	`61`	`"metadata": {},`
`63`	`62`	`"outputs": [],`
`64`	`63`	`"source": [`
`65`		`- "print(x.get_component_name())"`
	`64`	`+ "x.get_component_name()"`
`66`	`65`	`]`
`67`	`66`	`},`
`68`	`67`	`{`
`69`	`68`	`"cell_type": "markdown",`
`70`	`69`	`"metadata": {},`
`71`	`70`	`"source": [`
`72`		- "Start the `Heat` model through its BMI using a configuration file:"
	`71`	`+ "Start the Heat model through its BMI using a configuration file:"`
`73`	`72`	`]`
`74`	`73`	`},`
`75`	`74`	`{`
`@@ -78,7 +77,7 @@`
`78`	`77`	`"metadata": {},`
`79`	`78`	`"outputs": [],`
`80`	`79`	`"source": [`
`81`		`- "cat heat.yaml"`
	`80`	`+ "!cat heat.yaml"`
`82`	`81`	`]`
`83`	`82`	`},`
`84`	`83`	`{`
`@@ -193,8 +192,9 @@`
`193`	`192`	`"outputs": [],`
`194`	`193`	`"source": [`
`195`	`194`	`"temperature = np.zeros(shape)\n",`
`196`		`- "temperature[3, 4] = 100.0\n",`
`197`		`- "x.set_value(\"plate_surface__temperature\", temperature)"`
	`195`	`+ "temperature[tuple(shape//2)] = 100.0\n",`
	`196`	`+ "temperature_flat = temperature.flatten()\n",`
	`197`	`+ "x.set_value(\"plate_surface__temperature\", temperature_flat)"`
`198`	`198`	`]`
`199`	`199`	`},`
`200`	`200`	`{`
`@@ -268,7 +268,7 @@`
`268`	`268`	`"metadata": {},`
`269`	`269`	`"outputs": [],`
`270`	`270`	`"source": [`
`271`		`- "distant_time = 2.0\n",`
	`271`	`+ "distant_time = 10 * x.get_time_step()\n",`
`272`	`272`	`"while x.get_current_time() < distant_time:\n",`
`273`	`273`	`" x.update()"`
`274`	`274`	`]`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`"""Model the diffusion of heat over a 2D plate."""`
	`2`	`+`
`2`	`3`	`from ._version import __version__`
`3`	`4`	`from .bmi_heat import BmiHeat`
`4`	`5`	`from .heat import Heat, solve_2d`