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.
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.
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 pytestThe 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.
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. |
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.yamlSolve 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_projectWrite 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.pngInspect 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_projectRun 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-12T09Write 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_projectThe 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.
- The first inspection of a large graph can take about a minute. Parsed graphs are cached, so later runs are much faster.
--timeis interpreted in the time zone of the data file. The included larger data file uses UTC.- Exit code
0means the solve converged,3means it did not converge, and1means 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.
- 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
.dnetfile containing the graph, data, configuration and all solved timesteps. It also includes the per-timestep result tables, inspection report and aggregate report. A.dnetfile is a ZIP archive, so a copy can be renamed to.zipand inspected with ordinary archive tools. - File > Open project or file... restores a saved project.
- A
.dnetproject, graph, data file and configuration can be dropped onto the open window or ontoDuctNet.bat. Drag-and-drop requires the optionalguidependency. - 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.
- 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.
- 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.
- 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 (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&Rand 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.csvand, 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 undertrim_respond/report/.
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.
- The ordinary solve of the timestep gives the current fan pressure rises.
- 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: measuredalways uses the measured flow). A damper may open no further thanrequest_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. - Requests only grow when the shift falls, so the lowest shift with at most
ignored_requestsrequests is found by bisection (rooms matchingignore_roomsnever count; at mostmax_increasePa above the current rise). - With
reference_sensors, a measured p state is found as well: the shift at which the mean static pressure atpressure_pointsequals 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. - 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).
- 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: flowthe room's control dampers are throttled (one fitted factor per room) until the model reproduces it. - Scope:
scope.sources/scope.siderestrict 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).
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.
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.MultiGraphinspect --out DIR writes inspect_report.txt/.json, points.csv, missing_parameters.csv,
assumptions.csv and config_used.yaml. Input files are never modified.
- 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 undervocabulary: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 throughowl:sameAsorhasPart. - 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:feedsFluidToetc.) is ignored; direction is a solver result. - 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.
- Solvability (
solvability.py). Missing parameters are filled from configured defaults and recorded in the assumptions register, or reported as blocking when the default isnull. Determinacy is a structural count: redundancy = flow/pressure observations minus elements without a known law.
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.
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.
| 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. |
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
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.
- 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
tkinterdnd2package (pip install -e ".[gui]").