Tools: Make suntools an installable library

.github/workflows/ci.yml

@@ -92,8 +92,8 @@ jobs:
           fi
 
           # Check for changes to trigger documentation build checks
-          # Updates in doc, bindings/sundials4py, or tools directories
-          if echo "$CHANGED" | grep -qE '^(doc/|bindings/sundials4py/|tools/)'; then
+          # Updates in doc, bindings/sundials4py, or suntools directories
+          if echo "$CHANGED" | grep -qE '^(doc/|bindings/sundials4py/|suntools/)'; then
             echo "docs=true" >> "$GITHUB_OUTPUT"
           else
             echo "docs=false" >> "$GITHUB_OUTPUT"

.gitignore

@@ -85,9 +85,6 @@ uberenv_libs
 # swig
 /swig/swig
 
-# tools
-/tools/suntools/__pycache__
-
 # python
 .pytest_cache
 __pycache__

doc/arkode/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/arkode/guide/source/Usage/ARKStep/User_callable.rst

@@ -3095,7 +3095,7 @@ Main solver optional output functions
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/arkode/guide/source/Usage/ERKStep/User_callable.rst

@@ -1668,7 +1668,7 @@ Main solver optional output functions
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/arkode/guide/source/Usage/MRIStep/User_callable.rst

@@ -1732,7 +1732,7 @@ Main solver optional output functions
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/arkode/guide/source/Usage/SPRKStep/User_callable.rst

@@ -749,7 +749,7 @@ Main solver optional output functions
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/arkode/guide/source/Usage/User_callable.rst

@@ -4275,7 +4275,7 @@ Current stage index, and total number of stages        :c:func:`ARKodeGetStageIn
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/arkode/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstrings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/cvode/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/cvode/guide/source/Usage/index.rst

@@ -3026,7 +3026,7 @@ described next.
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/cvode/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/cvodes/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/cvodes/guide/source/Usage/SIM.rst

@@ -3021,7 +3021,7 @@ described next.
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/cvodes/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/ida/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/ida/guide/source/Usage/index.rst

@@ -2842,7 +2842,7 @@ described next.
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/ida/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/idas/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/idas/guide/source/Usage/SIM.rst

@@ -2867,7 +2867,7 @@ described next.
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/idas/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/kinsol/examples/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration -----------------------------------------------------
 

doc/kinsol/guide/source/Usage/index.rst

@@ -1667,7 +1667,7 @@ functions are described next.
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/kinsol/guide/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../../shared")))
 
-# Add suntools directory to import python function docstings with autodoc
-sys.path.append(os.path.abspath("../../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

doc/shared/sundials/Types.rst

@@ -169,7 +169,7 @@ Output formatting type
 
    .. note::
 
-      The Python module ``tools/suntools`` provides utilities to read and output
+      The Python package ``suntools`` provides utilities to read and output
       the data from a SUNDIALS CSV output file using the key and value pair
       format.
 

doc/superbuild/source/conf.py

@@ -20,8 +20,8 @@
 
 sys.path.append(os.path.dirname(os.path.abspath("../../shared")))
 
-# Add suntools directory to import python function docstrings with autodoc
-sys.path.append(os.path.abspath("../../../tools/suntools"))
+# Add the suntools package source parent for autodoc imports.
+sys.path.append(os.path.abspath("../../../suntools/src/suntools"))
 
 # -- General configuration ----------------------------------------------------
 

pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
 ]
 dependencies = [
     "nanobind >= 2.9.2",
-    "numpy >= 2.0.0",
+    "numpy >= 2.0.0"
 ]
 
 [project.optional-dependencies]

scripts/shared.sh

@@ -92,5 +92,5 @@ $tar $tarfile $distrobase/test/unit_tests/
 echo "   --- Add external files to $tarfile"
 $tar $tarfile $distrobase/external/
 
-echo "   --- Add tools to $tarfile"
-$tar $tarfile $distrobase/tools/
+echo "   --- Add suntools to $tarfile"
+$tar $tarfile $distrobase/suntools/

scripts/tarscript.sh

@@ -210,7 +210,7 @@ mkdir $tmpdir/examples
 mkdir $tmpdir/include
 mkdir $tmpdir/src
 mkdir $tmpdir/test
-mkdir $tmpdir/tools
+mkdir $tmpdir/suntools
 
 #----------------------------------
 # Copy appropriate files in $tmpdir
@@ -258,7 +258,7 @@ cp -r $sundialsdir/src/sundomeigest $tmpdir/src/
 cp    $sundialsdir/test/testRunner $tmpdir/test/
 cp -r $sundialsdir/test/unit_tests $tmpdir/test/
 
-cp -r $sundialsdir/tools $tmpdir/
+cp -r $sundialsdir/suntools $tmpdir/
 
 # Clean up tmpdir
 rm -rf $tmpdir/doc/shared/__pycache__
@@ -269,7 +269,7 @@ find $tmpdir -name ".DS_Store" -delete
 
 # Remove ignored or untracked files that may have been added
 cd $sundialsdir
-for f in $(git ls-files --others --directory benchmarks cmake doc examples external include src test tools); do
+for f in $(git ls-files --others --directory benchmarks cmake doc examples external include src test suntools); do
     rm -rf $tmpdir/$f
 done
 cd -

suntools/README.md

@@ -0,0 +1,20 @@
+# suntools (SUNDIALS)
+
+This directory contains the `suntools` Python package which provides utilities for
+
+- parsing SUNDIALS log files
+- more to come...
+
+## Install
+
+From this directory:
+
+```bash
+python -m pip install -e .
+```
+
+Then import as:
+
+```python
+import suntools
+```

suntools/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "suntools"
+version = "7.7.0"
+description = "Utilities designed to assist users of the SUNDIALS suite of nonlinear and differential/algebraic equation solvers."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSD-3-Clause" }
+authors = [
+  { name = "SUNDIALS Developers", email = "sundials-users@llnl.gov" }
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: BSD License",
+  "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://computing.llnl.gov/projects/sundials"
+Documentation = "https://sundials.readthedocs.io/"
+Source = "https://github.com/LLNL/sundials"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/suntools"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src/suntools",
+  "/examples",
+  "/README.md",
+  "/pyproject.toml",
+]

test/unit_tests/suntools/CMakeLists.txt

@@ -15,8 +15,8 @@
 # SUNDIALS Copyright End
 # ---------------------------------------------------------------
 
-# Locate suntools module
-set(SUNTOOLS_DIR "${CMAKE_SOURCE_DIR}/tools/suntools")
+# Locate suntools module source directory.
+set(SUNTOOLS_DIR "${CMAKE_SOURCE_DIR}/suntools/src/suntools")
 
 if(NOT EXISTS "${SUNTOOLS_DIR}/logs.py")
   message(WARNING "Skipped suntools log parser tests (logs.py not found)")