Skip to content
hamborgPublic

About

Numerical solver for ventilation ring-systems, provided as semantic knowledge graphs with timeseries data.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

DuctNet

Solves airflow and pressure in ventilation duct networks, including ring systems (main branches fed from both ends, closed loops, load-dependent flow-split points), from an RDF/Turtle building graph (Brick, FSO, BOT, ...) plus measured time series.

Status: Phase 1 (single timestep) plus a desktop window and a trim & respond test. Inspection, the single-timestep solver, the network schematic, the window and the trim & respond test (one timestep at a time) work on the synthetic networks and on the graph with real 2025 data. The window can solve a range of timesteps one after the other; the command-line time-series runner (Phase 2, also needed for trim & respond over a whole year) and the TimescaleDB adapter (Phase 3) are not built.

Quick start

Double-click DuctNet.bat to open the desktop window. You can also drop a .dnet project, a graph, a data file or a configuration file onto DuctNet.bat.

To associate .dnet files with DuctNet, run Register .dnet files.bat once. You can then open a project by double-clicking it. SYNTHETIC_DEMO.dnet is included as a small project for trying the application.

Install or rebuild the environment

From PowerShell in the project folder:

py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev,gui]"
.venv\Scripts\python -m pytest

The gui extra enables drag-and-drop support through tkinterdnd2. The desktop window and command-line solver work without drag-and-drop when that optional package is absent.

Command line

ductnet lives in the project's virtual environment: activate it (.venv\Scripts\Activate.ps1) or call .venv\Scripts\ductnet.exe. ductnet --help and ductnet inspect --help list everything.

Command Inputs What it does
ductnet inspect GRAPH GRAPH: the .ttl file. --data FILE: Parquet/CSV time series, to check which points have data. --config YAML: your overrides. --out DIR: write full report files. --no-cache: force re-parsing. Prints the inspection report. Large graphs take about a minute the first time and a few seconds afterwards (cached in ~/.ductnet/cache).
ductnet synth-data GRAPH --out FILE --start, --periods, --freq, --seed Writes invented placeholder measurements for every solver-relevant point of the graph, in each point's own unit.
ductnet synth --out DIR Writes the small synthetic example network and data.
ductnet solve GRAPH --data FILE and --time TIMESTAMP pick the measurements (first timestep if no time is given; no data = graph values and defaults only). --config YAML. --components 0,1 restricts to connected components from the inspection report. --out DIR. Solves one timestep and prints a summary. With --out: segments.csv (flow, direction, velocity, dp, pressures per element), nodes.csv, split_points.csv, measurement_residuals.csv, fitted_parameters.csv, inputs_applied.csv, convergence.json, assumptions.csv, config_used.yaml. Exit code 3 if not converged, 1 if parameters are missing with no default.
ductnet points GRAPH --out DIR --config YAML Lists the time-series ids the solver needs (timeseries_ids.csv plus one plain list per priority), for querying the database.
ductnet plot GRAPH --out FILE --data, --time, --config, --color flow|velocity|pressure|dp|friction|role Writes the network schematic by storey as a picture.
ductnet trim GRAPH --data FILE --time, --config, --ignored N and --demand setpoint|measured (override trim_respond: in the config for one run), --out DIR Trim & respond test for one timestep: the lowest common fan pressure at which at most N rooms are short of their demand (see Trim & respond test). With --out: trim_respond_summary.txt, trim_respond_rooms.csv, trim_respond_fans.csv, trim_respond_search.csv, end_state/ and current_state/ (full result tables), config_used.yaml. Exit code 0 for ok or plant off, 3 otherwise.
ductnet gui [FILE] --data, --config; FILE may be a graph or a .dnet project Opens the window.
ductnet run Not implemented yet.

Included files and example commands

The larger example project uses:

graph   data\my_graph.ttl
config  data\my_project_settings.yaml
data    data\my_timeseries_data.parquet

Open it in the desktop window:

.venv\Scripts\ductnet.exe gui data\my_graph.ttl --data data\my_timeseries_data.parquet --config data\my_project_settings.yaml

Solve one timestep and write the result files:

.venv\Scripts\ductnet.exe solve data\my_graph.ttl --data data\my_timeseries_data.parquet --time 2025-07-02T09:00 --config data\my_project_settings.yaml --out out\solve_project

Write a pressure-coloured network picture:

.venv\Scripts\ductnet.exe plot data\my_graph.ttl --data data\my_timeseries_data.parquet --time 2025-07-02T09:00 --config data\my_project_settings.yaml --color pressure --out out\network_pressure.png

Inspect the graph and write the report:

.venv\Scripts\ductnet.exe inspect data\my_graph.ttl --data data\my_timeseries_data.parquet --config data\my_project_settings.yaml --out out\inspect_project

Run the trim & respond test for one timestep:

.venv\Scripts\ductnet.exe trim data\my_graph.ttl --data data\my_timeseries_data.parquet --time 2025-03-12T09:00 --config data\my_project_settings.yaml --out out\trim_2025-03-12T09

Write lists of the time-series ids needed by the solver:

.venv\Scripts\ductnet.exe points data\my_graph.ttl --config data\my_project_settings.yaml --out out\timeseries_project

The small standalone demo files are examples/synthetic_demo_graph.ttl and examples/synthetic_demo_data.parquet.

from ductnet import inspect_graph, solve
report = inspect_graph("graph.ttl", config="my.yaml", data="data.parquet")   # read the graph once
result = solve(report, "data.parquet", "2025-01-15T10:00")
print(result.summary()); result.edges; result.nodes; result.split_points; result.save("out/solve")

from ductnet import trim_respond, trim_respond_report
tr = trim_respond(report, "data.parquet", "2025-01-15T10:00", baseline=result)   # baseline is optional
print(tr.summary()); tr.rooms; tr.fans; tr.save("out/trim")
rep = trim_respond_report([tr, ...])                 # several tested timesteps together
print(rep.text()); rep.timesteps; rep.rooms; rep.save("out/trim_report")

The case configuration can define the network scope, roughness corrections, equipment stand-ins, sensor placement and whether measured room flows or damper positions control the damper model.

Command-line notes

  • The first inspection of a large graph can take about a minute. Parsed graphs are cached, so later runs are much faster.
  • --time is interpreted in the time zone of the data file. The included larger data file uses UTC.
  • Exit code 0 means the solve converged, 3 means it did not converge, and 1 means required parameters are missing.
  • The command-line time-series runner is not implemented yet. Use Solve several... in the desktop window for a range of timesteps.
  • Result CSV files use ; as the separator and . as the decimal point.

Desktop window

Files, settings and projects

  • The configuration file is optional. Without one, DuctNet uses the packaged defaults. Select Config (optional) Settings... to edit the common case settings in a form.
  • File > Save project writes one .dnet file containing the graph, data, configuration and all solved timesteps. It also includes the per-timestep result tables, inspection report and aggregate report. A .dnet file is a ZIP archive, so a copy can be renamed to .zip and inspected with ordinary archive tools.
  • File > Open project or file... restores a saved project.
  • A .dnet project, graph, data file and configuration can be dropped onto the open window or onto DuctNet.bat. Drag-and-drop requires the optional gui dependency.
  • View > Storey order... changes the vertical order used in the network drawing. The order is stored in the configuration.
  • The Element names setting chooses between type plus identifier, label, identifier alone, or the graph entity name.

Navigating the network picture

  • Drag to pan. Shift-drag draws a selection window; the Drag: control can swap those actions.
  • Drag a selection window to the right to select elements fully inside it. Drag it to the left to select everything the window touches.
  • Click the nearest element to select it. Ctrl-click or Ctrl-drag adds to the selection.
  • With Click selects: run, clicking selects the complete run of ducts, elbows and transitions between tees, dampers or other components.
  • Use the mouse wheel to zoom. Shift-wheel zooms only horizontally and Ctrl-wheel only vertically. The axis buttons and scrollbars provide the same controls without a wheel.
  • Whole network resets the view.
  • When room names are visible, click one to select all elements currently carrying air to that room.
  • Drag either end of the colour scale to adjust its limits, or click the scale to enter limits directly.

Selection and analysis

  • With nothing selected, the selection pane lists the 20 largest values for the active colour quantity.
  • Listed elements are ordered upstream to downstream. Branching elements are marked and their branches are separated. Use Columns to choose the displayed properties.
  • Path between / to fan traces the path between two selected elements. With one selected element it traces the path back to its fan; when two elements are on separate branches it traces both upstream paths.
  • Air to this room selects the current airflow path to the room served by a selected terminal.
  • Critical path marks the path ending at the terminal with the least spare pressure.
  • Most critical element marks the worst element for the active quantity: largest flow, highest velocity, largest non-fan pressure drop or highest duct friction.
  • Outdoor side of the fans includes intake and exhaust runs that are hidden by default.

Several timesteps

  • Solve several... solves a selected range of timesteps.
  • Play steps through the solved results. Earlier split points and the critical path fade over three frames so movement is visible.
  • File > Save animation (GIF)... writes the playback as an animated image.
  • The Aggregate report tab summarizes recurring critical paths, open dampers, large pressure drops, split-point locations, velocities, fan performance and measurement fit. Use File > Save aggregate report to export its text, tables and figure.

Trim & respond in the window

  • Trim & respond (next to Solve several...) runs the test for the chosen timestep. It reuses that timestep's solve when there is one (a solve stored by an older DuctNet version is solved again). Its end state appears under Solved as <timestep> T&R and is drawn like any other result.
  • The Summary tab shows the test: the three states (fitted, measured pressure, T&R end state) with fan rises, flows, requests and fan power, the static pressure at the chosen points, the rooms at the damper limit and the rooms without a control damper. Below it follows the full solve of the end state.
  • The T&R report tab collects every test run in the window: one row per timestep (status, measured pressure, fan pressure change, fan power before and after, requests, the rooms that set the pressure), the power summed over the tested timesteps, and per room how often it is at the damper limit or short. Update refreshes it; Save report... or File > Save trim & respond report... writes trim_respond_report.txt, trim_respond_timesteps.csv, trim_respond_room_counts.csv and, with two or more tests, trim_respond_report.png.
  • File > Save trim & respond result... writes the tables of the shown test, plus end_state_network.png.
  • T&R end states are what-if states, not solves of the data, so Play, the animation and the Aggregate report leave them out.
  • Save project keeps the tests: each one under trim_respond/<timestep>/ (its tables and the result itself, reopened with the project) and the report under trim_respond/report/.

Trim & respond test

A trim & respond controller (ASHRAE Guideline 36) lowers the duct pressure setpoint step by step and raises it while more than I zones request pressure (damper about fully open). It settles at the lowest pressure at which at most I zones are starved. The test computes that end state directly for one timestep (trimrespond.py); no controller is simulated.

  1. The ordinary solve of the timestep gives the current fan pressure rises.
  2. In a copy of the network every fan becomes a pressure source with rise = current rise + shift, the same shift for all fans (fan_split: equal_shift). Every room is asked for its demand: the sum of its flow setpoints (SpFCI...), or its measured flow where a setpoint is missing (demand: measured always uses the measured flow). A damper may open no further than request_threshold (95 %); through the damper characteristic zeta = zeta_open * exp(k (1 - position)) that is a lower bound on the room's throttle. A room whose damper is at that bound and still gets less than (1 - shortfall_tolerance) of its demand is short, which counts as a request.
  3. Requests only grow when the shift falls, so the lowest shift with at most ignored_requests requests is found by bisection (rooms matching ignore_rooms never count; at most max_increase Pa above the current rise).
  4. With reference_sensors, a measured p state is found as well: the shift at which the mean static pressure at pressure_points equals the mean of those sensors. That is the plant as it runs, and the end state is compared with it. Without reference sensors the comparison is with the fitted state, whose absolute pressure level is not checked against data.
  5. Fan power = flow x rise / fan_efficiency (0.6, PLACEHOLDER).

Status ok, limit reached (even max_increase gives too many requests), plant off (fan flow below min_fan_flow) or nothing to adjust (no room with a flow-controlled damper; needs measurements.damper_control: flow). The settings live under trim_respond: in the config, for example:

trim_respond:
  ignored_requests: 2
  request_threshold: 95.0
  demand: setpoint
  ignore_rooms: []                     # regular expressions on room names
  pressure_points:                     # label: element id, name or alias
    left riser: <element id>
  reference_sensors: [<pressure sensor id>, ...]

Limits: steady state per timestep (no controller dynamics); the damper exponent k = 8 is a placeholder; fans without curve are pressure sources; terminals without a control damper are fixed openings and get more or less air with the pressure; tests over many timesteps need the Phase 2 runner (or one click per timestep in the window).

How the solver works

  • Element laws (elements.py): Darcy-Weisbach ducts (laminar below Re 2000, Swamee-Jain above 4000, blended between), fittings/dampers/terminals/equipment as quadratic losses, fans as a quadratic curve with affinity laws, fans without curve as pressure sources.
  • Solve (solver.py): global gradient algorithm on total pressure. One sparse symmetric positive-definite solve per iteration, backtracking line search, no loop identification, flow direction free to reverse. Tee losses depend on the flow split and are refreshed every iteration.
  • Measurements: damper positions and fan speeds set element parameters. Terminals without a characteristic and fans without a curve are unknowns, fitted by robust weighted least squares to the airflow and static-pressure sensors. Every measurement's residual is reported.
  • Outdoor side: unconnected ends and room-less terminals on the intake side of a supply fan or the discharge side of a return fan are taken as openings to ambient (registered as assumptions).
  • Room flows and flow-controlled dampers: where the graph does not say which controller is which duct damper, the sum of a room's flow sensors is one observation of the flow through that room's terminals. With measurements.damper_control: flow the room's control dampers are throttled (one fitted factor per room) until the model reproduces it.
  • Scope: scope.sources / scope.side restrict the solve to networks fed by selected source units and, optionally, to their supply or return side.
  • Checks: mass residual per node, pressure sums around every independent loop, velocity and friction ranges. Split points are nodes where two streams meet (supply) or part (return).

Loss coefficients

Fitting losses come from a table library, src/ductnet/loss_tables.yaml: elbows by diameter (or aspect ratio) and bend angle, tees/taps/transitions by flow-dependent formulas evaluated with the solved flows. Every entry names its source and carries a verified flag; uses of unverified entries are marked UNVERIFIED in the assumptions register. The shipped numbers were entered without the source documents at hand, so all but the trivial one are unverified. The ASHRAE Duct Fitting Database is licensed and not redistributed: put its values (or CIBSE, DIN/VDI, supplier data) in your own YAML file with the same structure and list it under fittings.extra_tables in your config; a higher priority overrides the shipped entry.

Python API

from ductnet import inspect_graph, load_network
report = inspect_graph("graph.ttl", data="data.parquet", config="my.yaml")
print(report.to_text()); report.save("out/inspect")
model, network = load_network("graph.ttl")      # network.graph is an undirected networkx.MultiGraph

inspect --out DIR writes inspect_report.txt/.json, points.csv, missing_parameters.csv, assumptions.csv and config_used.yaml. Input files are never modified.

How a graph becomes a network

  1. Vocabulary-neutral reading (semantics.py). Classes and properties are mapped to solver roles (fan, duct, fitting, damper, terminal, equipment, space, point, port, ...) by regular expressions on local names, configured under vocabulary: in the config. No URIs are hard-coded. The report lists what was mapped, what was not, and which connection triples could not be used. Connections through ports are lifted to the owning components. Also handled: port-to-port links with per-port geometry, parameters on typed property nodes (fpo:hasProperty [ a fpo:Length ; fpo:hasValue .. ]), unit strings, and points whose host is reached through owl:sameAs or hasPart.
  2. Undirected hydraulic network (topology.py). Two-connection components become edges, components with three or more connections (tees) become a star with one leg per connection, open ends of terminals/fans and rooms become fixed-pressure boundary nodes. Unconnected ports of anything else are kept as dead ends and reported, never turned into leaks. A 4-port air handling unit is split into a supply path and a return path. Graph edge direction (fso:feedsFluidTo etc.) is ignored; direction is a solver result.
  3. Loops and rings. Loop count = E - N + C. Ring elements are the non-bridge edges, grouped into 2-edge-connected blocks. Networks fed by several fans are flagged separately, because they have a flow-split point even without a closed loop in the graph.
  4. Solvability (solvability.py). Missing parameters are filled from configured defaults and recorded in the assumptions register, or reported as blocking when the default is null. Determinacy is a structural count: redundancy = flow/pressure observations minus elements without a known law.

Configuration and assumptions

All defaults live in one file, src/ductnet/defaults.yaml. Pass your own YAML with --config; it is merged over the defaults. Entries marked PLACEHOLDER are typical orders of magnitude and must be checked against the ASHRAE Duct Fitting Database or supplier data before results are relied on. Duct length, duct cross-section, terminal k-factor and filter/coil pressure drop have no default on purpose.

Data

DataFrameSource accepts wide (timestamp index, one column per time-series id) or long (timestamp, timeseries_id, value) frames and detects which. The solver will only use the DataSource interface (available_ids, snapshot, series), so a TimescaleDB adapter can replace it later.

Why the global gradient algorithm

Method Verdict
Global gradient (chosen) No loop identification needed, tolerant of poor starting flows, one sparse SPD solve per iteration, handles fans and fixed-pressure boundaries naturally, scales near-linearly.
Newton-Raphson on nodal pressures Same Jacobian structure, but needs Q = f^-1(dp), whose derivative is unbounded at zero flow, exactly where ring segments near the split point sit.
Hardy Cross Needs an explicit loop basis, converges linearly, slow on large networks. Kept as an independent check in the tests.
Weighted least squares Layered on top for unknown terminal flows and fan pressures; residual reported per measurement.
Cut the ring, find the neutral point Not needed: the split points are read from the solved flow directions.

Layout

src/ductnet/   config, assumptions, semantics, topology, datasource, solvability, inspection,
               fittings, elements, assemble, solver, results, synthetic, cli,
               plot (schematic by storey, readable names), analysis (where air comes from, runs,
               critical path, aggregates over timesteps), trimrespond (trim & respond test
               and its report), gui (the window)
DuctNet.bat    double-click launcher
tests/         pytest suite
examples/      small synthetic demo graph and matching Parquet data

Output files

All CSV files use ; as separator and . as decimal point. A project saved from the window is one .dnet file (a zip archive) holding the graph, the data, the configuration, every solved timestep with its result tables, and the trim & respond tests with their report.

Known limits

  • Loss tables are unverified. In the ordinary fit the model shows about half the measured static pressure at the mid-riser sensors. Trim & respond runs suggest the main cause is that the fit does not pin the pressure level (it lowers it to avoid overfeeding terminals without a control damper), rather than the header tee losses.
  • The three duct pressure sensors are located (the three ducts crossing between floor 4 and 5) but not assigned to a riser. The fit does not use them; the trim & respond test uses their mean as the reference pressure.
  • Room flow setpoints (SpFCI..._C) exist in the 2025 data only until 2025-05-07; after that the trim & respond demand is the measured room flow.
  • No thermal model: there are no temperatures in the results.
  • Dropping files on the open window needs the optional tkinterdnd2 package (pip install -e ".[gui]").

About

Numerical solver for ventilation ring-systems, provided as semantic knowledge graphs with timeseries data.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages