0.5
|
Dr. Christiane Kettner, University of Karlsruhe, FBTA.
The simulation of controller strategies with the simulation code TRNSYS (ColSim is based on a similar structure to the modular simulation code TRNSYS) and other commercially available programs is not possible without modifying numeric algorithms of the programs' solvers in order to achieve convergence with small time steps. Furthermore, the implementation of controller routines in Fortran within the programs is absolutely unsuitable for the code transfer to modern micro-controller hardware. Experiencing these (and other) restrictions of existing simulation programs was the original motivation to create a new simulation environment. ColSim is based on the UNIX multitasking philosophy (ColSim can be compiled as well on 32-bit-MS-windows systems) and the idea of public domain software. The current platform is a LINUX system (default installation SuSE LINUX) with different public domain tools included to setup the simulation environment. Most important is the GCC C-Compiler which represents a solid base for highly reliable software and development environments. ColSim is primarily a command line driven tool, which can be controlled interactively by a simple TCL-menu. The visualization of online results is realized with the interactive function plotting program GNUPLOT [14]. The design of systems to be simulated can be done with the vector graphic tool XFIG [13], which allows to convert a simulation script with all necessary object relations and parameter information.
The differential equations of the dynamic system are solved by a finite difference method. ColSim uses a spreaded working (System equations are solved inside the object calculation) modified Euler solver to calculate system state at run time of each object. The Euler algorithm requires small time steps to ensure stability but in return it's simple to realize, fast to execute, and has further advantages in comparison to other classical integration methods (e.g. Runge-Kutta).
Plug Flow Model: The plug flow model allows the tracing of the mass flow through a closed hydraulic network, which guarantees a fast calculation of the object chain. The plug is initiated at a pump object, is shifted through the branched network and is returned to the origin (pump). This mechanism allows simple modeling of flow delay effects and a mass balance at the second call of the pump in one time step.
An energy and mass flow balance is automatically executed within every time step. Current activities focus on the development of controllers to drive pumps and fans in various applications.
ColSim is completely implemented in ANSI C code with the following advantages:
In principle, ColSim is designed to run under Linux or Unix. It can be used under Windows NT with some restrictions concerning the graphical in-and output. However, at the current date, this installation chapter deals only with the installation into a Linux system. With SuSE Linux, it is most easy to identiy the needed auxiliary program packages, but there should be no serious problems with other Linux versions.
A compressed ColSim program package can be obtained from http://www.colsim.org The file, e.g. colsim.11.tgz, depending on the version number, should be placed in the home directory. Then, it's advantageous to check that the following programs and packages are available in the computer system:
To finish the installation, change into the ColSim directory with cd ColSim and type INSTALL.This shell script only fails if the path to one's own home directory is not set and direct execution of programs present in the home directory by typing their name only does not work, rather ./name must be typed. If this is the case, add the path to your PATH variable or ask the system administrator to do it.
In order to check whether the installation was successful, we try a first simulation run with a very simple system. Type ColSim in the directory ColSim . In the following, this will be our reference directory, called the `` ColSim directory'', and all paths given are assumed to start from here.
Now all availabe ColSim systems are listed in a small grey window titled project_ organizer. The steps explained in the following apply to each system, of course, but now we choose a concrete example: The demonstration system ``Demo''. With a double click on ``Demo'', the system is selected. Note that this procedure can be abbreviated by typing ColSim Demo directly.
The first thing which is done now is the configuration
of the chosen system. This means, all the modules needed are collected,
translated, linked together and an exectuable program called sim
is created. See section ![[*]](cross_ref_motif.gif)
for details. Then, the ColSim
menu3.1 pops up, like shown in fig.). To select an item click
on it once with the left mouse button.
The next step is to select fig2dek, which starts the reading in of information about the system's modules, their interconnections and parameters. When this process is finished, the simulation can be started by choosing sim.
You may want to know what is happening now. Here, we give a short
overview, a more detailed explanation can be found in chapter .
Activating fig2dek started the conversion
of the xfig-graphics object Demo.fig into a so-called
simulation dek Demo.dek,containing all the
information for the simulation program in more compact form. In ColSim,
the input for a simulation run -the arrangement of pipes, storages,
pumps, etc., and all their parameters - is defined by a graphical
object drawn with the public domain graphics software xfig.
Take a look at the xfig-picture of the example system Demo
by selecting xfig in the menu. What you
see is something like fig..
Though it may appear confusing at first sight, it's in fact easy to survey after a while due to its modular structure. Our demo system consists of the following components, called units in ColSim:
. Generally, the modules like storages, pipes, controllers,
etc. belonging to a ColSim system are called "units".
They can appear more than once in the system and are assigned a temporary
unit number at the beginning of every simulation run to distinguish
them. However, the generic objects like e.g. the storage
are unique. They are called ``types'' and are associated with
a source code file mostly bearing the same name and describing the
physical behaviour of the type. Each type has a specific type number
given as well in its source code file as in its xfig-representation.
How the unit's parameters are hidden in the graphics file and how
new systems can be designed by editing parameters and rearranging
the units will be discussed in chapter .
To summarize, the xfig-representation of the system contains all information about which types are used in the system, how they are interconnected and how their parameters are set. The direct input for the simulation program, however, is the simulation ``dek'' containing the same information as the graphics file, but in more comprised form.
Choosing vim sim.dek in the ColSim menu opens a simple editor3.2 showing the simulation dek of the system under consideration. For each unit of the system, all parameters are listed, and also the interconnections with other units: The block which is titled ``INPUTS'' lists for every input the number of the unit and the outlet it is connected to. If an input is not connected, both entries are zero.
The file ./sim.dek is actually a link to the file ./projects/Demo/Demo.dek , but a copy can be found in ./cnv/sim_new.dek.
Selecting sim in the ColSim menu starts the simulation run. First, some information is put out about the units contained in this system and the order in which they will be called.3.3 The day of the year currently being simulated is printed and two gnuplot windows are opened. Hit the button sleep in order to halt the program execution at the end of the current day.
In the upper window, several system temperatures are plotted as a function of the simulation time in hours:
Choose the button xfig and see how the plotted curves arise from the connections of the gnuplotter's inlet boxes with the units outlet boxes. For the gnuplotter's connections, colored thin dashed lines are chosen which match the colors in which the connected quantities will be plotted latter.
In the second gnuplot window, the red curve corresponds to the control signal sent from the controller unit to the pump and takes the values of 1 or 0, depending on whether the pump is on or off.
The green line visualizes the power output of the heater. Note that this curve is multiplied with a scaling factor given in the legend of the plot. The blue curve shows the mass flow through the pump in kg/h, also with a scaling factor.
When the button wake up is hit, the program
execution continues. When it is finished, an output data file can
be found in the ColSim directory. Type less sim_out0.dat
to scroll in the file. The first column contains the simulation time
in hours, the second the mass flow through the pump in kg/h, the third
the heater power in W, the fourth the pump power in W, the fifth the
power arriving in the storage, the sixth the storage's losses to the
ambient in W, the seventh the temperature at sensor 2 in C. All data
are averaged over one minute. The printer output can also be changed
to integral values or current values, see section .
ColSim can also be used without the menu, i.e. without the shell script ColSim. Note, however, that this script also configures an environment for the special system given as an argument in the call ColSim SystemName, which means that special links are created and paths are set. Therefore, in the following, it is assumed that both the installation script as well as the ColSim script were executed once without problems. If this is not the case, you should take a look at the scripts e.g. with the help of an editor and try to execute one line after the other until the problem is detected.
If the scripts were executed once before, only a few commands are needed to configure the system.
In the following, all necessary steps of the configuration process
are listed for the example system Demo (which can
be replaced by any other system), but for a detailed explanation please
see section about the structure of ColSim. These steps
need to be executed if another system was simulated before.
To start the simulation of the example system Demo:
.In order to halt the simulation, type Ctrl s in the window where the process sim was started. With Ctrl q, the execution continues. Ctrl C terminates the program run.
The executable program sim can also be started in the background with nohup sim_copy &, where sim_copy is a copy of sim, since then another simulation can run simultaneously. However, the two processes shouldn't write to the same output files, i.e. not the same printers (there are printer 0..9) should be used in the systems.
The xfig graphics of a system serves as the input file for the simulation. Herein, all information about the implemented units, their interconnections, their parameters and their output variables is contained. With the help of an example system, the necessary xfig commands to design a new ColSim system are explained in the following4.1.
In the first subsection , the most easy modification of a system is demonstrated, namely to modify a unit's parameters. In the second subsection , we demonstrate how to construct a new ColSim system from scratch, i.e. putting together the units, defining the right interconnections, editing the load profile, etc.
In order to exercise these steps immediately, a new system will be created in order not to modify the reference systems. The following commands should be executed now:
with a pump´s parameters, displays the part of the information about
a unit which is contained but not visible in the xfig graphics of
the system:
for details. . Here, the parameters of the
unit can be edited. , it was explained that via
the lines in the xfig graphics of a system, connections are established
between the outlet of one unit and the inlet of another unit. However,
if an inlet is not connected and consequently receives no values from
another unit, the input inital value given here is used instead. Also
at the beginning of the simulation, the inital values are used for
all inlets where no actual input values are accessible because the
connected unit wasn't called yet. for details).
.A useful feature is the Sort .xfig function of the ColSim menu. It can be used to acualize the comments to parameters, in-and outlets which appear in the info_edit window by rereading them from the source code file belonging to the unit under consideration. To use it, the unit must be in the scrap file .xfig (use the Copy or Delete function of xfig with the right mouse button). Then select Sort .xfig and open the info_edit window to check for changes. Sometimes the number and meaning of parameters change in the course of improving ColSim.
.
In the following, there won't be individual instructions for menu based and manual operation, since all necessary commands were explained already for both approaches.
First, load Example.fig into a xfig window, adjust
the scale with the Zoom function (lowest
button in the left panel) to find a convenient scale and delete all
units, lines and text, except for the unit sim control.
This unit is needed in every system, since it sets beginning and end
of the simulation, see section .
In the following, a simple system with two hydraulic cycles including a solar collector will be constructed as an example. The units needed will be taken from the library in the folder ./cnv/lib, which contains the graphical representations of all units belonging to the SchichtSpeicherSystem, our reference system for the fluid systems. If this library is not available or not complete in your ColSim version, simply copy the units directly from SchichtSpeicherSystem.fig in the folder ./projects/SchichtSpeicherSystem. Of course, the chosen units can also be copied from other xfig system graphics if present, like e.g. StandardKollektorAnlage.fig in ./projects/StandardKollektorAnlage. Note, however, that the parameter settings have to be checked more carefully when combining units from completely different systems: E.g. the heat capacities of the fluids must be chosen uniformly for all units passed by the same fluid. Otherwise, the simulation results will be peculiar, though no explicit error will be reported.
Note that if a clear orientation of the units is wanted, the Grid mode of xfig is helpful (button in the bottom panel).
Now the hydraulic cycle will be established by connecting the mass- and heatflow ports of all hydraulic units with lines. Originally, mass- and heatflow had separate ports in the graphic, since they are balanced separately by the program also. However, since mass- and heatflow always come together, it is now sufficient to connect only the heatflow port (always the small odd numbers), whereas the corresponding mass flow ports (always the small even numbers) are connected automatically during the conversion of the system graphics to the dek file.
To draw the connecting lines, select the zigzag line symbol from xfig's left panel (the comment POLYLINE drawing appears at the top left corner). Then, a color can be selected with the button PenColor from the bottom panel. For best clarity of the picture choose blue lines for cold water and red lines for hot water, line width 3, and let the lines follow the grid lines with as few bending points as possible.
Note that the way the line takes is not important as long as it begins in an input box and ends in an output box, or vice versa. Input boxes have an inwardly facing arrow tip, output boxes an outwardly facing one. The exact placing of the lines is easier, when the mode Point Posn is used in finest resolution (button in the bottom panel), then all bending points and endpoints fall onto a 1/2 mm grid. To choose beginning and bending points of the line, use the left mouse button, to finish it use the middle mouse button.
Next, the data input units are connected. Here, it's only the weather unit but mostly there's also a load_profile enabling user defined input for various units.. Use yellow lines to
for a detailed explanation of the controller and
its various modes.
Fig. shows how your system could look like now.
In order to facilitate the comparison of the lines, they were drawn
next to each other here. However, more complicated system graphics
are better to survey when parallel lines of the same type (e.g. controller
connections) are drawn onto each other. In the xfig graphics you can
always use Move and afterwards Undo
to distinguish the lines.
After saving Example.fig, the conversion to a dek file can be started. However, when trying to convert a newly drawn system, very often error messages like the following appear:
When evaluating error messages, be aware that the unit numbers can
change during the conversion process, when a system with newly added
or differently arranged units is converted for the first time (see
section ). When working with the ColSim menu, it is
sufficient to close the old xfig window after the conversion process
and reload it by pressing the xfig button.
When working without the ColSim menu, the file ./cnv/sim_new.fig can be used to identify the unit numbers corresponding to the error messages. Once the conversion runs without errors4.2. this file should be copied onto the system xfig file in the projects folder.
If the conversion process was successful, the simulation can be started. However, there is no output yet informing about the proceedings in the system. For this purpose, the plotting and printing devices were designed. Copy the gnuplotter and one of the printers into Example.fig and connect the output variables of your choice to the plotter's and printer's input boxes.
Here's a suggestion for the connection of the plotter:
For each connected input, an entry appears in the upper right corner of one of the gnuplot window and also the chosen scaling factor is displayed here.
Connect some interesting output variables of various units to the printing device. Depending on what printer you copied into the drawing -printer 0,1 or 2 - the output file will be sent to the files sim_out0.dat, sim_out1.dat or sim_out2.dat, all in the ColSim directory.
Keep in mind that the printer is able to process the data it receives
by summing it up over a given time span, integrating it or finding
out the mean value. These modes can be set for each printer input
individually with its input inital value. See section
for details.
Not all output variables of a unit appearing in the info_edit window or in the source code of the type can be displayed in the system xfig picture. However, these boxes can easily be added to the respective unit in the following way:
) are present in
the standard ColSim versions. Look in the folder ./weather
and find out which data bases are available in your version, then
adapt the parameters in the weather unit and eventually
also in the sim control unit (the simulation time
span must be covered by the weather data).) use fit formulas which are
only reliable for temperatures above 0 C and which cause funny results
at e.g. -50 C. Then, a negative relative humidity may be calculated
from this which causes an error in the unit sending the message.
In the following all available types, i.e. system components like pipes, pumps, storages, controller, collectors, walls, heaters, etc. are discussed in detail. People who are not interested in the physics and the modeling of a type may only read the first part of each section concerning the operation of the type, i.e. how it is integrated into the system and how its parameters should be set. However, only those parameters are discussed that are not sufficiently explained in the source code comments (readable with the help of the info-edit panel).
Also for the in-and outputs, this source of information should be used primarily. If the meaning of an in-or output cannot be resolved from the comments, one should take a look at the source code describing the type under consideration (all source codes or links to the source codes are in ./src) and search for the part where calculated quantities are assigned to the in-or output.
You'll find that not all in-and outputs which appear in the info-edit panel are visible in the xfig picture of the unit. There are two possible explanations why an existing in-or output is not shown there:
for instructions about how to add the extra in-or output boxes you
need to the xfig picture.
In the simulation, time is discretized into small steps of size h.
Therefore, the fluid moving through the hydraulic units is also discretized
into so-called plugs: The mass of one plug is 
,
where 
is the mass flow of the fluid, here in kg/s,
and h is the simulation time step in seconds. So one
plug is the fluid amount which is passed from one hydraulic unit to
the next during one timestep h. However, at the inlet ports of the
unit, not the mass of the plug arriving is given but the current mass
flow in kg/s, which is internally multiplied with h.
On the contrary, the heat flow arriving at the inlet ports of a unit
is already multiplied with h and given in J=Ws,
i.e. it's really an amount of energy 
.
Nevertheless, we address both quantities as ''mass flow'' and ''heat
flow'', respectively.
The fluid pipes are used to simulate the transport of fluid between two other hydraulic units in a more realistic way than it would be if the units' mass flow in-and outlets were simply connected by lines. The heat loss to the ambient can be modeled and, with pipe3.c, also the ''deadtime'': If there is more than one node, the fluid entering the pipe in one time step is not the same which leaves the pipe in the same time step. This effect reduces the efficiency e.g. of solar collectors, since every time the solar pump stops, hot fluid is left in the pipes and looses its energy to the ambient instead of transfering it into the storage. The controlling mechanism should take this effect into account in order to maximize the efficiency.
There are two models for the pipe, the corresponding source code files are called pipe1.c and pipe3.c. Pipe1.c is a simple node model without an exact representation of the deadtime: In each timestep, the incoming fluid plug is mixed with the fluid of the first node. From this mixture, a new plug is taken and mixed with the fluid of the second node, etc. From the last node, the outgoing plug is taken. The losses to the ambient are calculated for each node while the plug is present. The temperatures of all nodes are stored in the deriv-arrays.
The alternative model, pipe3.c, is based on the opposite view: The incoming plug presses the fluid in the pipe forward without mixing with it. From the end of the pipe, the outgoing plug is taken. Then, the losses to the ambient are calculated for each node. Since after each time step, only the node temperatures are stored, there is an effective mixing within the volume of one node. Therefore, the form of the deadtime curve (temperature of outgoing plug as a function of time, after a jump in the temperature of the incoming fluid) can be varied from a step function form for infinite number of nodes to a smooth increase for only few nodes. Mostly, 5-10 nodes will be used. The deadtime itself is independent of the number of nodes and corresponds to the travel time of the plug through the pipe.
Both pipe models employ an Euler stabilization for the losses to the ambient: If due to the linearization of the actually exponential function (heat loss as a function of time) cooling below the ambient temperature level occurs, e.g. for large time steps h or large values of kA, the losses to the ambient are limited in such a way that exactly the ambient temperature is reached by the node under consideration. Therefore, the calculation is stable for all timesteps and heat transfer coefficients kA/l.
The diverter5.1 models the branching of a pipe (a T-piece) by splitting the mass
(and heat) flow into branch 0 and branch 1 (see fig.).
At the current time, this is the only mode of operation, so PAR1 must
be set to 1. How the fluid is distributed to the two branches is defined
by the control signal ctr = 0..1 from INP3: The flow in branch
0 and branch 1 equals the incoming flow, multiplied with ctr
and (1 - ctr),respectively.
Since at the current time, there is no hydrodynamical calculation
done for the fluid flow in the tubes, the flowdiverter is a very simple
component part. Note that every diverter must be matched by a mixer
reunifying the mass flow.
The mixer models a T-piece unifying and mixing the mass flow of two branches (branch 0 and branch 1), which were separated by a preceding diverter. At the current time, this is the only mode of operation, so PAR1 must be set to 1. OUT3 informs about the contribution from the indiviudual branches: Its signal is calculated from 1 - mp0/(mp0 + mp1), where mp0 and mp1 are the incoming mass flows from branch 0 and 1.
In every hydrodynamic cycle, there must be a pump to create mass flow. Since up to now, there's no hydrodynamical calculation of the fluid flow in ColSim, the pump is modeled in a very simple way: PAR1 contains mp_max, the maximal mass flow the pump can maintain. PAR 5 sets the mode of operation; If the pump is run in mode 0, it receives a control signal ctr=0..1 from INP3. The output mass flow is then given by mp_max, multiplied by ctr. Alternatively, the pump can run in mode 1, where the target mass flow is read directly off INP4. Mode 2 is a combination of these cases, where INP4 is used if it is connected, and INP3 otherwise.
With PAR2, the heat capacity of the fluid passing the pump is set. Note that it causes errors hard to detect when this heat capacity is not the same in all hydraulic units in one cycle. E.g. in the SchichtSpeicherSystem, all units belonging to the solar cycle, i.e. collector, pipes, solar pump and the hot side of the external heat exchanger, have their heat capacity parameter set to 3.8 kJ/kgK, corresponding to a mix of water and an anti-freeze agent. The hydraulic cycle containing the cold side of the external heat exchanger, i.e. the storage and the pump inbetween them, as well as all other hydraulic cycles in the system have their heat capacity parameter set to 4.19 kJ/kgK, that of fresh water.
The pump's electrical power consumption in primary energy units is
calculated from the given primary power consumption at maximal mass
flow (PAR3) and a power law whose exponent a
is given in PAR4: 
.
In the ideal case and for laminar flow, i.e. low mass flow of 25-100
kg/h, the exponent a is 2.
The pump's thermal mass can be tuned with PAR7, see next section for details.
In section , it is explained why in ColSim the simulation
of each hydrodynamic cycle starts and ends at a pump. Consequently,
the pump units are called twice in every time step: During the first
call, the new mass flow for this timestep is calculated like explained
above. The new heat flow leaving the pump is calculated from the pump's
heat capacity multiplied with its temperature.
Actually, the pump's heat capacity is not really a physical property
of the pump and its fluid content alone. Rather, it is meant to summarize
system capacities not considered yet (e.g. those of pipe walls, mixers,
diverters, tabs, sockets, etc.). The pump's thermal mass is set by
PAR7, which is then internally multiplied with the fluid's heat capacity
(PAR2) to give the pump's capacity. If PAR5=0, the pump's thermal
mass is set to the maximum mass of one plug, i.e.
.
The pump's temperature is taken from the array elementderiv_o[unit][1],which
was written during the second call of the pump in the previous timestep
(see section for an explanation on global fields
like deriv_o, deriv_n, qp_sum etc.).
When mass and heat flow output values are calculated, the outgoing energy is added to the array element qp_sum[unit][1][1], which summarizes the pump's output of energy.
In the second call of the pump in the same time step, it is checked whether the incoming mass flow equals the outgoing mass flow like calculated during the first call. If this is not the case, the simulation is stopped. Furthermore it is checked whether vanishing outgoing mass flow is combined with non-vanishing incoming heat flow or vice versa.
The incoming heat flow is added to the array element qp_sum[unit][1][2], which summarizes the pump's energy input. Then, the new pump temperature is calculated from the pump's initial energy minus the summarized output plus the summarized input, everything divided by the pump's heat capacity.
The source code for the pump described above is pump.dynamic.c. There is a non-standard alternative, pump.static.c in ./src/more_types, which works without a heat capacity for the pump. In principle, this pump model leads to the same results for a longterm simulation as pump.dynamic.c with PAR7=0 ( minimal thermal mass). However, the dynamical pump is preferable to the static one since the latter tends to accumulate small unwanted and unphysical energy gains which result from differences in energy in-and outflow due to the finite timestep h.
The solar collector model absorbs solar radiation and transfers the energy to a fluid cycle. Apart from the collector's geometrical properties, it is specified by:
, which is the ratio of two
heat transfer coefficients, namely that from the fluid to the ambient
air and that from the absorber plate to the ambient air. 
(
, which is defined as the ratio of the absorbed solar radiation to
the incident solar radiation. The name of this quantity results from
the fact, that is is some functional of the transmittance of the absorber's
glass cover 
and the absorptance of the absorber plate
or tube 
. In first order it is indeed the product of
and , but due to the effects of multiple
reflections, wave lenght dependence and the fact that the back reflection
of the absorber is diffus, there are corrections.
],
which summarizes the heat losses to the ambient. and 
for beam radiation of perpendicular incidence must be given in PAR2.
For flat plate collectors, this product is multiplied internally with
a function
describing the angular depencence
on the incident angle (see section ``Modeling'' for details).
In PAR14, the parameter b0 for this function must be given, e.g. -0.12
for a collector with two glass covers.
For a CPC collector, PAR14 must be set to -1, and a table called iam_table.dat
must be present in ./iam, giving the angular dependence
as a function of two incident angles, since the CPC has no rotational
symmetry. See section for details.
In PAR3, the product of F' and
for diffuse incident
radiation should be given. It is smaller than that for the beam radiation,
since it is already multiplied with the angular dependance and integrated
over all incident angles.
With PAR4=
and PAR5=
, the product of 
and is specified, where the Ansatz
is used, i.e. the product 
is assumed to depend on
the temperature difference between fluid and ambient.
In PAR7, the specific heat capacity of the collector fluid should be given. Note that the same value must be used for all hydraulic units in the collector cycle.
If PAR15 is set to 1, the file ./horizon/horizon_table.dat
is read which contains information about shading objects which reduce
the horizon (see section ).
The collector must be connected to a weather unit (see section ):
From INP4 the global irradiance on a horizontal plane (Igh) is read
in, from INP5, the diffuse irradiance on a horizontal plane (Idh).
From INP3, the ambient temperature is read.
The standard ColSim collector model is an 
-type model,
which means that n nodes are used in the flow direction and 1 node
in the vertical direction. So, the absorber plate and the fluid are
treated as one capacity, and the internal heat transfer between them
is not modeled. There is also a 
-collector model,
where absorber and fluid have different capacities, but stability
problems can occur in certain circumstances.
The collector consists of an absorber and a fluid pipe in thermal
contact with the absorber. Along the pipe, the collector is divided
into n nodes. Just like in the pipe model described in section ,
in each time step a fluid plug enters the collector pipe. In a loop
over all nodes, the energy balance for each node is performed and
the new node temperature is calculated. At last, the outgoing plug
is calculated. However, in difference to the normal pipe model, the
collector pipe receives also energy from the absorber plate. The energy
difference between solar gains and losses to the ambient per node
for one time step 
are described by the following formula
(see [1],p.271):
where 
is the absorber area, 
the number of nodes
and 
the current temperature of node i. The beam and diffuse
solar irradiance 
and 
onto the collector
which its slope and orientation as given in PAR8 and PAR9, are calculated
by the radiation processor r ad_processor.c (see
section for details). The function horizon.c
is called afterwards to check whether the direct sun is shaded by
something, e.g. the roof of a neighboring house (see section
for details.) Then, the function
for
the angular dependent transmission is calculated with the help of
inc_angl_mod.c, see section for details).
There are two standard collector models, collector1xn.c and collector.pipe3.c which are based upon the pipe models pipe1.c and pipe3.c, resepctively. Apart from this, they are equal.
The heat exchanger is a device inside of which heat is exchanged between two streaming fluids. Consequently. it possesses two mass flow inlets and two outlets. Up to now, the heat exchanger type can only model a counterflow heat exchanger, therefore PAR1 must be set to 1. With PAR2 and PAR3, the specific heat capacities of the fluids on the hot and the cold side can be given, respectively. E.g. if water with an anti-freeze agent is used on the hot side, the value could be something like 3.8 kJ/kgK, whereas on the cold side there will mostly be simple water with a value of 4.19 kJ/kgK. In PAR4, the overall heat transfer coefficient-area product in W/K must be given.
Our standard type is the static heat exchanger heatexchanger.static.c. Here, only the capacities of the passing fluids are regarded, and the heat exchanger itself neither has a heat capacity nor an internal volume. Consequently, no losses to the ambient are calculable. There is also a dynamical model, heatexchanger.dyn.c,but is hasn´t been in use recently.
The modeling is based upon the schematic adiabatic counterflow exchanger described in [1], p.178f. The kA-value given in PAR4 equals the theoretical heat exchange per temperature difference for two fluids with infinite heat capacity. Since in reality, the fluids heat capacities are finite and therefore their temperatures change during the heat exchanging process, the exchanged heat is smaller than this. However, from the kA-value, the effectiveness of the heat exchanger can be calculated, which is defined as the ratio of the actual heat exchange that occurs to the maximum possible one.
The storage is a central module of a fluid system, since it is connected
to all hydraulic cycles. There is only one standard storage type and
all varieties like storages with or without internal heat exchangers
or with stratifiying tubes can be modeled with the corresponding parameter
settings. However, for better survey different xfig pictures can be
used which remind of the storage specifications: The left side of
fig. e.g. shows a picture of a storage with internal
solar heat exchanger, the right side of fig. shows
one without internal heat exchangers, but with a stratifying tube.5.2
The storage´s heat loss coefficient to the ambient is given in PAR1, its volume in PAR2 and the specific heat capacity of the fluid stored in it in PAR3.
At the bottom of each storage in fig., the in-and
outlet for the solar cycle are drawn (INP1 and OUT1). At the storage´s
left side, the in-and outlet for the heater cycle can be found (INP5
and OUT9). The cold water inlet INP3 is at the right side at the bottom,
and the hot water leaves the storage through OUT3, drawn at their
top. It's also possible to connect a circulation or heating cycle
(INP7, OUT17), though the in-and outlet boxes are not drawn in this
picture. They can simply be added to the xfig-picture (see section
). Of course the position of the individual in-and outlet
boxes in the xfig-pictures does not matter, they can be arranged completely
differently for another storage model.
The height where in-and outlets are attached to the storage can be varied by editing the storage's parameters, e.g. PAR5 and PAR6 give the positions of the ports for the heater cycle, PAR11 and PAR12 for the solar cycle . Since the storage is modeled as a chain of n nodes (where n is given in PAR4), the positions are a number between 1 and n, where node 1 refers to the top of the storage, node n to the bottom of the storage.
Also the heat capacities of the fluid entering through the inlets must be adjusted, using PAR7 and PAR13.
The different pictures in fig. are only used for
better orientation. Whether the storage works with or without internal
heat exchangers is solely decided by PAR22:
). PATR14,15,16
must be set.
The generic storage device can be tuned to simulate two different kinds of storages, namely a normal storage and a stratifiying storage, which differ in the way the incoming warm water from the solar cycle is filled in.
. The presence of a
stratifying tube is assumed, which guarantees that the hot water entering
the storage is let out in a segment with similar temperature. By this,
convection is suppressed and the water in the storage is stratified
with temperatures rising from the bottom to the top. The solar system
works more efficiently since the solar (Vorlauf) temperature is always
kept low. Thermal losses of the storage to the ambient are smaller,
since only the water in the top region must be kept at high temperatures
for immediate use. Note that in this mode, PAR11 and PAR12 don't have
to be set, since the inlet node for the solar cycle is adjusted automatically
and the outlet node is always set to n.
As mentioned above, the storage is modeled as a chain of n nodes,
where n =10 normally. The nodes are characterized by their temperatures
stored in the arrays deriv_o[unit][i] and deriv_n[unit][i]
(see section for a general explanantion of the global
arrays), where unit is the unit number of the storage and i counts
the nodes. Since the storage is usually connected with several hydraulic
cycles, it will be called more than once within one timestep (see
section for information about the order in which units
are called). Only at the last call of each timestep, effects like
convection, heat conduction and thermal losses to the ambient are
calculated:
Convection sets in if the temperature at node i+1 is higher than that at node i. The physical picture is that bubbles of hot fluid start to rise inside the storage due to their lower density with respect to the surrounding colder fluid. They don't stop until they reach a level where the surrounding fluid has the same temperature. This convective process is modeled in the following way: If a non-vanishing convective heat transfer coefficient kA_down_up (PAR25) is given, the energy transfered in one timestep from the hotter node i+1 to the colder node i is given by the transfer coefficient multiplied by the temperature difference and the timestep h. If PAR25 is set to 0, maximal mixing between the two nodes is assumed, i.e. the temperatures are equalized in each time step.
Heat conduction transfers energy from hotter nodes to colder nodes, regardless of the direction. If a transfer coefficent for heat conduction is given (PAR26, in W/K), the energy transfered between node i and node i+1 is calculated from this coefficient multiplied by the temperature difference and the timestep. If PAR26=0, a literature value of 0.598 W/Km for the heat conductability of water at 20 C is used. This value is multiplied with the storage cross section area (calculated from the storage volume, PAR1, and its height, PAR27) and divided by the node thickness, i.e. the storage height divided by the number of n. Note that the kA-value for the heat conduction calculated in this way underestimates the real effect if the storage contains internal heat exchangers!
The storages's energy losses to the ambient are summarized in the heat transfer coefficient given in PAR1. If PAR27, the storage height, is set to 0, the energy losses per node in one timestep are calculated from PAR1 divided by the number of nodes, multiplied with the node's temperature difference to the ambient and the timestep h. For a non-vanishing value of the storage height, the losses of node 1 and node n at the storage's top and bottom are increased by 10 %, whereas the losses of the other nodes are reduced.
Every time the storage is called as a part of some hydraulic cycle, it is calculated how much energy and/or water is fed into the storage by this cycle and how much is taken from it.
If there's a heat exchanger connected to the hydrodynamic cycle under
consideration, the heat transfer from the fluid in the heat exchanger
to the fluid in the storage is modeled with an internal pipe model
based upon pipe1.c like described in section .
The heat exchanger is regarded as a winded pipe through which the
hot fluid travels from the inlet to the outlet. The pipe has as many
nodes as there are in the storage between inlet and outlet. So when
for each node the pipe's heat losses to the ambient are calculated,
they represent the heat transfered to this specific node of the storage
by the heat exchanger.
If no or a vanishing heat transfer coefficient for the heat exchanger of the solar cycle (HE2) is given, this coefficient is calculated from a fit function in case the heat exchanger is needed. This fit function uses the values of the incoming fluid's temperature, the node temperature at the inlet of HE2 and the mass flow through HE2. Note that the fit functions coefficents are determined from a fit to a 1500l tank.
If there's no heat exchanger connected, the fluid enters the storage
at the node where the hydraulic cycle under consideration enters.
In every timestep one plug enters (one plug equals the amount 
where mp is the actual mass flow in kg/s and h is the timestep in
s. See section for details) and mixes with the node´s
fluid content. Then, another plug with the node's old temperature
is sent from this node to the next neighboring node in the direction
towards the outlet of the cycle, and so on.
At every call of the storage unit, an energy balance for each node is performed. In order to reduce the accumulation of errors due to the limited machine precision, the different energy gains and losses treated above are stored separately in the field qp_sum[unit][i][j], where unit is the unit number of the storage, i counts the nodes and j counts the different energies. The actual node temperature follows from the node's energy divided by the node's heat capacity.Note that the energy balance for the whole system is checked by the main program after each time step.
The storage model described above corresponds to the source code storage4.c in . /src/more_types. There is an older version, storage3.c, where the energy transfer into the storage with heat exchangers is modeled with an external call of pipe3.c.
The heater or auxiliary heater is used to heat up fluids according to one of the following modes which are chosen with PAR4:
This type is modeled very simple, since it has no internal capacity except for the fluid´s capacity and consequently cannot represent heat losses to the ambient. A more realistic model should include an internal capacity, since with a very heavy heater, the system effectiveness can be lowered considerably if it starts up very often. Then, a great portion of the heating energy is only used to heat up the heater which afterwards looses its heat to the ambient in its inactive periods.
What the current heater model does is only to either add the set heating power to the fluids energy and calculate its new temperature or to set the fluid's temperature according to PAR2 or INP3 and calculate the heating energy needed for this.
The heating type is currently subject to larger modifications.
Pipe_air is used to simulate the thermodynamics inside a ventilated room whose volume is given in PAR1. The room is filled with humid air and there are in-and outlets for dry air, water steam, carbon dioxide, water and heat, where only the heat in-and outlets are shown in the xfig pictures. All the others are connected automatically. Pipe_air can be used in two ways:
and ). It balances
the energy exchange of the walls with the ambient and wall heatings
and sends the energy gained in each time step to the connected pipe_air
unit. In turn, the pipe_air unit calculates the new
equilibrium state and sends the current room temperature OUT16 back
to AirRad_node. So when simulating a building, pipe_air
is used to calculate the thermodynamics of the air inside and the
air exchange via the ventilation, and AirRad_node
balances the energies from the walls and windows.
With PAR13 and PAR14, the inital humidity and CO
content
of the air in the room can be adjusted. The initial room temperature
must be given in DERIV1, the ambient temperature in INP6.
Of course, several pairs of pipe_air and AirRad_node
units can be used to simulate a building with more than one room,
see section for details.
Pipe_air has several inlets: INP6 can be connected to a weather
unit (see section ) to get the ambient temperature,
otherwise the inital value of INP6 will be used. INP10,11,12 and 13
can be used to simulate the direct and indirect influence of people
in the building who add water steam and carbon dioxide to the air
by their breathing, bring in heat and turn on heat and water sources.
If the inputs are not connected, constant values can be given as input
initial values, but mostly they will be connected to a unit load_profile
(see section ), so a detailed profile of the occupants´
behaviour can be given.
This module originates from an earth heat exchanger developped by
Klaus Rittenhofer. At this time, it was the equivalent to the fluid
type pipe, except for the fact that not only water
and heat flow are balanced but also dry air, water steam and carbon
dioxide. Since water steam can change into water when the temperature
drops, more sumptuous calculations are necessary to determine the
thermodynamical equilibrium than in a pure fluid system. The thermodynamical
routines used are collected in thermodynamics.c, see section .
In contrast to the original earth heat exchanger, there is currently
only one node in pipe_air, i.e there are no gradients
in steam-and CO-concentration and there is only one temperature
in the room. In a ventilation cycle, the mass stream of the dry air
is kept constant throughout the cycle, though the mass stream of water
steam and carbon dioxide may change. When a plug of dry air, steam
and CO arrives at the inlets of pipe_air5.3, the routine GetMixedOutPlug is called which mixes
the incoming amount of humid air with the resident air and calculates
the new thermodynamical equilibrium state. If condensation occurs,
an iteration is necessary to determine the new amounts of steam and
water and the new temperature (see also section ). The
outgoing plug is taken from the room volume.
Pump_air is essentially a ventilator, which creates a mass stream
of dry air. In PAR1, the maximal mass stream mp_max
is set in [kg/h]. PAR2 and PAR3 serve to calculate the electrical
power consumed by the ventilator. With PAR4, the mode of controlling
the pump can be selected: In mode 0, the control signal ctr=0..1
is read off INP6 and the current mass stream of dry air is given by
ctr mp_max. In mode 1, the mass stream
of dry air is read directly off INP7. With PAR7, the thermal mass
of the ventilator can be modeled, see next paragraph for details.
Just like the pump in fluid systems, the pump_air unit of a ventilation cycle is called twice in each time_step: Once as first unit of the cycle to set the mass stream for all other units, and a second time after all other units to balance masses and energies sent out and received back and calculate the new pump_air temperature.
In the first call, the outgoing mass stream of dry air is determined
by the control signals (INP6 or INP7), whereas the mass streams of
steam and CO follow from the absolute humidity and the
CO -concentration inside the pump volume. This volume is
calculated from the capacity for dry air given in PAR75.4. For the inital time step, a steam content of the pump corresponding
to a relative humidity of 50 % and a CO -concentration
of 500 ppm is assumed. Afterwards, the steam and CO contents
during the first call are read from the old values of OUT24 and OUT22,
where they were stored during the second call of pump_air
at the last time step. There is no water content since the possibility
of condensation within the pump´s volume is neglected.
The temperature of the outgoing plug is that of the air in the pump's volume. It is given by the old value of DERIV24, where it was stored during the second call of the last time step.
In the second call of pump_air, its new temperature
is calculated from the total enthalpy contained in pump_air's
dry air and steam content and the outgoing and incoming energy flow.
The new temperature is stored in DERIV24. Also, the new steam and
CO contents are calculated and stored in OUT24 and OUT22,
respectively.
The heater_air is used primarily to heat up air, but can also be used to cool it down or to change its humidity or carbon dioxide content. With PAR2, five modes of operation can be chosen:
given in INP7. The temperature
is kept constant.). With PAR6 it can
be chosen whether the set humidity from INP7 is interpreted to be
in the range 0..100 (for PAR6=1) or 0..1 (other). The reason for this
feature is that the heater is often used to simulate the ambient:
In ColSim, only closed hydraulic or ventilation cycles are allowed,
therefore the warm air leaving the building through the ventilation
is sent through a heater which impresses ambient temperature, ambient
relative humidity and ambient 
content on it. For this
prupose, INP6,7,9 of heater_air are directly connected
with the weather unit (see section ),
which retrieves its information from a weather data base file. And
in some of these data bases, relative humidity is given from 0..1,
in others in %.
The heater_air is essentially as simple as the heater in fluid systems,
i.e. is has no internal capacities and cannot simulate thermal inertia
and energy losses to the ambient. However, since there are four mass
flows (dry air, steam, water and CO), some thermodynamical
calculations are necessary, using the functions contained in thermodynamics.c.
If condensation occurs, the steam content of the outgoing air is limited corresponding to 100 % relative humidity, and the spare water is stored in the heater. If water must be evaporated to rise the humidity of the outgoing air, stored water is used if possible. Otherwise, water is added to the heater at ambient temperature if INP6 is connected, assuming that the heater simulates the ambient. If INP6 is not connected, a temperature of the added water of 10 C is assumed.
The type heatexchanger_air is a very simple model of a mechanism to transfer heat from warm air leaving a building to fresh air entering it, i.e. to simulate a heat recovery device. At INP1, the heat flow of the incoming fresh air must be connected. OUT1 is the heat flow outlet of the warmed up fresh air, i.e. INP1 and OUT1 belong to the ``cold'' side of the heat exchanger. However, the ``hot'' side is not modeled in detail, but only the information about the temperature of the warm air from the building (INP6) and relative humidity (INP7) is needed.
In PAR1, the efficiency of the heat exchange must be given as a number between 0 and 1, e.g. 0.7 - 0.85. PAR2 must be set to 1, since at the current time only a counterflow heat exchanger can be modeled.
With PAR3, a bypass temperature can be set: If the temperature of the warm room air (INP6) used to heat up the fresh air is larger than PAR3, no heat transfer is made. This feature is necessary if the buildingis getting too warm e.g. at sunny days.
With PAR4, the limiting ambient temperature can be given where the heating is turned off. So if the temperature of the incoming fresh air exceeds PAR4, the heat exchanger is bypassed also.
The modeling is as simple as that of heatexchanger_static.c
for the fluid systems and based upon the same formula (see section
). However, here the effectiveness is given
directly and has not to be calculated from the heat transfer coefficient-area
product like in heatexchanger.c. The device has no
internal capacity and no heat losses to the ambient. Effects of condensation
are not taken into account yet.
Diverter_air is used to divide a stream of air into
two, according to a control signal 
received from INP6.
The outgoing mass stream at branch 1 is mp_in,
with the incoming mass flow mp_in. Consequently, the outgoing mass
stream at branch 2 is (
mp_in. This is valid for
dry air, steam, water as well as and 
and also for the
heat flow.
The parameters are only needed for the hydraulic calculation, which is not active yet.
The mixer_air is the counterpart of diverter_air:
For every diverter, there has to be a mixer reunifying the mass and
energy flows. However, in mixer_air there are more calculations to
be done, because of the possibility of condensation inside the mixer.
If the condensation point is approached, an internal iteration is
performed in order to determine the new thermodynamical equilibrium
of the mixed state, i.e. the new temperature and the masses of steam
and water (compare section ). The mixer stores the
condensed water and tries to evaporate it again in the next time step.
No parameters have to be set. Note that OUT9 gives 
,
the relative contributions of the two incoming branches to the outgoing
mass flow:
, where 
and 
denote the incoming mass flows.
This type is subject to larger modifications at the current time.
This type is subject to larger modifications at the current time.
A sim control unit must be present in every system
to be simultated, since it sets start and end of simulation; In PAR1,
the start date must be given in the format yymmdd,
where yy is the year, mm the month and dd the day. Likewise, PAR2
denotes the last day to be simulated. Note that these dates refer
to the weather data base, i.e. in the chosen data base (see section
), the data files for this time span must be availlable.
Note that if the time span to be simulated crosses the turn of the year, the simulation carries on with january, the first, etc., but the year is not increased by 1. This makes sense, since the weather data bases mostly contain only data for one year. To simulate e.g. a heating period, the combination of e.g. PAR1=911001 and PAR2=910430 is possible.
With PAR3 and PAR4, the start time and end time can be set, respectively. The format is hhmmss (hours, minutes and seconds).
With PAR5, the maximal error in the system energy balance can be set.
PAR7 gives the simulation time step h in seconds. Note that if it is chosen too large, some units may report warnings refering to stability problems: Since in ColSim, the Euler method is applied in order to solve the differential equation set describing the status of the system, the iteration is only stable if the physical time constants involved are much larger than the simulation time step h. If this is not the case, warnings or error messages are printed and the program execution may even be halted. Then, PAR7 should be reduced considerably in the next run. There´s no use in trying to keep it as close to the instability limit as possible since then the simulation results will most certainly depend upon the simulation time step which is unphysical.
If PAR8>0, the fast iteration mode is activated and PAR8 is interpreted
as the number of time steps which are skipped if possible. See section
for details.
Note that the sim control type is not a real type in the sense that it is represented by an own source code file, but it is part of the main program main.c: The main program, knowing the type number of sim control, reads in its parameters and uses them to control the simulation.
Controller units are used to trigger pumps, ventilators, diverters, heaters and heatings in order to achieve e.g. a given set temperature in the storage or a certain air quality and temperature in a building. Since ColSim was mainly developped to serve as a simulation environment for developping and testing controlling algorithms, there are many variants of the controller type:
The default controller for fluid systems is ./src/more_types/controller.c and it can control the pump of the solar collector cycle or alternatively the mixer of a heating cycle.
With PAR1, the mode is selected:
, where the constants 
and 
are given by PAR4 and PAR6, respectively. The term 
is the difference of the collector temperature and the set temperature
(PAR5). The term 
is an integral of over
all past time steps, with a limitation to 2000. Here, the pump is
turned off if the collector temperature (INP1) is lower than the storage
temperature (INP2) plus a hysteresis term (PAR3).The control signal
is limited to a minimum value given by PAR8.
(see case (a)) is calculated as collector temperature
(INP1) minus storage temperature (INP2) minus PAR5. Otherwise, the
control signal is calculated just like in case a).
This fit formula is a result of a static optimization of the mass
flow as a function of the global irradiance onto the collector plane
and the temperature of the fluid entering the collector, which is
identified with the storage´s temperature (INP2) here.concentration as indicator for the quality
of the room air and also is able to control the temperatures of several
rooms by calculating a heating power, depending on the actual room
temperatur in comparison to the set temperature. Again, with PAR1,
the mode is selected:
value
in PAR13 and the measured is read from INP7. If the
is lower than a lower limit given in PAR14, the control
signal for the ventilation is set to 0. If PAR9=1, the control signal
stays constant, independent of the value. This constant
value can be set in PAR10. For the heating, a kI-control is used,
where the parameters kP and kI must be given in PAR4 and PAR6, respectively.
PAR5 contains the maximal total heating rate.
the fuzzy ventilation control
parameter: 
=0 causes the maximal economic ventilation
program with the lowest mean ventilation rate and =1
causes the maximal comfortable ventilation program with the highest
mean ventilation rate. With PAR4, the cooling mode can be turned on,
i.e. the ventilation is enhanced if the temperature specified by PAR6
exceeds PAR10. With PAR7, the inertia of the heating control signal
can be varied (mostly set to something like 0.7 %). With PAR8 and
PAR9, the amount by which the fuzzy sets for and relative
humidity are shifted for <1 is specified. The shifting
is proportional to (1-). PAR14 specifies the
concentration in the ambient since only the difference of the measured
concentration in the room to that in the ambient is
used to calculated the ventilation signal. With PAR2, the air heating
mode can be turned on, which means that the ventilation is enhanced
if the room temperature does not reach the set value: Since with the
air heating, the air temperature is always limited to 50-55 C, the
ventilation must be sufficient to transport enough heating power into
the room. If PAR2=1, INP1 is interpreted as the measured temperature
and PAR12 as the set temperature for the air heating.
With the help of the gnuplotter unit, the state of the system can be observed during a simulation run. Any quantity which corresponds to an output box in the xfig-picture of the simulation dek can be connected with one of the gnuplotter's input boxes and will be drawn then as a function of time during the simulation run. There are two exceptions; the mass and heat flow outlets cannot be connected with the gnuplotter (or printer), since this would be interpreted as mass and heat flow into the plotting devices and definitely cause severe damage... Sometimes, there are special outlet ports where information about the current mass or heat flow can be obtained.
On the other hand, not only those quantities can be plotted which
already have visible output boxes in the xfig-picture, but all those
which are listed as outputs in the info-edit window of a unit (i.e.
which appear in the comment part of the source codes of the corresponding
type). In section it is explained how the output boxes
needed can be added to the xfig-picture.
The gnuplotter unit, using the Public Domain program ``Gnuplot'', draws two diagrams: Plot 0 for INPUT 1..5 and plot 1 for INPUT 6..10. The inital values of INP1..10 define the scaling factors used for the plot. These scaling factor are shown in the legends of the plot, together with the unit number and outbox number which is plotted. In Plot 0, also the names of the plotted output quantities are printed in the legends. This information is taken from the comments to the output variables of the specific unit. These comments can be edited with the help of the info_edit window.
Note that INP1..5 and INP6..10 must be connected subsequently, since for the sake of speeding up the simulation, the program stops the output of data to the plot file when it encounters an unconnected input.
With PAR2, the ``refresh time interval'' can be chosen: The plot is drawn completely new after every refresh time interval. Since the simulation continues meanwhile, the lines drawn become longer and longer after every interval up to the chosen maximal time span (PAR1), where a new plot is started. In this way, it's easier to follow the progress of the simulation, compared to the alternative that the lines are drawn at once for the whole maximal time span (PAR1=PAR2). However, the latter parameter choice makes the simulation run considerably faster. The fasted run can be achieved by turning off the gnuplot output completely by setting PAR7=0.
If PAR8=1, the plot ranges are chosen automatically and adapt themselves continuously to the data. If PAR8=0, the ranges have to be set with PAR3..6. If PAR9=1, the line `` continue ?? no:echo n>no, yes:echo y>no, cancel:echo c>no'' is plotted for every day during the simulation run. Its meaning is that the simulation can be terminated in a controlled way without the menu by typing echo n>no in a text window. By this, the letter n is written into the file no, which is checked by the main program after each simulated day.
The plot file is called ,,plot.dat''. It contains data from the current day, which can also be plotted with an external call of gnuplot: After typing ``gnuplot'' in some text window, type e.g. plot ``plot.dat'' using 1:2. This command plots the second column of the data file as a function of the first column. The command plot ``plot.dat'' using 1:3 with lines will plot the third column as a function of the first column, with the data points interconnected by lines. For more information on gnuplot try the online help by typing help.
The equation type can be used to apply an arbitrary
formula to several input values and receive the results as output
values. However, for defining this formula, the source code file equation.c
has to be edited. The best approach is to copy the file from ./src/more_types
into the folder of the current project. Then, in the .cfg-file
of the project, a link has to be set to this file, otherwise the original
source code in ./src/more_types is read. See section
for details..
Now, the local file equation.c in the projects folder can be edited: It contains a switch/case structure, where PAR1 is the switch used to decide which case is active. Now either use an existing case and modifiy the commands there or insert a new case between the last current case and the default case. If n is the number of the current last case, the new case has to look like this
case n+1:{variable definitions; commands; setting the OUT variables; break;}.
The input variables are in input[i], the parameters can be addressed by PAR (i) and the output variables by OUT (i), where the latter two expressions are macros defined in ./src/global.h.
PAR (1) must be set to the case number of the formula to be applied.
The other parameters can be used for defining the formula. If more
INP or OUT boxes are needed than there are in the xfig picture of
the equation unit, simply add those you need by following
the instructions in section .
Note that after editing equation.c, you have to use the make button in the ColSim menu to activate the changes.
The weather unit reads data from the weather data in ./weather and sends it to its OUT variables, where it can be used by other units which need information about the solar irradiation, the ambient temperature and humidity, etc. However, note that in principle all kind of data can be read by the weather unit, i.e. it may also be used as a substitute for the load_profile unit e.g. if a different load profile should be defined for every day of the year.
Currently, the weather unit expects to find subfolders in ./weather whose names are composed of try and a two digit number, e.g. try05 or try14.5.5 The number is specified in PAR5 of the weather unit. Inside these subfolders5.6, a weather data file for each day of the year (or at least for all days which will be simulated) should be present, and its name must look like 970220.dat, i.e. it contains the number of the year, the month and the day.
Note that the original try data does not look like that, rather it is a single file for all days of the year, containing a header with information about the location where the data was recorded. Moreover, there are many more data columns than in the ColSim try data files. The original files are useful for the information about the locations (see explanations to PAR3 and PAR4). But if you only have these original files and no data in the ColSim format like explained above, you can use the convertion programm try_convert.awk (see comment part at the top of the file for how to use it). Normally, it is contained in a try subfolder, otherwise contact your suppliers of ColSim.
In PAR1, the timezone (with respect to Greenwich, east positive) where the weather data was measured should be given. E.g. Germany is east of Greenwich, therefore PAR1=+1 hour. PAR2 contains the time difference between two lines of the data file. In PAR3, the geographics length of the measurement place with respect to Greenwich must be given, but here east is counted negative. The geographical latitude must be given in PAR4.
With PAR6, it is determined whether the data is interpolated or not. If PAR7 is set to 1, a warning is written if the time difference between one data line and the next does not equal PAR2.
The OUT variables of the weather unit correspond to the data columns of the files in the try subfolders, i.e. if the ambient temperature is the first column after the time column, it can be read off OUT1 of the weather unit.
The printer unit writes the data it receives through its inputs to the file sim_outn.datin the ColSim directory. The number n is given by PAR1 of the printer. PAR2 is only read if PAR3=0, then it gives the print interval in seconds, i.e. the time difference between two subsequent lines in the output data file. Normally PAR3 is used to define the print interval and there are 8 possibilities to choose from.
With PAR4, the format of the time variable in the data files can be chosen: If PAR4=1, the time is given with a twelve digit number, where year, month, day, hour, minute and second are each represented with two digits. For PAR4=1,2,3,4 the time is given in seconds, hours, days or minutes, respectively, where the counting always starts at the beginning of the year.
If PAR5=0, the data is not modified, but if it is set to 1, it is divided by 1000 and 3600, which can be used to transform an energy output in J or Ws into kWh. However, this mode is only active if the data is integrated or summed up. This can be achieved by setting the input inital values:
If the input inital value of INP1 is 0, the variable connected to INP1 is averaged over one print interval (and printed into the first column after the time variable). For an inital value of 1, the momentary value at the time where the dataline is written is used. For a value of 2, the variable is integrated over one print interval, for 3, it is summed up over one print interval.
Originally, the unit load profile was designed to
model human behaviour concerning the consumption of warm water. The
unit reads a data file, load.SystemName.dat in the
folder ./projects/SystemName, which is linked to load.dat
in the ColSim directory. In this file, there is a entry for every
change in the mass flow and the temperature of the demanded warm water.
like table shows. The data read from the file is then
sent to the outlets of the load profile unit and hereby
made available for other units, e.g. the mass flow can be sent to
a pump and the set temperature to a control unit which controls a
mixer mixing hot and cold water.
However, load profile can be used in a much wider
context now, namely to imprint almost any input quantity onto the
system. E.g. the reaction of hydraulic devices like storage or pipes
to sudden changes in the ambient temperature can be tested by connecting
the ambient temperature input not to the weather unit but to the load
profile, where a designed temperature course is read from a data
file. Also, inhabitants of a building can be simulated with the help
of the load profile by making entries for the water
steam, and heat emissions by the people, as well as
the indirect loads like steam production by plants and wet clothes
and heat emissions by electrical devices.
In table , the structure for a simple version of the
data file is shown. The maximum number of columns after the time column
is OUTMAX0, a number globally defined in the file ./src/global.h.
The maximum number of lines is LOAD_SIZE, also defined in ./src/global.h.5.7 In the first line, the names of the quantities listed below should
be given (there must be as many words in the first line as data columns).
The second line stays empty. Beginning from the third line, the data
entries follow.
The format of the numbers is not important except for the first entry in each line: the time. It must be given either with 6 digits or with 7 digits, where the first two or three digits, respectively, count the hours, the following two the minutes and the last two the seconds. So e.g. 103000 means half past 10 on the first day.
The total time span defined with the data file is read off PAR1. It is considered as cyclic, i.e. when one time span has elapsed, the data file is read from the beginning to give the input for the next time span.
| time | mp | Tset |
| 000000 | 0 | 10 |
| 063000 | 120.0 | 40 |
| 064000 | 0 | 10 |
| 130000 | 85.0 | 50 |
| 130500 | 0 | 10 |
| 180000 | 150.0 | 40 |
| 182000 | 0 | 10 |
The load profile unit can have inlet ports (not shown in the xfig picture), though they cannot be connected to other units. Rather, the input variables always stay at their input inital values, which can be used to divide between working days and weekend: If the input initial value of INPn is set to 1, the corresponding output value OUTn is set to 0 on weekends. Whether or not it's a weekend is decided by the main program which knows beginning and end date of the simulation.
Note that each outlet of load profile corresponds to a data column of the data file, where the correspondance is one-to-one with the exception that OUT6,7,8 are left out since they are reserved for the energy balance. So OUT5 presents the fifth column of load.dat, and OUT9 the sixth column.
The function rad_processor (contained in the source
code file rad_processor.c) is called from within
types which balance solar energy, i.e. the solar collector and the
wall type. It is used to calculate 
and 
, the
diffuse and beam radiation incident onto a tilted plane from 
and 
the global and diffuse irradiation onto the horizontal
plane. The collector as well as the wall type call the radiation processor
and provide it with information about and the
albedo of the ambient, the current time, the location and the slope
and orientation of the absorbing surface.
The first thing the radiation processor does is to calculate the solartime,
the hour angle and the declination. From this, the incidence angle
of the beam radiation onto the absorbing plane is
calculated (the angle between the beam and the normal to the plane).
With
as the incidence angle of the beam radiation
onto the horizontal plane, is given by
. If the sun is low, a correction is applied since the term
diverges for
. Though 
is very small then, it does not vanish completely for
but
still is visible due to the diffraction in the atmosphere.
Then, is calculated from
,
where 
is the slope of the surface (0 for horizontal
surface). Another contribution to 
the global irradiation
onto the horizontal plane, is 
, the irratiation reflected
back from the ground. It is given by
where 
is the albedo of the ambient. All formulas
origin from [1].
If a special horizon is defined, i.e. if PAR15 of collector or wall
is set to 1, and are recalculated by the function
horizon (see section ). Also, a shading
value is calculated which is 1 or 0 and either extinguishes the beam
radiation totally or leaves it unchanged.
In the new version of the radiation processor, also
the radiation which is transmitted through a glazing is calculated.
From the collector or the walls, the value 
is delivered
which characterizes the angular depencence of the transmittance. It
is used during the call of the function Incidence angle
modifier (see section ) which returns multiplicative factors
for the reduction of beam and diffuse radiation by the glazing. Note,
however, that these values still have to be multiplied with the transmission
factor at vanishing incidence angle.
The radiation processor returns all the calculated information about the irradiation onto the tilted surface and in addition also the angles describing the position of the sun, absolute and relative to the surface.
The source code file thermodynamics.c contains several functions describing thermodynamical relations. There is e.g. the function Get_Temp_from_enthalpy which is used to calculate the temperature in a volume from the enthalpy and the masses of dry air, water steam and water contained in it. Some functions also contain fit formulas, e.g. Get_p_steam_s which calculates the partial pressure of water steam in saturated air as a function of temperature. This formula is valid between 0 and 100 C (see e.g. [2] p.103f).
The maybe most important function of thermodynamics.c is called GetMixedOutPlug: It calculates the mixing of an entering plug of humid air into the air volume corresponding to one node, and determines temperature and composition (dry air/steam) of the outgoing plug. Here we give a short outline of the calculation:
First, the enthalpy of the plug is added to that of the node to give
, likewise its masses of dry air and steam are added
to those of the node, giving 
and 
.
The resident water of the node was temporarily added to
Then, the absolute humidity of the mixture, 
, is calculated
from
. Now, there are two
possibilities:
< 
, where is the absolute
humidity of the saturated state, calculated from the function Get_xs_from_enthalpy2(which
depends upon the enthalpy of the humid air, divided by the mass of
dry air). This is the easy case since there is no condensation, therefore
no water (in liquid form) is present. The new temperature simply follows
from the function Get_Temp_from_enthalpy, since
all masses are known (the mass of dry air is always preserved, the
mass of steam is times the mass of dry air and the mass
of water vanishes). > . Now there is a problem: We know that
condensation occurs during the mixing and there is an unknown amount
of water in the system. We know that equals
then, but the problem is that the we calculated is most
probably wrong: We used the function Get_xs_from_enthalpy2
with the argument
, but we know now that
also contains the enthalpy of water and Get_xs_from_enthalpy2
expects only the enthalpy of humid air (i.e. dry air and steam) as
an argument.
. On the other
hand, the new temperature can only be calculated if the masses of
steam and water are known, and for this we need the right
of the equilibrium state.
like
calculated above and use it to calculate temporary values for
and
From these
masses, a temporary temperature 
can be calculated with
Get_Temp_from_enthalpy,since the total enthalpy
is constant and known. From the new temperature, the
enthalpy of the humid air can be calculated from
with 
as the specific heat capacity of water. Now
we have a better input value for Get_xs_from_enthalpy2
and can calculate a closer guess for , etc. The iteration
is stopped as soon as the temperature changes by less than 0.0001
C. In thermodynamics.c there is also the function Get_alpha_air which calculates the heat transfer of the air streaming in a pipe to the walls of the pipe.
In this chapter, it is explained how ColSim works from the configuration to the individual steps in the simulation run. It's not absolutely necessary to read it if one uses the menu based configuration and simulation and only works with the standard systems (SchichtSpeicherSystem, StandardKollektorAnlage, etc.) with modified parameters and slight rearrangements of types.
However, for people who have to use the command line execution of system configuration and simulation or who intend to modify parts of the source code or design completely new systems, this chapter is a ``must''.
The installation command INSTALL, which is executed directly after unpacking the ColSim programs, is a simple shell script. Its tasks are:
In the following, the processes started by the call ColSim Systemname are explained in detail, again with the help of a test system for demonstration .
)
to the file load.Systemname.dat in the folder
The advantage of the special configuration method described in the following, is that it is highly flexible: The source code file which is used to describe a type in the system can be exchanged by an alternative one very easily. In this way it is possible to modify the source code files and test the results by working with local copies in the projects folder, leaving the original files unchanged. Then, the modifications will only affect the current project and not all other ColSim projects, too.
So the main task of the configuration routine config is to put together the right source code files needed for the simulation of the current system and to prepare the right auxiliary files. By the xfig graphics file, the types appearing in the system are determined, but there can be different source code files describing the same type: The pipe e.g. can be described with pipe1.c, pipe2.c or pipe3.c in the folder ./src/more_types, which differ in the way the physical processes in the pipe are modeled. In the file ./cfg/default.cfg, the default settings are given. Take a look at it with less ./cfg/default.cfg to study its structure:
).).
Moreover, several files are created, mostly in the folder ./src:
for details).
The PRIORITY value will be used by the program unit_order_init.c
which, at the beginning of each simulation run, determines the order
in which the units will be called in every time step. The HYDRAULIC
variable describes the hydraulic function of the type. ). For every unit, it
calls the function type_call, which determines the
type of this unit and calls the right function describing the type.
In section , the conversion process was roughly explained
already. The executable program which is started with the button fig2dek
in the ColSim menu is called cnv.exe and can be found
in the directory ./cnv. The source codes are in ./cnv/src.
This program opens the text file . /cnv/sim.fig (which
is a link to
./projects/Systemname/Systemname.fig). Take a look
at sim.fig with the help of an editor or with less
sim.fig in the folder ./cnv.
Although the parameters are not visible in the xfig graphics of the
system, they appear in this file. How the parameters are edited is
explained in chapter . What cnv.exe
does is to read the information about the system from sim.fig
and to write it to sim_new.dek in more compact form:
Then, take a look at sim_new.dek. For every unit of the system, all parameters are listed here, and also the interconnections with other units in the following way: The block which is titled ``INPUTS'' lists for every input port of the unit under consideration first the number of the unit, then the number of the outlet it is connected to. If an input is not connected, both entries are zeros. In this case, the input inital value, given in the block below, is assigned as a fixed value to this input.
There is one extra thing that fig2dek does
apart from starting cnv.exe: It copies the file ./cnv/sim_new.dek
to ./projects/Example/Example.dek and sets a link
from sim.dek in the ColSim directory to the dek file
in the projects folder. This step is not necessary when doing a command
line execution of a simulation. It is sufficient to link sim.dek
in the ColSim directory to sim_new.dek in the folder
./cnv (see section ).
When the simulation program is started by using the sim button in the menu or by typing sim in the ColSim directory, the main program is started (source code main.c, in the folder ./src like all functions discussed in the following). After initializing variables and arrays, it calls as the first function dek_reader. c. The latter opens the simulation dek ./sim.dek and reads in the information about how many units and which types are used in the system, their parameters and their interconnections. The parameters of the unit sim control, which must be present in every system, are used immediately for calculating beginning and end of the simulation time in seconds.
Then, the function unit_order_init (source code file unit_order_init.c) is called. It determines the order, in which the individual units will be called in every time step by creating an onedimensional array called unit_order which contains the unit numbers to be called subsequently. For this purpose, it uses the header file unit_order_init.h which was created during the configuration process. In this file, a PRIORITY number is assigned to each type, except for sim control. Types with low priority numbers are called first within one timestep in the following way:
. Here,
is the fluid mass per time being pumped through the cycle and
is the simulation time step. Every hydraulic unit succeeding the pump
receives the plug and sends it on to the next unit within the cycle.for details). After one hydraulic cycle
is completed, the next pump and its cycle are calculated.
illustrates what happens at such a branching point: The program init_set_mp
first continues with an arbitrary unit succeeding the diverter. Several
units later, a mixer must appear, since in ColSim only closed hydraulic
cycles are allowed. If it is found that the mixer's output cannot
be calculated since no current input values are at hand, the program
returns to the diverter and continues with the second branch. Also
branchings inside branchings are possible.
When the process of determining the right unit order is completed and the array unit_order is filled with all unit numbers to be called subsequently during one time step, the simulation starts. The main program calculates start and endtime of the simulation and prints out the actual day. In the main loop over all simulation time steps, a second loop is contained which runs through all entries in the array unit_order, i.e. it runs through all units in the system according to their previously determined order. Within this loop, the function type_call.c is called, which was generated during the configuration process. In type_call, first the type is identified which corresponds to the current unit number, then the function describing this type is called. To most of these functions, the following important variables and arrays are handed over which type_call itself receives from the main program:
), an output box can be drawn in the xfig
picture of the system. This box can be connected to a gnuplotter or
a printer, by which information about the specific output variable
can be visualized or stored (see chapter for instructions
on such manipulations).
Since the calculation of the units in ColSim proceeds according to
the mass flow, the predecessor unit's newly calculated output for
the actual time step can be used as input for the current unit in
the same time step. If a unit has more than one predecessor unit,
e.g. a mixer or a heat exchanger, it is called several times until
all input values are updated (see section ).
When the input is complete, the function starts calculating the behaviour
of the current unit, then actualizes its column of the output array
OUT(i), if necessary sums up the lossed and gained
internal energies in qp_sum to calculates the new
temperatures and eventually returns control to the main program. More
about the physics and modeling of the types in chapter .
Within the loop over all entries in the array unit_order, all units in the system are calculated according to this previously determined order. Afterwards, at the end of each time step, the main program performs an energy balance with the help of the function energy_outcome.c which balances the entries in OUT(i),i=6,7,8, summed over all units with heat flow. For more complicated types like the storage and the collector, more detailed energy balances are performed. If a certain tolerance in the balance is exceeded, the program execution is stopped.
The last commands in the time loop of main are concerned with switching the out_o with the out_n array and the deriv_o with the deriv_n array. Then, the next time step is calculated, until the end of the given simulation time interval is reached.
Here, we deal with the case that for a special system called Systemname a standard type is exchanged with a non-standard type or a modified standard type, but the name of the type stays the same. E.g. in the simulation of Systemname instead of the standard fluid pipe ( pipe2.c or pipe3.c. depending on the ColSim version) pipe1.c should be used.
Then, the only thing necessary is to edit the configuration file of the system, in this case ./projects/Systemname/Systemname.cfg.
If there is no entry yet for the pipe, i.e. the standard pipe model mentioned in ./cfg/default.cfg is used, the following line must be added:
pipe2.c src/more_types/pipe1.c
TYPE.
Note that the reason why the generic pipe type is called pipe2.c
here and not simply pipe.c is that ``pipe'' is
a reserved name in Linux operating systems. Now save the file and
exit the editor.
The configuration process can be started by closing the ColSim menu for the system and typing ColSim Systemname again. Alternatively, it can also be done without closing the menu by changing into the folder ./cfg and typing: config ../projects/Systemname/Systemname.cfg. This program sets the links listed in ./cfg/default.cfg and ./projects/Example/Example.cfg. Afterwards, a new compilation must be performed, either with the make button of the ColSim menu or by typing m in the folder ./src.
By this we mean a type which didn't exist before, i.e. which receives a type number not used before. The easiest way to create such a new type is to copy the source code of an existing type as similar as possible and adapt the comment part at the beginning of the function. This comment part is important for the configuration process. Take a look at ./src/init_type_def_string.c and choose a type number not used yet. Make an entry with the name of the new type. If you append the type after the last existing entry, correct the number of types in the program lines below.
Then, a PRIORITY and HYDRAULIC number must be chosen with the help
of the information in section . Next, the comments to parameters,
in-and outlets should be adapted, since they appear in the info_edit
window later.
Now the program code, written in ANSI-C follows. Note that there is
an init_flag, which can be used for commands only
to be executed once at program start. Please read chapter
for information about the global arrays. Note that the energy balance
will also be performed for the new type, therefore, OUT 6,7,8 must
be set correctly. If it´s a hydraulic or ventilation type with mass
flow, it consists of one or several nodes and the array DERIV
(i) must receive the actual node temperatures. See ./src/global.h
for preprocessor definitions and macros.
At the end of the function characterizing the new type, the array OUT(i) (i.e. out_n[unit][i]) must be filled with the calculated values according to the explanations given in the comment part. These values can be made accessible to other units in the following way:
A xfig object must be created corresponding to the new type. Again,
the best way is to copy an existing unit from a xfig graphics of a
ColSim system and modify it. Follow the instructions in section
for opening the compound, then the individual parts of the unit can
be deleted, modified or replaced with new graphical symbols. Also,
the right in-and outlet boxes (corresponding to the in-and outlets
used in the source code) can be created by changing the numbers in
the old ones, if necessary. If finished, create a compound object
again and copy it into the xfig graphics of the system which should
contain the new type.
Now all units connected to the outlet boxes of the new type should be able to receive the values written to the out_n array in the program code. First, try to set the parameters of the new type by deleting it from the system graphics with the right mouse button, then choose sort .xfig in the ColSim menu. If you open the info_edit window afterwards, the right number of parameters together with the right comments (like written in the source code file) should appear. Edit the parameters and try to convert your system graphics with fig2dek afterwards,
There are three reference systems at this time:
This document was generated using the LaTeX2HTML translator Version 99.1 release (March 30, 1999)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 1 -local_icons man.tex
The translation was initiated by Christof Wittwer on 2002-05-31
