Model Representation and Result Quantities
How the heat network is simulated: thermo-hydraulic model, time integration, result quantities and output files
VICUS Districts Page 4 of 4 in this chapter
Overview
The dynamic simulation represents the heat network as a thermo-hydraulic model: a quasi-steady hydraulics (mass fluxes and pressures) coupled with transient energy balances of the fluid volumes. The time integration is performed with an adaptive step size. This page describes the model representation compactly and lists the result quantities and output files as a reference.
Model Representation
Hydraulics
In each integration step, the nonlinear equation system of mass conservation at the nodes and the pressure-loss relations of all elements is solved with a Newton method. The setpoint of pressure maintenance is prescribed at the reference node; from the geodetic heights of the nodes, the pressures including the geodetic component additionally result (quantities with the suffix WithElevation). All pressures written out are gauge pressures, see Pressure Calculation in the Network. Controlled valves and pumps enter the equation system directly with their current control variables; the volume flow of controlled pumps is limited to their maximum volume flow in all control modes.
For pumps with index point (worst point) control, the network is first solved for the pump head of the initial values, and only then is the control equation released. After convergence, the solver checks whether the controlled consumer is still the index point; if not, it continues with the new index point. Pressure difference and node of the index point are available as result quantities (see below).
Thermics
Each pipe is subdivided into fluid volumes along its length; the maximum element length is the Pipe discretization length from the network settings. The number of volumes per pipe is
with the pipe length . The value is rounded up, so no volume is longer than . For each volume, an energy balance of heat transport with the mass flux and heat exchange with the surroundings (e.g. ground) is solved. A smaller discretization length increases the accuracy of the temperature fronts in the network, but enlarges the equation system and the computation time.
Controllers and Ground Coupling
Controllers (e.g. for valves and pumps) are computed within the network model; their current manipulated and error variables are available as result quantities (see Controllers). Pipes with ground heat exchange and ground heat sources with a coupled ground model are represented via separate ground models generated on export, which are coupled to the network model by co-simulation with the configured coupling time step (see Ground Model).
Time Integration
The default integrator is CVODE, an implicit method with an adaptive step size: the time step is automatically increased or decreased based on a local error estimate (relative tolerance 10⁻⁵ by default, maximum time step 1 h). In numerically demanding situations, the steps can temporarily become very small; the outputs are produced independently of this on the output grid (default: hourly).
Result Quantities
With the option Generate default network-related outputs (see Defining Outputs), hourly outputs are generated for all network elements. Which quantities an element provides depends on the component type. Powers and heat fluxes are written as the mean value over the output step (column “Mean”, file suffix -mean), so that summing them up yields correct energies. Temperatures, pressures, flows and ratios such as COP and efficiency are instantaneous values at the output time.
| Quantity | Unit | Mean | Meaning |
|---|---|---|---|
| FluidMassFlux | kg/s | – | Mass flux through the element |
| FluidVolumeFlow | m³/s | – | Volume flow through the element |
| FluidVelocity | m/s | – | Flow velocity (pipes) |
| InletNodeTemperature / OutletNodeTemperature | °C | – | Temperature at the inlet or outlet of the element |
| TemperatureDifference | K | – | Outlet minus inlet temperature |
| OutletNodePressure | Pa | – | Pressure at the outlet node |
| OutletNodePressureWithElevation | Pa | – | Gauge pressure at the outlet node including the geodetic component — the pressure that stands in the pipe |
| PressureDifference | Pa | – | Pressure difference across the element |
| PressureDifferencePerLength | Pa/m | – | Pressure gradient per meter of pipe length |
| PressureLossFittingsInlet / PressureLossFittingsOutlet | Pa | – | Pressure loss due to fittings at the inlet/outlet |
| PressureLossBase / PressureLossControlled | Pa | – | Pressure loss of the element without or due to the controlled valve |
| FlowElementHeatLoss | W | yes | Heat flux from the element to the surroundings; negative if the element injects heat into the network |
| HeatLossPerLength | W/m | yes | Heat loss of the pipe per meter |
| HeatingPower | W | yes | Heating power supplied to the fluid (heat exchanger) |
| PressureHead | Pa | – | Head of the pump |
| ElectricalPower | W | yes | Electrical power consumption (pumps, heat pumps) |
| MechanicalPower | W | yes | Mechanical (hydraulic) power of the pump at its operating point |
| PumpEfficiency | – | – | Current pump efficiency |
| VolumeFlowRateExceedance | m³/s | – | Amount by which the required volume flow exceeds the possible volume flow of the pump |
| PressureDifferenceAtWorstpoint | Pa | – | Pressure difference at the index point (only for pumps with index point control) |
| WorstpointNodeId | – | – | ID of the network node that currently is the index point (only with index point control) |
| COP | – | – | Coefficient of performance of the heat pump |
| CondenserHeatFlux / EvaporatorHeatFlux | W | yes | Heat flux at the condenser or evaporator of the heat pump |
| RequiredBuildingHeatFlux | kW | yes | Heat power requested by the building (transfer station) |
| HeatDeficitAbsolute | kW | yes | Uncovered heat demand of the transfer station |
| HeatDeficitRelative | – | – | Ratio of heat deficit to requested heat flux |
| OutletTemperatureSecondary / InletTemperatureSecondary | °C | – | Secondary-side temperatures of the transfer station |
| OutletTemperatureSecondarySetpoint | °C | – | Setpoint of the secondary-side outlet temperature of the transfer station |
| StoredHeatingEnergy | kWh | – | Currently stored heat quantity of the transfer station |
| ValveOpening | – | – | Relative opening of the thermostatic bypass valve (only networks with bypass) |
Further quantities – for instance InletNodePressure, InletNodePressureWithElevation, the pressure exceedance InletNodePressureExceedance / OutletNodePressureExceedance (amount in Pa by which the gauge pressure exceeds the nominal pressure of the pipe; 0 as long as the limit holds) or the manipulated and error variables of controllers (ControllerResultValue / ControllerErrorValue) – are provided by the solver as well. They are not part of the default outputs of the dynamic simulation and are added as custom outputs when needed.
The names of the pressure quantities have changed:
…NodePressureAbsoluteis now…NodePressureWithElevation,…NodeOverPressureis now…NodePressureExceedanceand is written in Pa instead of bar, and…NodePressureRelativehas been dropped without replacement. Evaluation scripts using the old names have to be adapted — there is deliberately no backward compatibility.
Output Files
Alongside the project file, the simulation creates a folder <ProjectName>/:
results/– result fileslog/screenlog.txt– solver log
Next to it, VICUS Districts writes the exported calculation model <ProjectName>.nandrad. A co-simulation with ground models adds the co-simulation file <ProjectName>.msim and the directory <ProjectName>_fmus/ with the FMUs of the network and ground models.
For each result quantity, a file <NetworkName>-<NetworkID>.<Quantity>.btf (binary format, default) or .tsv (text format) is written, e.g. Network-12.FluidMassFlux.btf. The network ID in the prefix keeps the results of several networks apart in the same folder and keeps them attached after a network is renamed. The format is set by the option Use binary format on the Outputs page. Averaged or integrated outputs receive the suffix -mean or -integral – for the default outputs this applies to all power and heat flux quantities, e.g. Network-12.HeatingPower-mean.btf; for an output grid other than hourly, its name is appended.
The TSV files are tab-separated text files: the first column contains the time, followed by one column per network element with the element name, ID and unit in the column header, e.g. SupplyPipe(ID=1612).FluidMassFlux [kg/s].
You evaluate the results directly in the result area of VICUS Districts (false color in the 3D model, line charts) or open them in PostProc 2 – the TSV files can also be further processed in any spreadsheet or scripting tool.