Update examples + check repository health (#33)

* 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

Author: mdpiper

.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 }}
 

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
+}

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.

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()"
    ]

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:"
    ]
   },
   {

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

heat/bmi_heat.py

@@ -8,7 +8,6 @@
 
 
 class BmiHeat(Bmi):
-
     """Solve the heat equation for a 2D plate."""
 
     _name = "The 2D Heat Equation"

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",
 ]