The key modelling concepts in DAE Tools:
What’s the time? (AKA: Hello world!)  Importing DAE Tools pyDAE module(s), units and variable types developing models, setting up a simulation, declaring auxiliary objects (DAE solver, data reporter, log), simulation runtime options, running a smulation. 
Tutorial 1  Using distribution domains, distributing parameters/variables/equations on domains, using derivative functions (dt, d, d2), setting boundary and initial conditions. 
Tutorial 2  Using arrays (discrete distribution domains), specifying degrees of freedom, setting initial guesses. 
Tutorial 3  Declaring arrays of variable values (Array function) and using functions that operate on them arrays, using the Constant function, making nonuniform grids. 
Tutorial 6  Using ports, making port connections, declaring components (instances of other models). 
Tutorial 10  Saving and restoring initialisation files, evaluating integrals. 
Support for discrete systems:
Tutorial 4  Declaring discontinuous equations (symmetrical state transition networks: daeIF statements). 
Tutorial 5  Declaring discontinuous equations (nonsymmetrical state transition networks: daeSTN statements). 
Tutorial 13  Using event ports, handling events using ON_CONDITION() and ON_EVENT() functions, and declaring user defined actions. 
Tutorial 15  Declaring nested state transitions. 
The simulation options:
Tutorial 7  Making userdefined operating procedures, resetting the values of degrees of freedom and resetting initial conditions. 
Data reporting:
Tutorial 8  Using data reporters to write the results into files (Matlab, MS Excel, JSON, XML, HDF5, VTK, Pandas), developing custom data reporters. 
DAE and LA solvers:
Tutorial 9  Using available linear equations solvers (SuperLU, SuperLU_MT, Trilinos Amesos, IntelPardiso, Pardiso). 
Tutorial 11  Using iterative linear equations solvers (Trilinos AztecOO) and preconditioners (builtin AztecOO, Ifpack, ML). 
Tutorial 12  Using SuperLU and SuperLU_MT solvers and their options. 
External functions:
Tutorial 14  Declaring and using external functions. 
Logging:
Tutorial 17  Using TCPIP Log and TCPIPLogServer. 
Interoperability with NumPy:
Tutorial 16  Using DAE Tools variables and NumPy functions to solve a simple stationary 1D heat conduction by manually assembling Finite Element stiffness matrix and load vector. 
Tutorial 18  Using DAE Tools variables and NumPy functions to generate and solve a simple ODE system. 
Thermophysical property packages:
Tutorial 19  Using thermophysical property packages in DAE Tools. 
Variable constraints:
Tutorial 20  Specifying variable constraints in DAE Tools. 
Equation evaluation modes:
Tutorial 21  Specifying different equation evaluation modes and evaluators. 
What is the time? (AKA Hello world!) is a very simple model. The model consists of a single variable (called ‘time’) and a single differential equation:
d(time)/dt = 1
This way, the value of the variable ‘time’ is equal to the elapsed time in the simulation at any moment.
This tutorial presents the basic structure of daeModel and daeSimulation classes. A typical DAETools simulation requires the following 8 tasks:
The ‘time’ variable plot:
Files
Model report  whats_the_time.xml 
Runtime model report  whats_the_timert.xml 
Source code  whats_the_time.py 
This tutorial introduces several new concepts:
In this example we model a simple heat conduction problem: a conduction through a very thin, rectangular copper plate.
For this problem, we need a twodimensional Cartesian grid (x,y) (here, for simplicity, divided into 10 x 10 segments):
y axis
^

Ly  L T T T T T T T T T R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
 L + + + + + + + + + R
0  L B B B B B B B B B R
> x axis
0 Lx
Points ‘B’ at the bottom edge of the plate (for y = 0), and the points ‘T’ at the top edge of the plate (for y = Ly) represent the points where the heat is applied.
The plate is considered insulated at the left (x = 0) and the right edges (x = Lx) of the plate (points ‘L’ and ‘R’). To model this type of problem, we have to write a heat balance equation for all interior points except the left, right, top and bottom edges, where we need to specify boundary conditions.
In this problem we have to define two distribution domains:
the following parameters:
and a single variable:
The model consists of 5 equations (1 distributed equation + 4 boundary conditions):
Heat balance:
rho * cp * dT(x,y)/dt = k * [d2T(x,y)/dx2 + d2T(x,y)/dy2]; x in (0, Lx), y in (0, Ly)
Neumann boundary conditions at the bottom edge:
k * dT(x,y)/dy = Qb; x in (0, Lx), y = 0
Dirichlet boundary conditions at the top edge:
T(x,y) = Tt; x in (0, Lx), y = Ly
Neumann boundary conditions at the left edge (insulated):
dT(x,y)/dx = 0; y in [0, Ly], x = 0
Neumann boundary conditions at the right edge (insulated):
dT(x,y)/dx = 0; y in [0, Ly], x = Lx
The temperature plot (at t=100s, x=0.5, y=*):
Files
Model report  tutorial1.xml 
Runtime model report  tutorial1rt.xml 
Source code  tutorial1.py 
This tutorial introduces the following concepts:
The model in this example is very similar to the model used in the tutorial 1. The differences are:
The temperature plot (at t=100s, x=0.5, y=*):
Files
Model report  tutorial2.xml 
Runtime model report  tutorial2rt.xml 
Source code  tutorial2.py 
This tutorial introduces the following concepts:
The model in this example is identical to the model used in the tutorial 1. Some additional equations that calculate the total flux at the bottom edge are added to illustrate the array functions.
The temperature plot (at t=100, x=0.5, y=*):
The average temperature plot (considering the whole xy domain):
Files
Model report  tutorial3.xml 
Runtime model report  tutorial3rt.xml 
Source code  tutorial3.py 
This tutorial introduces the following concepts:
In this example we model a very simple heat transfer problem where a small piece of copper is at one side exposed to the source of heat and at the other to the surroundings.
The lumped heat balance is given by the following equation:
rho * cp * dT/dt  Qin = h * A * (T  Tsurr)
where Qin is the power of the heater, h is the heat transfer coefficient, A is the surface area and Tsurr is the temperature of the surrounding air.
The process starts at the temperature of the metal of 283K. The metal is allowed to warm up for 200 seconds, when the heat source is removed and the metal cools down slowly to the ambient temperature.
This can be modelled using the following symmetrical state transition network:
IF t < 200
Qin = 1500 W
ELSE
Qin = 0 W
The temperature plot:
Files
Model report  tutorial4.xml 
Runtime model report  tutorial4rt.xml 
Source code  tutorial4.py 
This tutorial introduces the following concepts:
In this example we use the same heat transfer problem as in the tutorial 4. Again we have a piece of copper which is at one side exposed to the source of heat and at the other to the surroundings.
The process starts at the temperature of 283K. The metal is allowed to warm up, and then its temperature is kept in the interval (320K  340K) for 350 seconds. This is performed by switching the heater on when the temperature drops to 320K and by switching the heater off when the temperature reaches 340K. After 350s the heat source is permanently switched off and the metal is allowed to slowly cool down to the ambient temperature.
This can be modelled using the following nonsymmetrical state transition network:
STN Regulator
case Heating:
Qin = 1500 W
on condition T > 340K switch to Regulator.Cooling
on condition t > 350s switch to Regulator.HeaterOff
case Cooling:
Qin = 0 W
on condition T < 320K switch to Regulator.Heating
on condition t > 350s switch to Regulator.HeaterOff
case HeaterOff:
Qin = 0 W
The temperature plot:
Files
Model report  tutorial5.xml 
Runtime model report  tutorial5rt.xml 
Source code  tutorial5.py 
This tutorial introduces the following concepts:
A simple port type ‘portSimple’ is defined which contains only one variable ‘t’. Two models ‘modPortIn’ and ‘modPortOut’ are defined, each having one port of type ‘portSimple’. The wrapper model ‘modTutorial’ instantiate these two models as its units and connects them by connecting their ports.
Files
Model report  tutorial6.xml 
Runtime model report  tutorial6rt.xml 
Source code  tutorial6.py 
This tutorial introduces the following concepts:
In this example we use the same heat transfer problem as in the tutorial 4. The input power of the heater is defined as a variable. Since there is no equation defined to calculate the value of the input power, the system contains N variables but only N1 equations. To create a wellposed DAE system one of the variable needs to be “fixed”. However the choice of variables is not arbitrary and in this example the only variable that can be fixed is Qin. Thus, the Qin variable represents a degree of freedom (DOF). Its value will be fixed at the beginning of the simulation and later manipulated in the userdefined schedule in the overloaded function daeSimulation.Run().
The default daeSimulation.Run() function (reimplemented in Python) is:
def Run(self):
# Python implementation of daeSimulation::Run() C++ function.
import math
while self.CurrentTime < self.TimeHorizon:
# Get the time step (based on the TimeHorizon and the ReportingInterval).
# Do not allow to get past the TimeHorizon.
t = self.NextReportingTime
if t > self.TimeHorizon:
t = self.TimeHorizon
# If the flag is set  a user tries to pause the simulation, therefore return.
if self.ActivityAction == ePauseActivity:
self.Log.Message("Activity paused by the user", 0)
return
# If a discontinuity is found, loop until the end of the integration period.
# The data will be reported around discontinuities!
while t > self.CurrentTime:
self.Log.Message("Integrating from [%f] to [%f] ..." % (self.CurrentTime, t), 0)
self.IntegrateUntilTime(t, eStopAtModelDiscontinuity, True)
# After the integration period, report the data.
self.ReportData(self.CurrentTime)
# Set the simulation progress.
newProgress = math.ceil(100.0 * self.CurrentTime / self.TimeHorizon)
if newProgress > self.Log.Progress:
self.Log.Progress = newProgress
In this example the following schedule is specified:
The plot of the inlet power:
The temperature plot:
Files
Model report  tutorial7.xml 
Runtime model report  tutorial7rt.xml 
Source code  tutorial7.py 
This tutorial introduces the following concepts:
Some time it is not enough to send the results to the DAE Plotter but it is desirable to export them into a specified file format (i.e. for use in other programs). For that purpose, daetools provide a range of data reporters that save the simulation results in various formats. In adddition, daetools allow implementation of custom, userdefined data reporters. As an example, a userdefined data reporter is developed to save the results into a plain text file (after the simulation is finished). Obviously, the data can be processed in any other fashion. Moreover, in certain situation it is required to process the results in more than one way. The daeDelegateDataReporter can be used in those cases. It has the same interface and the functionality like all data reporters. However, it does not do any data processing itself but calls the corresponding functions of data reporters which are added to it using the function AddDataReporter. This way it is possible, at the same time, to send the results to the DAE Plotter and save them into a file (or process the data in some other ways). In this example the results are processed in 10 different ways at the same time.
The model used in this example is very similar to the model in the tutorials 4 and 5.
Files
Model report  tutorial8.xml 
Runtime model report  tutorial8rt.xml 
Source code  tutorial8.py 
This tutorial introduces the following concepts:
Currently there are the following linear equations solvers available:
In this example we use the same conduction problem as in the tutorial 1.
The temperature plot (at t=100s, x=0.5, y=*):
Files
Model report  tutorial9.xml 
Runtime model report  tutorial9rt.xml 
Source code  tutorial9.py 
This tutorial introduces the following concepts:
In this example we use the same conduction problem as in the tutorial 1.
Files
Model report  tutorial10.xml 
Runtime model report  tutorial10rt.xml 
Source code  tutorial10.py 
This tutorial describes the use of iterative linear solvers (AztecOO from the Trilinos project) with different preconditioners (builtin AztecOO, Ifpack or ML) and corresponding solver options. Also, the range of Trilins Amesos solver options are shown.
The model is very similar to the model in tutorial 1, except for the different boundary conditions and that the equations are written in a different way to maximise the number of items around the diagonal (creating the problem with the diagonally dominant matrix). These type of systems can be solved using very simple preconditioners such as Jacobi. To do so, the interoperability with the NumPy package has been exploited and the package itertools used to iterate through the distribution domains in x and y directions.
The equations are distributed in such a way that the following incidence matrix is obtained:
XXX 
 X X X 
 X X X 
 X X X 
 X X X 
 XXX 
 XXX 
 X XXX X 
 X XXX X 
 X XXX X 
 X XXX X 
 XXX 
 XXX 
 X XXX X 
 X XXX X 
 X XXX X 
 X XXX X 
 XXX 
 XXX 
 X XXX X 
 X XXX X 
 X XXX X 
 X XXX X 
 XXX 
 XXX 
 X XXX X 
 X XXX X 
 X XXX X 
 X XXX X 
 XXX 
 XXX 
 X X X 
 X X X 
 X X X 
 X X X 
 XXX
The temperature plot (at t=100s, x=0.5, y=*):
Files
Model report  tutorial11.xml 
Runtime model report  tutorial11rt.xml 
Source code  tutorial11.py 
This tutorial describes the use and available options for superLU direct linear solvers:
The model is the same as the model in tutorial 1, except for the different boundary conditions.
The temperature plot (at t=100s, x=0.5, y=*):
Files
Model report  tutorial12.xml 
Runtime model report  tutorial12rt.xml 
Source code  tutorial12.py 
This tutorial introduces the following concepts:
In this example we use the very similar model as in the tutorial 5.
The simulation output should show the following messages at t=100s and t=350s:
...
********************************************************
simpleUserAction2 message:
This message should be fired when the time is 100s.
********************************************************
...
********************************************************
simpleUserAction executed; input data = 427.464093129832
********************************************************
...
The plot of the ‘event’ variable:
The temperature plot:
Files
Model report  tutorial13.xml 
Runtime model report  tutorial13rt.xml 
Source code  tutorial13.py 
In this tutorial we introduce the external functions concept that can handle and execute functions in external libraries. The daeScalarExternalFunctionderived external function object is used to calculate the heat transferred and to interpolate a set of values using the scipy.interpolate.interp1d object. In addition, functions defined in shared libraries (.so in GNU/Linux, .dll in Windows and .dylib in macOS) can be used via ctypes Python library and daeCTypesExternalFunction class.
In this example we use the same model as in the tutorial 5 with few additional equations.
The simulation output should show the following messages at the end of simulation:
...
scipy.interp1d statistics:
interp1d called 1703 times (cache value used 770 times)
The plot of the ‘Heat_ext1’ variable:
The plot of the ‘Heat_ext2’ variable:
The plot of the ‘Value_interp’ variable:
Files
Model report  tutorial14.xml 
Runtime model report  tutorial14rt.xml 
Source code  tutorial14.py 
External function source code  tutorial14_heat_function.c 
This tutorial introduces the following concepts:
In this example we use the same model as in the tutorial 4 with the more complex STN:
IF t < 200
IF 0 <= t < 100
IF 0 <= t < 50
Qin = 1600 W
ELSE
Qin = 1500 W
ELSE
Qin = 1400 W
ELSE IF 200 <= t < 300
Qin = 1300 W
ELSE
Qin = 0 W
The plot of the ‘Qin’ variable:
The temperature plot:
Files
Model report  tutorial15.xml 
Runtime model report  tutorial15rt.xml 
Source code  tutorial15.py 
This tutorial shows how to use DAE Tools objects with NumPy arrays to solve a simple stationary heat conduction in one dimension using the Finite Elements method with linear elements and two ways of manually assembling a stiffness matrix/load vector:
d2T(x)/dx2 = F(x); x in (0, Lx)
Linear finite elements discretisation and simple FE matrix assembly:
phi phi
(k1) (k)
* *
*  * *  *
*  * *  *
*  * *  *
*  * *  *
*  *  *
*  * *  *
*  * *  *
*  * *  *
*  * element (k) *  *
**+++++++++++++++++++**
x x
(ki (k)
\_________ _________/

dx
The comparison of the analytical solution and two ways of assembling the system is given in the following plot:
Files
Model report  tutorial16.xml 
Runtime model report  tutorial16rt.xml 
Source code  tutorial16.py 
This tutorial introduces the following concepts:
In this example we use the same heat transfer problem as in the tutorial 7.
The screenshot of the TCP/IP log server:
The temperature plot:
Files
Model report  tutorial17.xml 
Runtime model report  tutorial17rt.xml 
Source code  tutorial17.py 
This tutorial shows one more problem solved using the NumPy arrays that operate on DAE Tools variables. The model is taken from the Sundials ARKODE (ark_analytic_sys.cpp). The ODE system is defined by the following system of equations:
dy/dt = A*y
where:
A = V * D * Vi
V = [1 1 1; 1 2 1; 0 1 2];
Vi = 0.25 * [5 1 3; 2 2 2; 1 1 1];
D = [0.5 0 0; 0 0.1 0; 0 0 lam];
lam is a large negative number.
The analytical solution to this problem is:
Y(t) = V*exp(D*t)*Vi*Y0
for t in the interval [0.0, 0.05], with initial condition y(0) = [1,1,1]’.
The stiffness of the problem is directly proportional to the value of “lamda”. The value of lamda should be negative to result in a wellposed ODE; for values with magnitude larger than 100 the problem becomes quite stiff.
In this example, we choose lamda = 100.
The solution:
lamda = 100
reltol = 1e06
abstol = 1e10

t y0 y1 y2

0.0050 0.70327 0.70627 0.41004
0.0100 0.52267 0.52865 0.05231
0.0150 0.41249 0.42145 0.16456
0.0200 0.34504 0.35696 0.29600
0.0250 0.30349 0.31838 0.37563
0.0300 0.27767 0.29551 0.42383
0.0350 0.26138 0.28216 0.45296
0.0400 0.25088 0.27459 0.47053
0.0450 0.24389 0.27053 0.48109
0.0500 0.23903 0.26858 0.48740

The plot of the ‘y0’, ‘y1’, ‘y2’ variables:
Files
Model report  tutorial18.xml 
Runtime model report  tutorial18rt.xml 
Source code  tutorial18.py 
This tutorial introduces the thermo physical property packages.
Since there are many thermo packages with a very different API the CapeOpen standard has been adopted in daetools. This way, all thermo packages implementing the CapeOpen thermo interfaces are automatically vailable to daetools. Those which do not are wrapped by the class with the CapeOpen conforming API. At the moment, two types of thermophysical property packages are implemented:
The central point is the daeThermoPhysicalPropertyPackage class. It can load any COM component that implements CapeOpen 1.1 ICapeThermoPropertyPackageManager interface or the CoolProp thermo package.
The framework provides lowlevel functions (specified in the CapeOpen standard) in the daeThermoPhysicalPropertyPackage class and the higherlevel functions in the auxiliary daeThermoPackage class defined in the daetools/pyDAE/thermo_packages.py file. The lowlevel functions are defined in the ICapeThermoCoumpounds and ICapeThermoPropertyRoutine CapeOpen interfaces. These functions come in two flavours:
The daeThermoPackage auxiliary class offers functions to calculate specified properties, for instance:
All functions return properties in the SI units (as specified in the CapeOpen 1.1 standard).
Known issues:
In this tutorial, we use a very simple model: a quantity of liquid (water + ethanol mixture) is heated using the constant input power. The model uses a thermo package to calculate the commonly used transport properties such as specific heat capacity, thermal conductivity, dynamic viscosity and binary diffusion coefficients. First, the lowlevel functions are tested for CapeOpen and CoolProp packages in the test_single_phase, test_two_phase, test_coolprop_single_phase functions. The results depend on the options selected in the CapeOpen package (equation of state, etc.). Then, the model that uses a thermo package is simulated.
The plot of the specific heat capacity as a function of temperature:
Files
Model report  tutorial19.xml 
Runtime model report  tutorial19rt.xml 
Source code  tutorial19.py 
This tutorial illustrates the support variable constraints available in Sundials IDA solver. Benchmarks are available from Matlab documentation.
Absolute Value Function:
dy/dt = fabs(y)
solved on the interval [0,40] with the initial condition y(0) = 1. The solution of this ODE decays to zero. If the solver produces a negative solution value, the computation eventually will fail as the calculated solution diverges to inf. Using the constraint y >= 0 resolves this problem.
The Knee problem:
epsilon * dy/dt = (1t)*y  y**2
solved on the interval [0,2] with the initial condition y(0) = 1. The parameter epsilon is 0 < epsilon << 1 and in this example equal to 1e6. The solution follows the y = 1x isocline for the whole interval of integration which is incorrect. Using the constraint y >= 0 resolves the problem.
In DAE Tools contraints follow the Sundials IDA solver implementation and can be specified using the valueConstraint argument of the daeVariableType class __init__ function:
and changed for individual variables using daeVariable.SetValueConstraint functions.
Absolute Value Function solution plot:
The Knee problem solution plot:
Files
Source code  tutorial20.py 
This tutorial introduces different methods for evaluation of equations in parallel. Equations residuals, Jacobian matrix and sensitivity residuals can be evaluated in parallel using two methods
The Evaluation Tree approach (default)
OpenMP API is used for evaluation in parallel. This method is specified by setting daetools.core.equations.evaluationMode option in daetools.cfg to “evaluationTree_OpenMP” or setting the simulation property:
simulation.EvaluationMode = eEvaluationTree_OpenMP
numThreads controls the number of OpenMP threads in a team. If numThreads is 0 the default number of threads is used (the number of cores in the system). Sequential evaluation is achieved by setting numThreads to 1.
The Compute Stack approach
Equations can be evaluated in parallel using:
OpenMP API for general purpose processors and manycore devices (i.e. Xeon Phi).
This method is specified by setting daetools.core.equations.evaluationMode option in daetools.cfg to “computeStack_OpenMP” or setting the simulation property:
simulation.EvaluationMode = eComputeStack_OpenMP
numThreads controls the number of OpenMP threads in a team. If numThreads is 0 the default number of threads is used (the number of cores in the system). Sequential evaluation is achieved by setting numThreads to 1.
OpenCL framework for streaming processors (GPU, GPGA) and heterogeneous systems.
This type is implemented in an external Python module pyEvaluator_OpenCL. It is up to one order of magnitude faster than the Evaluation Tree approach. However, it does not support external functions nor thermophysical packages.
OpenCL evaluators can use a single or multiple OpenCL devices. It is required to install OpenCL drivers/runtime libraries. InteL: https://software.intel.com/enus/articles/opencldrivers AMD: https://support.amd.com/enus/kbarticles/Pages/OpenCL2Driver.aspx NVidia: https://developer.nvidia.com/opencl
Files
Source code  tutorial21.py 