USEPA · kaklise · Mar 23, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/.github/workflows/build_deploy_pages.yml b/.github/workflows/build_deploy_pages.yml
@@ -25,8 +25,7 @@ jobs:
           python-version: '3.11'
       - name: Install package
         run: |
-          pip install -e .
-          pip install -r requirements.txt
+          pip install -e .[optional,doc]
       - name: Build documentation
         run: sphinx-build documentation/ documentation/_build/html
       - name: Upload artifact

diff --git a/.github/workflows/build_tests.yml b/.github/workflows/build_tests.yml
@@ -136,7 +136,7 @@ jobs:
         brew reinstall libomp
     - name: Test wntr
       run: |
-        pip install -r requirements.txt
+        pip install --find-links=. --pre "wntr[optional,test]"
         pytest wntr/tests/ --ignore=wntr/tests/test_demos.py --ignore=wntr/tests/test_examples.py
 
   run_coverage:
@@ -163,16 +163,16 @@ jobs:
       run: |
         python --version
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        python -m pip install -e .
+        python -m pip install -e .[optional,test]
     - name: Run Tests
       if: ${{ matrix.os != 'macos-latest' }}
-      run: | 
-        coverage erase
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest  --doctest-modules --doctest-glob="*.rst" wntr
-        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" documentation
       env:
+        OMIT: "'*/tests/*','*/extensions/*','*/sim/network_isolation/network_isolation.py','*/sim/aml/evaluator.py'"
         COVERAGE_FILE: .coverage.${{ matrix.python-version }}.${{ matrix.os }}
+      run: | 
+        coverage erase
+        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit=$OMIT -m pytest -m "not extensions" --ignore=wntr/extensions --doctest-modules --doctest-glob="*.rst" wntr
+        coverage run --context=${{ matrix.os }}.py${{ matrix.python-version }} --source=wntr --omit=$OMIT --append -m pytest --doctest-glob="*.rst" --ignore-glob="*/extensions/*.rst" documentation
     - name: Run Tests (ARM-processor)
       if: ${{ matrix.os == 'macos-latest'}}
       # doctests are not flexible enough to skip EPANET=v2.0 errors on ARM processor, so do not run doctests on ARM system
@@ -200,8 +200,7 @@ jobs:
     - name: Install coverage
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        python -m pip install -e .
+        python -m pip install -e .[optional,test]
         pip install coveralls
     - name: Download coverage artifacts from test matrix
       uses: actions/download-artifact@v4

diff --git a/.github/workflows/extensions.yml b/.github/workflows/extensions.yml
@@ -0,0 +1,36 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: extensions
+
+on:
+  push:
+    branches: 
+    - '**'
+  pull_request:
+    branches:
+    - '**'
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+      fail-fast: false
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install packages
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[optional,test]
+    - name: Run tests and coverage (unittests plus doctests)
+      run: |
+        coverage run --source=wntr --include="*/extensions/*" -m pytest -m extensions --doctest-modules wntr
+        coverage run --source=wntr --include="*/extensions/*" --append -m pytest --doctest-glob="extensions/*.rst" documentation        
+        # coverage report --fail-under=70        
+
diff --git a/.github/workflows/quick_check.yml b/.github/workflows/quick_check.yml
@@ -27,15 +27,13 @@ jobs:
     - name: Install packages
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
-        pip install --upgrade coverage pytest
-    - name: Install package for development
-      run: |
-        python -m pip install -e .
+        pip install -e .[optional,test]
     - name: Run tests and coverage (unittests plus doctests)
+      env:
+        OMIT: "'*/tests/*','*/extensions/*','*/sim/network_isolation/network_isolation.py','*/sim/aml/evaluator.py'"
       run: |
-        coverage run --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" -m pytest -m "not time_consuming" --doctest-modules --doctest-glob="*.rst" wntr
-        coverage run --source=wntr --omit="*/tests/*","*/sim/network_isolation/network_isolation.py","*/sim/aml/evaluator.py" --append -m pytest --doctest-glob="*.rst" documentation        
+        coverage run --source=wntr --omit=$OMIT -m pytest -m "not time_consuming and not extensions" --ignore=wntr/extensions --doctest-modules --doctest-glob="*.rst" wntr
+        coverage run --source=wntr --omit=$OMIT --append -m pytest --doctest-glob="*.rst" --ignore-glob="*/extensions/*.rst" documentation        
         coverage report --fail-under=70        
     # coverage run --source=wntr --omit="*/tests/*" --append -m pytest --doctest-glob="*.rst" documentation 
 
diff --git a/documentation/developers.rst b/documentation/developers.rst
@@ -93,6 +93,8 @@ Bug reports and feature requests
 Bug reports and feature requests can be submitted to https://github.com/USEPA/WNTR/issues.  
 The core development team will prioritize and assign bug reports and feature requests to team members.
 
+.. _contributing:
+
 Contributing
 ---------------------
 Software developers, within the core development team and external collaborators, 
@@ -101,6 +103,8 @@ Software developers interested in contributing to the project are encouraged to
 create a `Fork` of the project and submit a `Pull Request` using GitHub.  
 Pull requests will be reviewed by the core development team.  
 
+Pull requests
+^^^^^^^^^^^^^
 Pull requests can be made to the **main** or **dev** (development) branch.  
 Developers can discuss new features and the appropriate branch for contributing 
 by opening a new issue on https://github.com/USEPA/WNTR/issues.  
@@ -115,6 +119,35 @@ Pull requests must meet the following minimum requirements to be included in WNT
 
 * Network model files will not be duplicated in the repository.  Network files are stored in examples/network and wntr/tests/networks_for_testing only.
 
+Extensions
+^^^^^^^^^^
+WNTR extensions are intended to house beta and self-contained functionality that adds to WNTR. 
+Developers interested in contributing to WNTR extensions should communicate with the core development team
+through https://github.com/USEPA/WNTR/issues prior to submitting a pull request. 
+See :ref:`extensions` for a list of current WNTR extensions.
+
+Extensions adhere to the following file structure:
+
+* **Source code**: Source code files (*.py) associated with the extension, with the exception of documentation and testing, 
+  reside in a folder named ``wntr\extensions\<extension_name>``.  The folder contains an ``__int__.py`` file to import the extension.
+* **Documentation**: Documentation resides in a file named ``documentation\extensions\<extension_name>.rst``. 
+  The documentation page should include 
+  1) a high level summary of the extension, 
+  2) a point of contact (developer name and GitHub username), and 
+  3) supporting documentation and examples (using doctest). 
+  A link to the documentation should also be added to ``documentation\extensions.rst`` and ``documentation\userguide.rst``.
+* **Testing**: Tests are run using the `extensions workflow <https://github.com/USEPA/WNTR/tree/main/.github/workflows/extensions.yml>`_.
+  Tests reside in a file named ``wntr\tests\extensions\test_<extension_name>.py``. 
+  Tests should be marked ``@pytest.mark.extensions``.
+* **Requirements**: If the extension requires packages beyond WNTR's core dependencies, add a corresponding entry to 
+  ``extras_require`` in ``setup.py``. Users can then install the extension's dependencies with ``pip install wntr[<extension_name>]``.
+
+.. note:: 
+   While documentation is required for extensions, the documentation is not included in the 
+   `WNTR EPA Report <https://cfpub.epa.gov/si/si_public_record_report.cfm?Lab=NHSRC&dirEntryID=337793>`_.  
+   Documentation for extensions is only available online. 
+   Extensions that have long-term test failures will be removed from the repository.
+
 Software release
 ------------------
 The software release process requires administrative privileges and knowledge about the external services used in the release process.

diff --git a/documentation/extensions.rst b/documentation/extensions.rst
@@ -0,0 +1,38 @@
+.. raw:: latex
+
+    \clearpage
+
+.. _extensions:
+
+Extensions
+==========
+|extensions|
+
+.. |extensions| image:: https://github.com/USEPA/WNTR/actions/workflows/extensions.yml/badge.svg
+   :target: https://github.com/USEPA/WNTR/actions/workflows/extensions.yml
+
+WNTR extensions are intended to house beta and self-contained functionality that adds to WNTR, 
+but is currently not part of core WNTR development.  The extensions should be designed for a wide audience.
+
+WNTR currently includes the following extension:
+
+- :ref:`hello_world`
+
+Additional extensions will be added at a later date.
+
+.. note:: 
+   Developers interested in contributing to WNTR extensions should communicate with the core development team
+   through https://github.com/USEPA/WNTR/issues prior to submitting a pull request.
+   See :ref:`contributing` for more information.
+
+   While documentation is required for extensions, the documentation is not included in the 
+   `WNTR EPA Report <https://cfpub.epa.gov/si/si_public_record_report.cfm?Lab=NHSRC&dirEntryID=337793>`_.  
+   Documentation for extensions is only available online. 
+   Extensions that have long term test failures will be removed from the repository.
+
+Third-party packages
+---------------------
+Developers are also encouraged to create third-party software packages that extends functionality in WNTR.  
+A list of software packages that build on WNTR is included below:
+
+.. include:: third_party_software.rst
diff --git a/documentation/extensions/hello_world.rst b/documentation/extensions/hello_world.rst
@@ -0,0 +1,28 @@
+
+.. role:: red
+
+.. raw:: latex
+
+    \clearpage
+
+.. _hello_world:
+
+Hello World
+===========================================
+
+**Summary**: "hello_world" is a WNTR extension that demonstrates the file structure of a simple extension. 
+See :ref:`contributing` for more information on creating an extension.
+
+**Point of contact**: Katherine Klise, https://github.com/kaklise
+
+-----
+
+The Hello World extension contains a single function that returns "Hello World!".
+
+.. doctest::
+
+    >>> import wntr.extensions.hello_world as hello_world
+
+    >>> output = hello_world.example_module.example_function()
+    >>> print(output)
+    Hello World!
diff --git a/documentation/index_latex.rst b/documentation/index_latex.rst
@@ -35,6 +35,7 @@ WNTR documentation
    graphics
    gis
    advancedsim
+   extensions
    license
    users	   
    developers

diff --git a/documentation/third_party_software.rst b/documentation/third_party_software.rst
@@ -0,0 +1,25 @@
+* CriticalityMaps: https://github.com/pshassett/CriticalityMaps
+
+* Digital HydrAuLic SIMulator (DHALSIM): https://github.com/Critical-Infrastructure-Systems-Lab/DHALSIM
+
+* InfraRisk: https://github.com/srijithbalakrishnan/dreaminsg-integrated-model
+
+* LeakDB: https://github.com/KIOS-Research/LeakDB
+
+* MAGNets: https://github.com/meghnathomas/MAGNets
+
+* MILPNet: https://github.com/meghnathomas/MILPNet
+
+* PPMTools: https://github.com/USEPA/PPMtools
+
+* PTSNet: https://github.com/gandresr/ptsnet
+
+* TSNet: https://github.com/glorialulu/TSNet
+
+* VisWaterNet: https://github.com/tylertrimble/viswaternet
+
+* wntr-qgis: https://github.com/angusmcb/wntr-qgis
+
+* wntr-quantum: https://github.com/QuantumApplicationLab/wntr-quantum
+
+See the `WNTR GitHub Dependeny Graph <https://github.com/USEPA/WNTR/network/dependents?dependent_type=REPOSITORY>`_ to find additional repositories and packages that use WNTR.
diff --git a/documentation/userguide.rst b/documentation/userguide.rst
@@ -72,6 +72,14 @@ U.S. Department of Energy's National Nuclear Security Administration under contr
    graphics
    gis
    advancedsim
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Extensions
+
+   extensions
+   extensions/hello_world
 
 .. toctree::
     :maxdepth: 1

diff --git a/documentation/users.rst b/documentation/users.rst
@@ -12,28 +12,10 @@ If users have related software or a publication that they would like
 to add to this page, please email the contacts listed on the WNTR GitHub webpage (https://github.com/USEPA/WNTR) 
 or submit a pull request with the update.
 
-Related software
------------------
+Third-party packages
+---------------------
 
-* CriticalityMaps: https://github.com/pshassett/CriticalityMaps
-
-* Digital HydrAuLic SIMulator (DHALSIM): https://github.com/Critical-Infrastructure-Systems-Lab/DHALSIM
-
-* LeakDB: https://github.com/KIOS-Research/LeakDB
-
-* MAGNets: https://github.com/meghnathomas/MAGNets
-
-* MILPNet: https://github.com/meghnathomas/MILPNet
-
-* PPMTools: https://github.com/USEPA/PPMtools
-
-* PTSNet: https://github.com/gandresr/ptsnet
-
-* TSNet: https://github.com/glorialulu/TSNet
-
-* VisWaterNet: https://github.com/tylertrimble/viswaternet
-
-See the `WNTR GitHub Dependeny Graph <https://github.com/USEPA/WNTR/network/dependents?dependent_type=REPOSITORY>`_ to find additional repositories and packages that use WNTR.
+.. include:: third_party_software.rst
 
 Publications
 ------------
@@ -114,5 +96,5 @@ Publications
 
 .. bibliography::
     :notcited:
-    :list: bullet
+    :list: enumerated
 
diff --git a/documentation/wntr-api.rst b/documentation/wntr-api.rst
@@ -26,4 +26,5 @@ API documentation
         wntr.network
         wntr.scenario
         wntr.sim
+        wntr.extensions
         wntr.utils
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,5 +3,5 @@ requires = ["setuptools", "numpy>=2.2.6"]
 build-backend = "setuptools.build_meta"
 
 [tool.pytest.ini_options]
-markers = ["time_consuming:excluded from ci quick test"]
+markers = ["time_consuming:excluded from ci quick test", "extensions:included only in extensions ci"]
 addopts = "--doctest-modules"
diff --git a/requirements.txt b/requirements.txt
@@ -5,26 +5,3 @@ networkx
 pandas>=2.0
 matplotlib
 setuptools<69.5.1
-
-# Optional
-plotly<6.0
-folium
-utm
-openpyxl
-geopandas
-rasterio
-rtree
-
-# Documentation
-sphinx
-sphinx_design
-sphinx_rtd_theme
-pydata_sphinx_theme
-sphinxcontrib-bibtex
-
-# Testing
-pytest
-nbformat
-nbconvert
-ipykernel
-coverage
diff --git a/setup.py b/setup.py
@@ -73,6 +73,11 @@
 LICENSE = 'Revised BSD'
 URL = 'https://github.com/USEPA/WNTR'
 DEPENDENCIES = ['numpy>=2.2.6', 'scipy', 'networkx', 'pandas>=2.0', 'matplotlib']
+EXTRAS = {
+    'optional': ['plotly<6.0', 'folium', 'utm', 'openpyxl', 'geopandas', 'rasterio', 'rtree'],
+    'doc': ['sphinx', 'sphinx_design', 'sphinx_rtd_theme', 'pydata_sphinx_theme', 'sphinxcontrib-bibtex'],
+    'test': ['pytest', 'nbformat', 'nbconvert', 'ipykernel', 'coverage'],
+}
 
 # use README file as the long description
 file_dir = os.path.abspath(os.path.dirname(__file__))
@@ -103,5 +108,6 @@
       url=URL,
       zip_safe=False,
       install_requires=DEPENDENCIES,
+      extras_require=EXTRAS,
       scripts=[],
       include_package_data=True)
diff --git a/wntr/__init__.py b/wntr/__init__.py
@@ -8,6 +8,7 @@
 from wntr import gis
 from wntr import library
 from wntr import utils
+from wntr import extensions
 from wntr import msx
 
 __version__ = '1.4.0'

diff --git a/wntr/extensions/__init__.py b/wntr/extensions/__init__.py
@@ -0,0 +1,5 @@
+"""
+The wntr.extensions package contains extensions to WNTR
+"""
+# Note, WNTR extensions should not import by default.  
+# Use <extension_name>/__init__.py to import the extension
diff --git a/wntr/extensions/hello_world/__init__.py b/wntr/extensions/hello_world/__init__.py
@@ -0,0 +1,4 @@
+"""
+The wntr.extensions.hello_world extension provides a simple example of a WNTR extension
+"""
+from wntr.extensions.hello_world import example_module