Solver Options

NANDRAD solver performance options: time integration (CVODE, Euler), tolerance, time step limits, linear solvers KLU/GMRES/BiCGStab, ILU preconditioner.

VICUS Buildings Page 4 of 12 in this chapter

Overview

The solver options are located in the simulation view on the Dynamic Simulation page in the Performance options tab. They affect only the computation speed and robustness of the numerical solution — for a converged computation not the physical results (within the tolerances). Empty input fields mean “Auto”: the solver then uses its default values. The sections below the general options can be expanded and are collapsed when the page is opened.

General options

The General options group is only visible when the Districts workspace is active and the project contains a heat network. It holds the Demand profile smoothing: of the network consumers (Detailed simulation, Normal simulation, Simplified simulation, Quick simulation or a custom width in the Smoothing width: field). In pure building projects the group is hidden.

Time integration method

FieldDefaultMeaning
Relative tolerance:1e-5Accuracy of the time integration; smaller values yield more accurate results at the cost of longer computation time
Integrator:CVODESelection: CVODE based solver [CVODE], Explicit Euler solver [ExplicitEuler], Implicit Euler solver [ImplicitEuler]
Maximum method order (1-5):5Limits the BDF order of CVODE; higher orders are more efficient but can introduce oscillations
Non-linear iteration convergence coefficient:0.1Scaling factor of the Newton convergence test; smaller values enforce tighter convergence
Initial time step:0.1 sFirst integration step; empty = automatic choice
Time step size limit (model consistency):1e-8 sSmallest allowed time step; if the solver needs smaller steps, it aborts — useful for detecting model inconsistencies
Maximum time step size:1 hLargest allowed time step; limits how far the solver may leap ahead

CVODE is an implicit multi-step solver (SUNDIALS) with variable order and step size and is the default choice for the stiff systems of equations of building simulation. With the explicit Euler method, the settings for the equation solver and preconditioner do not apply.

Linear equation system solver

FieldDefaultMeaning
Linear equation system solver:KLUSelection: Dense solver [Dense], KLU sparse solver [KLU], GMRES iterative solver [GMRES], BICGSTAB iterative solver [BiCGStab]
Maximum dimension for Krylov subspace:50Iterative solvers only (GMRES); larger values improve convergence but increase memory requirements
Linear iteration convergence coefficient:0.05Scaling factor of the linear convergence test

KLU is a direct, sparse solver and usually the most robust choice. GMRES and BiCGStab are iterative Krylov methods that can be faster for very large systems but require a preconditioner.

Preconditioner for iterative equation system solvers

FieldDefaultMeaning
Preconditioner:ILUIncomplete LU preconditioner [ILU]
Level of fill-in (ILU):3Accuracy of the incomplete LU factorization; higher values improve the preconditioning at the cost of more memory

These fields are only active when an iterative equation solver is selected.

Hydraulic network solver

The Hydraulic network solver section is only visible if the project contains a heat network or a supply system with a hydraulic network:

FieldDefaultMeaning
Newton convergence tolerance:0.001Absolute convergence tolerance of the Newton solver for the hydraulic network
Newton initial conditions: Use previous time step results as initial conditionenabledTake the initial values of the Newton method from the last time step
Solve system only in limited intervals: with Set fixed interval:disabled; 3 minDo not solve the hydraulics in every integration step, but at fixed intervals. Deprecated and not recommended: the step changes of the mass fluxes between the intervals disturb the time integrator; unchanged inputs are detected anyway, so the network is only solved when necessary
Fluid viscosity: Consider temperature dependent viscosityenabled for 5GDHC networks onlyThe kinematic viscosity is evaluated at the current fluid temperature in every hydraulic solve. Without the option it is frozen at the default fluid temperature of the network — this decouples hydraulics and fluid temperatures and is noticeably faster. The setting applies to the active network

Good to know

For pure building simulations, the default settings (CVODE + KLU, relative tolerance 1e-5) are almost always the best choice. If a simulation runs unusually slowly, the “Write statistics for each internal solver step” option on the start page helps to find the bottleneck before adjusting tolerances — tolerances that are too large can obscure or amplify control oscillations (thermostat, shading control).

Stay up to date

New features, tutorials and updates delivered to your inbox.