openswmm 6.0.0a1__tar.gz → 6.0.0.dev2__tar.gz

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/CMakeLists.txt

@@ -11,6 +11,40 @@
 
 cmake_minimum_required(VERSION 3.24)
 
+# ============================================================================
+# Source-distribution guard: the sdist on PyPI is metadata-only and does NOT
+# carry the OpenSWMM C/C++ engine source tree.  Detect that we have neither a
+# pre-built engine prefix nor the parent project's CMakeLists.txt reachable
+# via add_subdirectory(..) and fail with a clear, actionable error rather
+# than letting vcpkg or the C compiler emit a confusing one.  Without this
+# guard, a stray VCPKG_ROOT in the user's environment causes the auto-load
+# block below to fire and vcpkg then tries to read a vcpkg.json next to the
+# unpacked sdist that does not exist.
+# ============================================================================
+if(NOT DEFINED OPENSWMM_ENGINE_INSTALL_PREFIX
+        AND NOT DEFINED ENV{OPENSWMM_ENGINE_INSTALL_PREFIX}
+        AND NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/../CMakeLists.txt")
+    message(FATAL_ERROR
+        "openswmm cannot be built from this source distribution: the sdist "
+        "does not bundle the OpenSWMM C/C++ engine sources, and no pre-built "
+        "engine was supplied via -DOPENSWMM_ENGINE_INSTALL_PREFIX=<path>.\n"
+        "\n"
+        "Install a pre-built wheel instead:\n"
+        "    python -m pip install openswmm\n"
+        "\n"
+        "Wheels are published for Python 3.9-3.13 on Linux x86_64, macOS "
+        "(arm64 and x86_64), and Windows x64. If pip fell back to this "
+        "sdist, no wheel matched your platform/interpreter -- check the "
+        "available files at https://pypi.org/project/openswmm/#files and, "
+        "if needed, switch to a supported Python version.\n"
+        "\n"
+        "Source builds are supported only from a full git checkout of the "
+        "openswmm.engine repository:\n"
+        "    git clone https://github.com/hydrocouple/openswmm.engine\n"
+        "    cd openswmm.engine/python\n"
+        "    pip install . --no-build-isolation")
+endif()
+
 # ============================================================================
 # vcpkg manifest directory: the vcpkg.json lives one directory above python/.
 # Set VCPKG_MANIFEST_DIR before project() so vcpkg's toolchain file sees it.

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: openswmm
-Version: 6.0.0a1
+Version: 6.0.0.dev2
 Summary: Python bindings for the OpenSWMM stormwater modelling engine.
 Keywords: SWMM,stormwater,hydrology,hydraulics,water resources,environmental engineering
 Author-Email: Caleb Buahin <caleb.buahin@gmail.com>
@@ -23,7 +23,6 @@ Classifier: Operating System :: Unix
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -37,7 +36,7 @@ Project-URL: Homepage, https://github.com/hydrocouple/openswmm.engine/python
 Project-URL: Repository, https://github.com/hydrocouple/openswmm.engine
 Project-URL: Bug Tracker, https://github.com/hydrocouple/openswmm.engine/issues
 Project-URL: Changelog, https://github.com/hydrocouple/openswmm.engine/blob/main/CHANGELOG.md
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: numpy>=1.21.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3; extra == "dev"

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/concepts.rst

@@ -256,6 +256,21 @@ Threading & multiprocessing
 * **Multiple threads, one Solver per thread**: supported.  The C
   engine is reentrant; two threads each holding their own Solver do
   not interact.
+
+  As of OpenSWMM 6.0, the following Cython entry points release the
+  GIL while inside the C engine, so two such threads execute their
+  C work truly in parallel rather than serialising on the interpreter:
+
+  * :meth:`Solver.step`, :meth:`Solver.stride`
+  * Every ``*_bulk`` getter / setter on :class:`Nodes`,
+    :class:`Links`, and :class:`Subcatchments`
+    (:meth:`get_depths_bulk`, :meth:`get_flows_bulk`,
+    :meth:`get_quality_bulk`, etc.)
+
+  Registered step-begin / step-end callbacks remain safe: their
+  Cython trampolines reacquire the GIL via ``noexcept with gil:``
+  before invoking the user's Python callable.
+
 * **Multiple threads, one shared Solver**: **not** supported.  The
   Solver and its domain classes assume a single-threaded caller.  If
   you need shared state, drive a single Solver from one thread and

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/links.rst

@@ -138,6 +138,41 @@ Pump-specific
    * - :meth:`get_pump_init_state` / :meth:`set_pump_init_state`
      - Initial on/off state.
 
+Pump utilization statistics
+---------------------------
+
+Accumulated during a running simulation. Read either per-link with the
+scalar accessors, or — for whole-network summaries — in one shot with
+:meth:`get_pump_stats_bulk`, which performs a single C ABI crossing
+instead of ``3 * n_links`` and releases the GIL during the call.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Method
+     - Returns
+   * - :meth:`get_stat_pump_cycles(idx)`
+     - Pump on/off cycle count (``int``).
+   * - :meth:`get_stat_pump_on_time(idx)`
+     - Total pump on-time in seconds (``float``).
+   * - :meth:`get_stat_pump_volume(idx)`
+     - Total volume pumped in ft³ (``float``).
+   * - :meth:`get_pump_stats_bulk()`
+     - ``dict`` of three ``np.ndarray`` columns — ``cycles``
+       (``int32``), ``on_time`` (``float64``), ``volume`` (``float64``);
+       non-pump links carry ``cycles == -1``.
+
+.. code-block:: python
+
+   # Whole-network pump summary in one call.
+   stats = links.get_pump_stats_bulk()
+   pumps = stats["cycles"] >= 0           # filter to pump links
+   total_pumped_ft3 = stats["volume"][pumps].sum()
+   total_run_time_h = stats["on_time"][pumps].sum() / 3600.0
+   print(f"{pumps.sum()} pumps, {total_pumped_ft3:.1f} ft³ pumped, "
+         f"{total_run_time_h:.1f} pump-hours")
+
 Weir / orifice
 --------------
 
@@ -301,10 +336,51 @@ Bulk arrays
      - All link mid-point depths.
    * - :meth:`get_quality_bulk(p)`
      - Pollutant ``p`` concentration per link.
+   * - :meth:`get_pump_stats_bulk`
+     - All pump statistics in a single C call —
+       ``{"cycles": ndarray[int32], "on_time": ndarray[float64],
+       "volume": ndarray[float64]}``. Non-pump links carry
+       ``cycles == -1`` as a sentinel.
+   * - :meth:`get_velocities_bulk`
+     - Cross-sectional velocity per link *(added 6.0.0)*.
+   * - :meth:`get_capacities_bulk`
+     - Capacity ratio ``q / q_full`` per link *(added 6.0.0)*.
+   * - :meth:`get_volumes_bulk`
+     - Stored volume per link *(added 6.0.0)*.
+   * - :meth:`get_control_settings_bulk`
+     - Active control setting (0..1) per link *(added 6.0.0)*.
+   * - :meth:`get_target_settings_bulk`
+     - Target control setting per link *(added 6.0.0)*.
+   * - :meth:`get_hyd_powers_bulk`
+     - Hydraulic power per link in ft-lb/s
+       (``gamma * |Q| * |hL|``) *(added 6.0.0)*.
+   * - :meth:`get_ids_bulk`
+     - ``list[str]`` of every link's id in one C call
+       *(added 6.0.0; stride-packed UTF-8)*.
+
+Memory-aliasing note: ``get_flows_bulk`` and ``get_depths_bulk`` return
+arrays that share memory with engine scratch space — ``.copy()`` if you
+keep them past the next call. The other bulk getters (``get_pump_stats_bulk``
+and every Phase 3 addition) return freshly allocated arrays, so the
+result is yours to retain.
+
+Whole-network reporting pattern (mirrors the Nodes example):
+
+.. code-block:: python
 
-Same memory-aliasing rule as :class:`Nodes`: the returned array shares
-memory with engine scratch space; ``.copy()`` if you keep it past the
-next call.
+   ids       = links.get_ids_bulk()              # list[str]
+   flows     = links.get_flows_bulk()            # np.ndarray[float64]
+   velocities = links.get_velocities_bulk()
+   capacities = links.get_capacities_bulk()
+   powers    = links.get_hyd_powers_bulk()
+   stats     = links.get_pump_stats_bulk()
+   pumps     = stats["cycles"] >= 0              # boolean mask
+
+   # Pump-energy summary in 3 lines:
+   pump_run_hours = float(stats["on_time"][pumps].sum() / 3600.0)
+   pump_ft_lb_s   = float(powers[pumps].sum())
+   pump_hp        = pump_ft_lb_s / 550.0
+   print(f"{pumps.sum()} pumps  ran {pump_run_hours:.1f} h  ~{pump_hp:.1f} hp avg")
 
 Vectorised peak detection across all links:
 

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/nodes.rst

@@ -316,7 +316,7 @@ want vectorised.  Each returns or accepts a contiguous
 
 .. list-table::
    :header-rows: 1
-   :widths: 35 65
+   :widths: 40 60
 
    * - Method
      - Returns / accepts
@@ -327,13 +327,33 @@ want vectorised.  Each returns or accepts a contiguous
    * - :meth:`set_depths_bulk(arr)`
      - Force depths for every node from ``arr``.
    * - :meth:`get_inflows_bulk`
-     - Total inflow per node.
+     - **Lateral** inflow per node (see naming note below).
    * - :meth:`get_overflows_bulk`
      - Overflow (flooding) per node.
    * - :meth:`set_lat_inflows_bulk(arr)`
      - Lateral inflow per node.
    * - :meth:`get_quality_bulk(p)`
      - Concentration of pollutant ``p`` per node.
+   * - :meth:`get_volumes_bulk`
+     - Stored volume per node *(added 6.0.0)*.
+   * - :meth:`get_outflows_bulk`
+     - Total outflow per node *(added 6.0.0)*.
+   * - :meth:`get_losses_bulk`
+     - Per-node losses (evaporation + seepage) *(added 6.0.0)*.
+   * - :meth:`get_lateral_inflows_bulk`
+     - Lateral inflow per node — explicitly named successor to
+       :meth:`get_inflows_bulk` *(added 6.0.0)*.
+   * - :meth:`get_ids_bulk`
+     - ``list[str]`` of every node's id in one C call
+       *(added 6.0.0; stride-packed UTF-8)*.
+
+.. note::
+
+   Naming caveat: :meth:`get_inflows_bulk` reads the *lateral* inflow
+   column on the C side despite its generic name; it is retained for
+   backward compatibility, but new code should prefer
+   :meth:`get_lateral_inflows_bulk`. Both methods return the same
+   values.
 
 Memory-aliasing rule: the array returned by a ``get_*_bulk`` method
 shares memory with an internal scratch buffer that the engine reuses
@@ -351,6 +371,35 @@ keep the array (e.g. across a step), call ``.copy()``:
         history.append(nodes.get_depths_bulk().copy())   # detach from scratch
     H = np.stack(history)              # shape (T, n_nodes)
 
+Whole-network reporting with the Phase 3 bulk accessors:
+
+.. code-block:: python
+
+   # Single C call per quantity — replaces N round-trips through
+   # the scalar getters. Useful when building post-run summaries,
+   # MCP / GUI dataframes, or input to a downstream tool.
+   ids       = nodes.get_ids_bulk()              # list[str]
+   depths    = nodes.get_depths_bulk()           # np.ndarray[float64]
+   volumes   = nodes.get_volumes_bulk()
+   outflows  = nodes.get_outflows_bulk()
+   losses    = nodes.get_losses_bulk()
+   lat       = nodes.get_lateral_inflows_bulk()
+
+   # Build a single DataFrame-shaped dict in one shot:
+   summary = {
+       "id":               ids,
+       "depth":            depths,
+       "volume":           volumes,
+       "outflow":          outflows,
+       "losses":           losses,
+       "lateral_inflow":   lat,
+   }
+
+   # Find the most-flooded outfall, e.g.:
+   flooded = nodes.get_overflows_bulk()
+   worst   = int(flooded.argmax())
+   print(f"max overflow at {ids[worst]}: {flooded[worst]:.3f}")
+
 ----
 
 EngineState requirements & exceptions

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/solver.rst

@@ -409,6 +409,69 @@ For the full list see :class:`~openswmm.engine.ErrorCode`.
 
 ----
 
+Runoff interface file (Phase 1b)
+================================
+
+Persists per-subcatchment runoff snapshots to a binary file matching
+the legacy SWMM-5 ``Frunoff`` format.  Useful when a slow-running
+runoff phase needs to be cached and replayed against a downstream
+routing-only run (e.g. design-storm sensitivity analyses).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Method
+     - Description
+   * - :meth:`open_runoff_iface_write(path)`
+     - Open the file in SAVE mode.  The engine then auto-emits one
+       record per runoff substep until :meth:`close_runoff_iface`
+       is called.
+   * - :meth:`open_runoff_iface_read(path)`
+     - Open the file in USE mode.  Currently exposes the file but
+       does **not** yet skip the engine's runoff computation —
+       see the note below.
+   * - :meth:`save_runoff_step(dt)`
+     - Manually force one snapshot.  Normally unnecessary because the
+       engine auto-saves; provided for plugin authors and tests.
+   * - :meth:`read_runoff_step()`
+     - Read one record from the open USE file into the current
+       subcatchment runoff/quality vectors.  Returns ``False`` on EOF.
+   * - :meth:`close_runoff_iface()`
+     - Close the file (idempotent).  Called automatically when the
+       solver is closed.
+
+.. note::
+
+   USE-mode auto-skip — making the engine bypass its own runoff
+   computation when a USE file is open — is a follow-up to Phase 1b.
+   Today's USE mode is an advanced manual feature: callers must invoke
+   :meth:`read_runoff_step` between :meth:`Solver.step` calls *and*
+   understand that the engine will overwrite the loaded state when it
+   runs its own runoff phase.
+
+End-to-end SAVE example:
+
+.. code-block:: python
+
+   from openswmm.engine import EngineState, Solver
+
+   with Solver("design_storm.inp", "design_storm.rpt", "design_storm.out") as s:
+       s.open()
+       s.initialize()
+       s.start()
+       s.open_runoff_iface_write("design_storm.rfi")
+       while s.state == EngineState.RUNNING:
+           if s.step() != 0:
+               break
+       s.end()
+       s.close_runoff_iface()
+       # design_storm.rfi now contains one record per runoff substep and
+       # can be reopened by a downstream routing-only run via
+       # ``s.open_runoff_iface_read(...)``.
+
+----
+
 See also
 ========
 

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/statistics.rst

@@ -99,6 +99,10 @@ Per-subcatchment
 Bulk variants
 -------------
 
+Each bulk method makes a single C call and returns a contiguous
+``np.ndarray[float64]``. The GIL is released for the duration of the
+C call.
+
 .. list-table::
    :header-rows: 1
    :widths: 50 50
@@ -111,9 +115,46 @@ Bulk variants
      - All-link peak flows.
    * - :meth:`subcatch_runoff_vol_bulk()`
      - All-subcatchment runoff volumes.
+   * - :meth:`node_max_overflow_bulk()`
+     - All-node peak overflow rate *(added 6.0.0)*.
+   * - :meth:`node_vol_flooded_bulk()`
+     - All-node total flooded volume *(added 6.0.0)*.
+   * - :meth:`node_time_flooded_bulk()`
+     - All-node cumulative time-flooded *(added 6.0.0)*.
+   * - :meth:`subcatch_max_runoff_bulk()`
+     - All-subcatchment peak runoff *(added 6.0.0)*.
+   * - :meth:`link_max_velocity_bulk()`
+     - All-link peak velocity *(added 6.0.0)*.
+   * - :meth:`link_max_filling_bulk()`
+     - All-link peak depth/full-depth ratio *(added 6.0.0)*.
+   * - :meth:`link_vol_flow_bulk()`
+     - All-link cumulative flow volume *(added 6.0.0)*.
+   * - :meth:`link_surcharge_time_bulk()`
+     - All-link cumulative surcharge time *(added 6.0.0)*.
+
+Whole-network flooding summary in 4 C calls (replaces a ``4 * n_nodes``
+Python loop):
+
+.. code-block:: python
+
+   from openswmm.engine import Nodes, Statistics
+
+   stats   = Statistics(solver)
+   nodes   = Nodes(solver)
+
+   ids        = nodes.get_ids_bulk()
+   max_over   = stats.node_max_overflow_bulk()
+   vol_flood  = stats.node_vol_flooded_bulk()
+   t_flood    = stats.node_time_flooded_bulk()
+
+   # Worst-flooded node by cumulative volume:
+   worst = int(vol_flood.argmax())
+   print(f"{ids[worst]}: vol={vol_flood[worst]:.1f},  "
+         f"peak overflow={max_over[worst]:.3f},  hours={t_flood[worst]:.2f}")
 
 The standard memory-aliasing rule applies — ``.copy()`` if you need
-to keep the array.
+to keep the array (the four pre-6.0 bulk getters share scratch
+buffers; the 6.0 additions return freshly allocated arrays).
 
 ----
 
@@ -214,7 +255,9 @@ Compute surcharge fraction across the network
 Bulk arrays
 ===========
 
-The ``*_bulk`` family is the vectorised path:
+The ``*_bulk`` family is the vectorised path. Each call returns a
+contiguous ``np.ndarray[float64]`` of the indicated shape. GIL is
+released during the underlying C call.
 
 .. list-table::
    :header-rows: 1
@@ -228,10 +271,27 @@ The ``*_bulk`` family is the vectorised path:
      - ``(n_links,)``
    * - :meth:`subcatch_runoff_vol_bulk`
      - ``(n_subcatch,)``
-
-Same memory-aliasing semantics as the bulk methods on :class:`Nodes`
-and :class:`Links` — ``.copy()`` if you keep the array past the next
-call.
+   * - :meth:`node_max_overflow_bulk`
+     - ``(n_nodes,)`` *(added 6.0.0)*
+   * - :meth:`node_vol_flooded_bulk`
+     - ``(n_nodes,)`` *(added 6.0.0)*
+   * - :meth:`node_time_flooded_bulk`
+     - ``(n_nodes,)`` *(added 6.0.0)*
+   * - :meth:`subcatch_max_runoff_bulk`
+     - ``(n_subcatch,)`` *(added 6.0.0)*
+   * - :meth:`link_max_velocity_bulk`
+     - ``(n_links,)`` *(added 6.0.0)*
+   * - :meth:`link_max_filling_bulk`
+     - ``(n_links,)`` *(added 6.0.0)*
+   * - :meth:`link_vol_flow_bulk`
+     - ``(n_links,)`` *(added 6.0.0)*
+   * - :meth:`link_surcharge_time_bulk`
+     - ``(n_links,)`` *(added 6.0.0)*
+
+Memory-aliasing rule: the three pre-6.0 bulk methods share scratch
+buffers with engine state — ``.copy()`` if you need to retain them
+past the next call. The 6.0 additions return freshly allocated
+arrays.
 
 ----
 

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/docs/guide/subcatchments.rst

@@ -297,24 +297,57 @@ Per-subcatchment runoff coefficient (post-run summary)
 Bulk arrays
 ===========
 
-The :class:`Subcatchments` class does not (yet) expose bulk-array
-accessors.  Vectorise across the population manually:
+Each bulk method makes a single C call and returns a contiguous
+``np.ndarray[float64]`` of shape ``(n_subcatchments,)`` (or a
+``list[str]`` for ids). The GIL is released for the duration of the C
+call, so multi-threaded consumers can read from independent solvers
+in parallel.
 
-.. code-block:: python
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
 
-    import numpy as np
+   * - Method
+     - Returns / accepts
+   * - :meth:`get_runoff_bulk`
+     - Runoff rate per subcatchment (project flow units).
+   * - :meth:`get_quality_bulk(p)`
+     - Concentration of pollutant ``p`` per subcatchment.
+   * - :meth:`get_rainfall_bulk`
+     - Rainfall rate per subcatchment *(added 6.0.0)*.
+   * - :meth:`get_evap_bulk`
+     - Evaporation loss per subcatchment *(added 6.0.0)*.
+   * - :meth:`get_infil_bulk`
+     - Infiltration loss per subcatchment *(added 6.0.0)*.
+   * - :meth:`get_snow_depth_bulk`
+     - Snow depth per subcatchment *(added 6.0.0; placeholder zeros
+       pending full snow-state integration)*.
+   * - :meth:`get_ids_bulk`
+     - ``list[str]`` of every subcatchment's id in one C call
+       *(added 6.0.0; stride-packed UTF-8)*.
+
+Whole-network water-balance pattern using the Phase 3 accessors:
 
-    runoff = np.zeros(sc.count())
-    while s.state == EngineState.RUNNING:
-        if s.step() != 0:
-            break
-        for i in range(sc.count()):
-            runoff[i] += sc.get_runoff(i)
+.. code-block:: python
 
-If you need a strictly faster path, fall back to the
-:class:`OutputReader` after the run and use the bulk subcatchment
-methods (:doc:`output_reader`) — that's typically fastest for
-post-processing.
+   ids    = sc.get_ids_bulk()
+   rain   = sc.get_rainfall_bulk()
+   infil  = sc.get_infil_bulk()
+   evap   = sc.get_evap_bulk()
+   runoff = sc.get_runoff_bulk()
+
+   # Per-subcatch instantaneous residual (storage / snow can make this
+   # noisy step-by-step but it should integrate near zero over a long
+   # simulation if the model is well-balanced).
+   residual = rain - infil - evap - runoff
+   for i, name in enumerate(ids):
+       print(f"  {name:<12}  R={rain[i]:.3f}  I={infil[i]:.3f}  "
+             f"E={evap[i]:.3f}  Q={runoff[i]:.3f}  resid={residual[i]:+.3f}")
+
+For *cumulative* (post-run) statistics, prefer the bulk accessors on
+:class:`Statistics` (``subcatch_runoff_vol_bulk`` etc.) or the
+:class:`OutputReader` — those are denser and pull from the report
+file rather than recomputing from the live state.
 
 ----
 

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/openswmm/engine/_2d.pxd

@@ -13,7 +13,8 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_vertex_get_xyz(void* engine, int idx,
                                 double* x, double* y, double* z)
     int swmm_2d_vertex_get_xyz_bulk(void* engine,
-                                     double* x, double* y, double* z)
+                                     double* x, double* y, double* z) nogil
+    int swmm_2d_set_vertex_z(void* engine, int idx, double z)
     int swmm_2d_triangle_get_vertices(void* engine, int idx,
                                        int* v0, int* v1, int* v2)
     int swmm_2d_triangle_get_area(void* engine, int idx, double* area)
@@ -23,7 +24,7 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_triangle_get_neighbours(void* engine, int idx,
                                          int* n0, int* n1, int* n2)
     int swmm_2d_edge_get_geometry_bulk(void* engine,
-                                        double* length, double* nx, double* ny)
+                                        double* length, double* nx, double* ny) nogil
 
     # Coupling
     int swmm_2d_vertex_coupling_count(void* engine, int* count)
@@ -37,14 +38,14 @@ cdef extern from "openswmm_2d.h":
     int swmm_2d_get_coupling_flux(void* engine, int idx, double* flux)
     int swmm_2d_get_rainfall(void* engine, int idx, double* rainfall)
     int swmm_2d_get_net_source(void* engine, int idx, double* net_source)
-    int swmm_2d_get_depths_bulk(void* engine, double* depths)
-    int swmm_2d_get_heads_bulk(void* engine, double* heads)
-    int swmm_2d_get_coupling_fluxes_bulk(void* engine, double* fluxes)
-    int swmm_2d_get_edge_flux_bulk(void* engine, double* flux)
+    int swmm_2d_get_depths_bulk(void* engine, double* depths) nogil
+    int swmm_2d_get_heads_bulk(void* engine, double* heads) nogil
+    int swmm_2d_get_coupling_fluxes_bulk(void* engine, double* fluxes) nogil
+    int swmm_2d_get_edge_flux_bulk(void* engine, double* flux) nogil
 
     # State — per vertex
     int swmm_2d_vertex_get_head(void* engine, int idx, double* head)
-    int swmm_2d_vertex_get_heads_bulk(void* engine, double* heads)
+    int swmm_2d_vertex_get_heads_bulk(void* engine, double* heads) nogil
 
     # Statistics
     int swmm_2d_get_max_depth(void* engine, double* max_depth)

{openswmm-6.0.0a1 → openswmm-6.0.0.dev2}/openswmm/engine/_2d.pyi

@@ -92,7 +92,8 @@ class Surface2D:
         npt.NDArray[np.float64],
         npt.NDArray[np.float64],
     ]:
-        """Return (x, y, z) NumPy arrays for all vertices.
+        """Return (x, y, z) NumPy arrays for all vertices. GIL is released
+        during the C call.
 
         @return: Tuple C{(x, y, z)}, each of shape C{(n_vertices,)} with
             dtype C{float64}.
@@ -101,6 +102,23 @@ class Surface2D:
         """
         ...
 
+    def set_vertex_z(self, idx: int, z: float) -> None:
+        """Set the ground elevation of a mesh vertex.
+
+        Updates derived geometry for every triangle incident to this
+        vertex (centroid Z, per-edge midpoint Z). XY-derived fields are
+        unaffected. When called during a running simulation, solver
+        state (head, depth) is intentionally not rewritten — the implied
+        depth = head - bed therefore changes by the same amount as bed.
+
+        @param idx: Vertex index (0-based).
+        @type idx: int
+        @param z: New ground elevation (project vertical units).
+        @type z: float
+        @raise RuntimeError: If the C API call fails.
+        """
+        ...
+
     def get_triangle_vertices(self, idx: int) -> tuple[int, int, int]:
         """Return the (v0, v1, v2) vertex indices for a triangle.
 
@@ -205,10 +223,13 @@ class Surface2D:
 
     # ====================================================================
     # State (depth/velocity) - per triangle bulk arrays
+    #
+    # Every bulk getter in this section releases the GIL for the C call.
     # ====================================================================
 
     def get_depths(self) -> npt.NDArray[np.float64]:
-        """Return depths for all triangles as a NumPy array.
+        """Return depths for all triangles as a NumPy array. GIL is
+        released during the C call.
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
@@ -217,7 +238,8 @@ class Surface2D:
         ...
 
     def get_heads(self) -> npt.NDArray[np.float64]:
-        """Return total heads for all triangles as a NumPy array.
+        """Return total heads for all triangles as a NumPy array. GIL is
+        released during the C call.
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
         @rtype: np.ndarray
@@ -226,7 +248,8 @@ class Surface2D:
         ...
 
     def get_coupling_fluxes(self) -> npt.NDArray[np.float64]:
-        """Return coupling fluxes for all triangles as a NumPy array.
+        """Return coupling fluxes for all triangles as a NumPy array. GIL
+        is released during the C call.
 
         @return: Array of shape C{(n_triangles,)} with dtype C{float64}.
             Positive values denote flux into the 2D surface.
@@ -236,7 +259,8 @@ class Surface2D:
         ...
 
     def get_edge_flux_bulk(self) -> npt.NDArray[np.float64]:
-        """Return normal edge fluxes for all triangle edges.
+        """Return normal edge fluxes for all triangle edges. GIL is
+        released during the C call.
 
         Indexed as C{[tri*3 + localEdge]}.
         @return: Array of shape C{(n_triangles*3,)} with dtype C{float64}.
@@ -245,6 +269,7 @@ class Surface2D:
 
     def get_edge_geometry_bulk(self) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64], npt.NDArray[np.float64]]:
         """Return time-invariant edge lengths and outward unit normal components.
+        GIL is released during the C call.
 
         Returns C{(length, nx, ny)}, each indexed as C{[tri*3 + localEdge]}.
 
@@ -317,6 +342,7 @@ class Surface2D:
 
     def get_vertex_heads(self) -> npt.NDArray[np.float64]:
         """Return reconstructed heads at all vertices as a NumPy array.
+        GIL is released during the C call.
 
         @return: Array of shape C{(n_vertices,)} with dtype C{float64}.
         @rtype: np.ndarray