Simulation Settings and Start
Define the simulation period, network and solver settings and start the dynamic annual simulation
VICUS Districts Page 2 of 4 in this chapter
Overview
On the Dynamic Simulation page, you define the simulation period, network-specific model options and solver settings and start the annual simulation. Before the start, VICUS Districts automatically checks the network for typical error sources (open ends, missing pump characteristic curves, outdated diversity results) and exports the project into the solver’s calculation model.
Access
Simulation button in the main toolbar, then the Dynamic Simulation page in the list on the left. On the left are the Network settings and Performance options tabs, and to the right of them the simulation period and start buttons.
Simulation Period
Simulation start area:
| Field | Format / Unit | Meaning |
|---|---|---|
| Start date: | dd.mm.yyyy hh:mm:ss | Beginning of the simulation period |
| End date: | dd.mm.yyyy hh:mm:ss | End of the simulation period |
| Duration: | value + time unit (e.g. h, d, a) | Length of the period |
End date and duration are coupled: if you change the duration, the end date is adjusted automatically, and vice versa.
Network Settings
Network settings tab, Hydraulic network model options area:
| Option | Default | Unit | Meaning |
|---|---|---|---|
| Network to simulate: | active network | – | Selection when there are multiple networks in the project |
| Nominal temperature difference: | from network parameters | K (0–100) | Nominal temperature difference between supply and return of the network |
| Position of pressure maintenance: | first energy center, inlet | – | Energy center at which the pressure maintenance is applied, and its connection side Energy center inlet or Energy center outlet |
| Setpoint of pressure maintenance: | from network parameters | bar (−100–100) | Gauge pressure that the pressure maintenance holds at the reference node; it sets the pressure level of the whole network, see Pressure Calculation in the Network |
| Pipe discretization length: | from network parameters (20 m; 50 m with the Conventional district heating network template) | m | Maximum length of the fluid volumes into which each pipe is thermally subdivided (see Model Representation) |
| Initial fluid temperature: | empty = automatic | °C (−100–500) | Initial temperature of the fluid in the entire network at the start of the simulation |
The collapsible Ground coupling options area only appears if the network contains pipes with ground heat exchange (ground model) or geothermal components with a coupled ground model:
| Option | Unit | Meaning |
|---|---|---|
| Coupling time step: | min | Communication time step between the network model and the ground models; a maximum of 20 min is recommended for numerical stability |
| Discretize in multiple ground models along network | – | Generates several ground models along the routes instead of one model per laying situation (default: off) |
| Fluid temperature interval: | K | Temperature step size for the split into ground models (only with discretization enabled) |
| Number of ground models: | – | Display of the resulting number of models after clicking Calculate the discretization and the number of ground models |
Solver Settings
Performance options tab. The default values are suitable for heat networks; adjustments are only necessary in case of convergence problems or very large networks.
General Options
The General options group appears in the Districts workspace as soon as the project contains a network. It is stored per network and applies to the active network.
| Option | Default | Meaning |
|---|---|---|
| Demand profile smoothing: | Detailed simulation (No smoothing) | Smooths the predefined consumer demand profiles before the dynamic simulation, see below |
| Smoothing width: | – | Width of the smoothing window in h (0–720); only visible with Custom smoothing width |
The available entries:
| Entry | Smoothing width |
|---|---|
| Detailed simulation (No smoothing) | no smoothing |
| Normal simulation (Slight smoothing) | 1 h |
| Simplified simulation (Moderate smoothing) | 2 h |
| Quick simulation (Strong smoothing) | 6 h |
| Custom smoothing width | value from Smoothing width: |
On export, the demand profiles are smoothed with a Gaussian window whose standard deviation is the smoothing width. The annual energy is preserved exactly, while peak loads and short-term fluctuations are levelled out. User-defined demand files are never smoothed, and the steady-state calculation is not affected. Smoothed profiles can make the simulation more stable or faster in some cases and are usually accurate enough for heat losses and pump electricity; assess peak loads and control behaviour with unsmoothed profiles.
Hydraulic Network Solver
The collapsible Hydraulic network solver area appears when the project contains a network:
| Option | Default | Meaning |
|---|---|---|
| Newton convergence tolerance: | 10⁻⁴ | Absolute convergence tolerance of the Newton method for the network hydraulics |
| Newton initial conditions: | – | Use previous time step results as initial condition – start values of the Newton method from the last time step |
| Solve system only in limited intervals: | off | Solves the hydraulics not in every integration step but only at the interval Set fixed interval: (min) |
| Fluid viscosity: Consider temperature dependent viscosity | on for 5GDHC networks, otherwise off | Evaluate the fluid viscosity as a function of temperature, see below |
By default, the hydraulic network is solved in every integration step; the solver detects unchanged inputs itself and then skips the solve. Solve system only in limited intervals is deprecated and not recommended: the step changes of the mass fluxes between the intervals disturb the time integrator. When projects from versions before 2.1 are opened, the option is switched off.
Consider temperature dependent viscosity is stored per network and applies to the active network. When enabled, the kinematic viscosity of the fluid is evaluated at the current fluid temperature in every hydraulic solve, so the Reynolds number and the pipe friction follow the temperature. When disabled, the viscosity at the default fluid temperature of the network is used; the hydraulics are then decoupled from the fluid temperatures and noticeably faster. The option matters in cold district heating networks, where the viscosity of brine changes strongly at low temperatures; when older projects are opened, it is switched on for 5GDHC networks.
Time Integration and Equation Solvers
The collapsible areas Time integration method, Linear equation system solver and Preconditioner for iterative equation system solvers hold the settings of the time integrator:
| Option | Default | Meaning |
|---|---|---|
| Relative tolerance: | 10⁻⁵ | Relative error tolerance of the time integration |
| Integrator: | CVODE | Time-integration method with adaptive step size; alternatively Implicit/Explicit Euler with a fixed step size |
| Maximum method order (1-5): | auto | Highest order of the CVODE BDF method |
| Non-linear iteration convergence coefficient: | auto | Scaling of the Newton iteration convergence test |
| Initial time step: | 0.1 s | Initial time step of the integration |
| Time step size limit (model consistency): | – | Smallest allowed time step; if a smaller step is needed, the solver aborts |
| Maximum time step size: | 1 h | Upper limit of the adaptive step size |
| Linear equation system solver: | KLU (sparse) | Alternatively Dense, GMRES or BiCGStab; for the iterative solvers additionally Krylov dimension, convergence coefficient, Preconditioner: and Level of fill-in (ILU): |
The collapsible Command line solver options area additionally provides:
| Option | Default | Meaning |
|---|---|---|
| Solver message detail: | Normal | Output depth in the console window (Minimum to Very Detailed) |
| Number of parallel threads: | empty = automatic | Fixed number of threads (1–64). Automatic means: the value of the environment variable OMP_NUM_THREADS if set, otherwise the number of logical processor cores − 1, at most 8. In a co-simulation with ground models, the thread count is passed on to the network model (NANDRAD FMU) |
| Write statistics for each internal solver step | off | Generates detailed solver statistics files |
| Close console window when finished | off | Close the console window automatically after the run |
| Copy command line to clipboard | – | Copies the complete solver call, e.g. for batch runs |
You configure the outputs of the simulation on the Outputs page; for heat networks, the option Generate default network-related outputs automatically generates all common result quantities (see Model Representation and Result Quantities).
Start and Checks

Start simulation starts the simulation run with a progress display and a Cancel button.
Test initialization checks the model initialization for input errors without calculating the simulation – recommended before long runs.
Log opens the solver log file
<ProjectName>/log/screenlog.txt.
Before the start, VICUS Districts automatically performs the following checks:
- Network cleanup: Fittings are corrected and open line ends are cleaned up (as an undoable change).
- Ground coupling: If the coupling time step is larger than 20 min, a dialog offers to reduce it to 20 min (Reduce to 20 min / Keep current).
- Controlled pumps without limiting polynomial: Warning with a list of the affected nodes and components; without a limiting polynomial, the simulation may fail. Recommendation: assign the pump characteristic curve from the database via the steady-state calculation.
- Diversity: If the diversity results are outdated, the optimization is automatically re-run before the start.
The project is then exported into the solver’s calculation model (progress dialog) and the run is started. If the network contains coupled ground models, the simulation automatically runs as a co-simulation of the network and ground models.
If results of the network to be simulated already exist, the Start Solver dialog asks whether to start the simulation from scratch (Restart) or to continue the last run (Continue, only possible if the last run computed the same network). A restart replaces only the result files of this network; results of other networks in the project are kept (see Multiple Networks).
At the first start of a network, VICUS Districts automatically creates the default line diagrams and false-color plots of the network, provided the default network outputs are enabled and no diagrams of that kind exist for the network yet. This happens only once per network and can be undone.
Practical tip
Never start a long annual run unchecked. With Test initialization you check the model for input errors in seconds without calculating the simulation – this spares you the abort after many minutes of computation time. Also take the pre-start checks seriously: a warning about controlled pumps without limiting polynomial can actually make the run fail; in that case assign the pump characteristic curve beforehand from the database via the steady-state calculation.