SimuPlot 5 Manual

1. Introduction ............................................................................................................................ 2
2. A quick demo ......................................................................................................................... 2
3. The SIMULATION toolbox................................................................................................... 3
3.1 The SIMSPEC window .................................................................................................... 3
3.1.1 Variables (upper section, Fig 1) ................................................................................ 4
3.1.2Constants (middle section, Fig 1):.............................................................................. 4
3.1.3 Algorithms and model equations (bottom section, Fig 1): ........................................ 5
3.1.4Compile & Run button ............................................................................................... 5
3.1.5 Menu functions of the SIMSPEC window ................................................................ 6
3.2 Run a simulation............................................................................................................... 8
3.3 Make a new SIMSPEC file .............................................................................................. 9
3.4 Algorithm types ................................................................................................................ 9
3.4.1 ode23s algorithms ..................................................................................................... 9
3.4.2 Vector algorithms .................................................................................................... 10
3.4.3 Loop algorithms ...................................................................................................... 12
4. Data plotting toolbox ............................................................................................................ 14
4.1 Data import ..................................................................................................................... 14
4.2 Data plotting ................................................................................................................... 15
5.Plot window menus ............................................................................................................... 16
5.1 The Simulation menu .................................................................................................... 16
5.2 The EditGraph menu ...................................................................................................... 17
5.3 UIcontext menus............................................................................................................ 18
5.4 The Data menu .............................................................................................................. 19
5.5 Multi-graph panels ........................................................................................................ 21
6. Animations in PowerPoint ................................................................................................... 22
7. SimuPlot Commands ............................................................................................................ 23
8. SimuPlot Calc files ............................................................................................................... 23
9. Error messages ..................................................................................................................... 24

enfors@biotech.kth.se / December 2016

 SimuPlot5 manual 2 (25)

1. Introduction
SimuPlot contains two toolboxes for simulations, and data plotting, respectively. It has been
developed for bioprocess applications but can be used for many other purposes. SimuPlot5
has been developed with MATLAB version 2014b (8.4.0).

NOTE: When changing from MATLAB version 2014a (8.3.0) to version 2014b (8.4.0) MathWorks
introduced major changes in object specifications. This means that the present SimuPlot5 SIMSPEC
files (specifying simulations) currently are not back-compatible to MATLAB versions earlier that
2014b.

First time you use SimuPlot in a computer you must set MATLABs path to the folder
SimuPlot5 and its subfolders and save the path. The path is set from the MATLABs
Command windows menu (File/Set path or Environment/Set path, depending on version),
which opens a list of current paths including MATLABs default. Use the button Add with
subfolders and a browser is opened. Select the folder SimuPlot5 and press button Open.
This will add the SimuPlot5 folders on top of the previous folders in the path specifications.
Save the path setting. If you do not move or re-name these folders you do not need to repeat
the path setting next time you use SimuPlot in this computer.

The start command simuplot (case sensitive!) opens an initiation page from which the two
toolboxes are accessed (see cover page). It also initiates the global variables xy (a numeric
matrix with variable data in columns) and names (a cell matrix with column titles), for data
imported from e.g. Excel with the "Import to xy" button. If you get the error message
" ?undefined function or variable simuplot" you have not set MATLABs path correctly, or
misspelt simuplot.

2. A quick demo
For a quick demo of a dynamic and interactive simulation of a fed-batch culture:
Start MATLAB. If you have not set MATLABs search path to the SimuPlot5 folder and its
subfolders before, do that now (see text above).

1.Start SimuPlot with the command simuplot in the Command window. The window shown
on the cover page should open.
2 Press the button Open a SIMSPEC file. A browser opens.
3. Open the file fedbatch-demo.fig in the folder _SIMSPECfiles. A new window like the one
in Fig 1 should open.
4. Press the button Compile & Run. A new plot window should open (see Fig 4) and plots
will gradually develop.
5. When the initial substrate (S) after about 6 hours process time is exhausted (see Fig 4)
press the mouse arrow in the graph. The simulation is then interrupted and a small window
shown in Fig 2 is opened for changing constants.
6. Start a substrate feed, e.g. 0.1 L/h to initiate the substrate feeding. Press the OK button to
continue the simulation. (The Cancel button will stop the simulation irreversibly)
For information about the data plotting toolbox, see Chapter 4.2.

December 2016
 SimuPlot5 manual 3 (25)

3. The SIMULATION toolbox

3.1 The SIMSPEC window
The SIMSPEC file opens a window with 3 sections: Variables, Constants, and Algorithm with
equations (See Fig 1 which is an example of specification of a dynamic simulation of a fed-
batch culture with ode23s to solve the mass balance equations).

V
a
r
I
a
b
l
e
s

C
o
n
s
t
a
n
t
s

A
l
g
o
r
I
t
h
m

Fig 1. The SIMSPEC-window of fedbatch-demo. Upper section: Variables; Middle section: 3 tables
with constants; Bottom section: Algorithm with equations. The upper two sections can be scrolled to
see more rows, and the Algorithm section can be expanded with the FieldSize+ button. See text below
for further description. This is an example of specification with an algorithm using MATLABs ode23s
(indicated in the menu bar) to solve the differential equations. Examples of a Vector algorithm and a
Loop algorithm are shown in Chapters 3.4.2 and Fig 3.4.3, respectively.

December 2016
 SimuPlot5 manual 4 (25)

3.1.1 Variables (upper section, Fig 1)

This section specifies the variables: variable names, their initial values, plots, and plot axes.
Variable: The variable name is used as variable name in the model equations in the algorithm
and must therefore be spelt exactly equal in both sections (case sensitive!). This name is also
used for the plot labels and axes labels. The x-variable (usually time) must be specified in the
first row of variables.
ODE: This button must be checked for variables that are solved from differential equations
(ODE). These ODE variables must be listed after the x-variable. Below that you can specify
other variables you want to plot, e.g. variables appearing in the algorithm (e.g. my) or
changeable constants (e.g. F). The ODE button of these non-ODE variables must be un-
checked.
Unit: The unit is only for information and has no impact on the simulation.
Initial value: This specifies the initial value for a variable and it must be given for variables
that are solved from differential equations (ODE). For other types of printed variables the
initial values are omitted. If a model contains ODE variables they must be specified and given
an initial value even if they are not made visible with the Plot button (see below).
Scale min and Scale max: These values specify the minimum and maximum value of a plot
in the graph. Values must be entered even if the plot visibility button is un-checked.
Colour: A press on this button opens MATLABs uisetcolor function for change of the default
plot colour.
Axis: An optional individual axis is drawn for the plot if this button is checked. These axes
can be moved horizontally with the mouse and their labels can be moved with the mouse. A
double-click on the axis deletes it. If a plot lacks an axis it can later on be added from the
menu EditGraph (chapter 5.2).
Plot visibility: Checking this button means that the plot is visible in the simulation graph. If
the button is unchecked the plot is still drawn but made invisible by MATLABs visible off
object property, and the data are saved in the global xysim matrix. The visibility status of plots
can be changed in a graph after a simulation with the Edit plots function in the Edit graph
menu (chapter 5.2).
The variables table may contain max 17 variables, but only 9 variables including the x-
variable in the first row, are shown. The other variable rows are made visible by means of he
scroll-bar to the right. Red text on the 9th variable row indicates that there are more invisible
variables in the table below.
Un-checking the normally checked button "Interactive" in the upper right corner of the
SIMSPEC file (Fig 1) eliminates the interactive simulation mode, which increases the
simulation rate considerably, but the gradual development of the plots is then not shown.

3.1.2Constants (middle section, Fig 1):

This section contains 3 tables for specification of constants in the model equations. Constants
declared in the left table of this section can be checked to become changeable during the
simulation. If the mouse is clicked in the graph during a dynamic simulation the simulation is
interrupted and an editable list of changeable constants appears (Fig 2).

December 2016
 SimuPlot5 manual 5 (25)

Fig 2. Constants that have been declared as changeable by checking in

the left Constants section appear for editing when a dynamic simulation
is interrupted by a mouse-click in the simulation graph. The OK button
resumes the simulation with the new constant values. If the Cancel
button is pressed the simulation is ended. This is the normal way to stop
a dynamic simulation before it is finished.

The visible part of the Constants table contains 3x7 constants but the table may harbour 3x19
constants that can be made visible by scrolling. Red text on the 7th row indicates that there
are more constants below.

3.1.3 Algorithms and model equations (bottom section, Fig 1):

This section contains an algorithm and model equations for the simulation. Its structure
depends on the algorithm type used (ode23s/ode15s/ode45, Loop, or Vector). The algorithm
type is indicated in the menu bar of the SIMSPEC window. The different algorithm types are
explained in Chapter 3.4. Open the SIMSPEC files fedbatch_demo.fig, Sconsumption_demo,
and chemostat_demo.fig for examples of simulations with ode23s, a loop algorithm, and
vectors, respectively. MATLAB syntax must be applied for the code in this section. The
algorithm and equations shown in Fig 1 represent algorithm type ode23s. Pressing the Expand
+ button to the right increases the algorithm field size to fill the window. A second press
returns the default size.

3.1.4Compile & Run button

Pressing this button compiles the current specification (even if not saved !) to a temporary
simulation file (simfile.m) and runs the simulation. If a previous simulation window exists, a
window will open to permit 3 options for location of the new plots (Fig 3).

Fig 3. Plot options. If the Previous graph option is used a new window
will open to let you specify a different line style for the new simulation. If
the Renewed graph option is used the previous graph is erased and a new
graph is produced in the same window. If you have several previous
windows with SimuPlot graphs it is the currently activated window that
will receive the new plots. If you plot in a previous graph, you can specify
the new plot line appearances (solid, dashed, dotted, and thick)

Do not open and edit the simfile. It will have no influence of a simulation since a new file is
produced when you press the simulation button. However, it may sometimes be useful to
study the simfile if the simulation stops with an error message due syntax error in the
algorithm. Close it again before you continue.

December 2016
 SimuPlot5 manual 6 (25)

3.1.5 Menu functions of the SIMSPEC window

The standard menubar of MATLABs figure objects have been replaced with the following
SIMSPEC specific menu:

Open: Opens a browser for selection of a new SIMSPEC file. It also closes the current
SIMSPEC file. If you open a SIMSPEC file in other ways so that more than one SIMSPEC
file is open you cannot run a simulation. An error message will prompt you keep only one
SIMSPEC window open.
Save: This menu opens a browser for saving the current specification as a .fig file. Always
use this menu option, not other MATLABs function, to save a SIMSPEC file. Pressing the
Compile & Run button runs the simulation with the current specifications, irrespectively of
whether they are saved or not. Therefore, do not save changes in a SIMSPEC file until you
need to save these changes for later use.

Edit spec:

The Edit spec. menu has three submenus for printing, changing fontsize and correct the
format of rows in the Algorithm or Comments that may become disorganized. Use the HELP
edit spec menu to get a window with further information.
Copy, Paste and Clear of single spec-rows in the tables with Variables or Constants can be
made with a uicontextmenu that appears if the mouse right-click on a Variable/Constant
name. Alternatively, an alt-key+mouse-right-click may do the same. The commands refer to
the whole specification row.
The Variables table can hold max 17 variables including the x-axis variable that must be
specified on the first variable row. The constants are specified in three parallel tables, each
with 14 rows. To scroll through all Variables/Constants use the slider on right hand side. The
Algorithm field is automatically extended and furnished with a scroller when more than 20
rows of text are inserted. Pressing the "field size" button ( + ) extends the Algorithm field to
cover the whole window.

Comments: This menu is used to Show/Hide the Comments page. Text for explaining the
simulation can be added here. It has no impact on the simulation. It is recommended that no
remarks (text preceded by % sign) are included in the Algorithm field. You may rather copy
the algorithm text and paste it into the Comments field and add the comments there. An
example of comments to the fedbatch_demo simulation is shown below.

December 2016
 SimuPlot5 manual 7 (25)

Algorithm type: This menu shows the current type of algorithm used (See section 3.4). The
menu text is only a piece of information in the case of Loop and Vector algorithms, but if an
ODE algorithm is used the menu can be set to specify the use of MATLABs ode23s, ode15s
or ode45 for solving the mass balance equations (ordinary differential equations). For
fermentation processes ode23s is usually the best and fasted ODE-solver. Also a max time-
step in the ODE-solving can be set. Use the HELP function in the menu for more information.

The Interactive checkbox: Un-checking this checkbox removes the interactive simulation
mode, which makes the simulation much faster. This option is only available in ODE and
Loop algorithms.

December 2016
 SimuPlot5 manual 8 (25)

The HELP menu of the SIMSPEC file opens a window with a summary of the content of
this section (3.1).

3.2 Run a simulation

Open a SIMSPEC file either from the button Open SIMSPEC file on the start window of
SimuPlot (see cover page) or from the menu of an already open SIMSPEC file (see Fig 1). A
browser opens for selection of a SIMSPEC file. Some demo files are located in the folder
_SIMSPECfiles where you should store also your own SIMSPEC files.
It is strongly recommended that you organise your computer screen so that you see at least part of the
Command window while you run simulations. If errors are encountered MATLAB prints error
messages in the Command window. Also messages from SimuPlot appear in the Command window.
Press the button Compile & Run to initiate the simulation.
If you run a simulation with model type Vector, for instance the demo file chemostat_demo,
the result is immediately printed out in the plot window. If you run a dynamic simulation (for
instance the ode23s demo file fedbatch_demo, or a loop algorithm, e.g. Sconsumption_demo),
the simulation result is gradually plotted in the plot window and this gives the opportunity to
interrupt the simulation for changing constants, which have been specified and checked in the
leftmost table of constants, see Fig 1. The interruption is initiated by a single-click in the
simulation graph during a simulation. If the simulation runs too fast for interaction you can
slow down the rate by means of the rate slider above the graph (see Fig 4). This slider can be
switched on/off from the Simulation menu.
Fig 4.Example of dynamic simulation of
a fed-batch culture that was started as a
batch process with the specifications in
Fig 1. At 6 hrs the limiting substrate (S)
was exhausted and the simulation was
interrupted with a mouse-click in the
graph and the medium feed was started
with F=0.1 l/h. At 10 hrs F was increased
to 0.2 l/h. The labels on the plots are
produced by double-clicking on the plot.
See more about plot and graph editing in
chapter 5.2.

During a dynamic simulation the plots can be identified by a temporary label that appears
after a mouse right-click on the plot. When a simulation has been finished a message
Simulation completed is printed in the Command window. You can then proceed with
different options:
change specifications and run a new simulation. This can be done in a new window, or by
replacing the previous simulation, or by superimposing the new simulation on the
previous one (see Fig 3).
edit the plots and graph (see chapter 5.2-3 ).
save the figure (from the File menu) in different formats (e.g. jpeg or fig). If you choose
the MATLAB specific .fig format you can later open the window again and utilise all
SimuPlot functions for plot and graph editing. (Currently a bug distorts the axes when
you re-open this file. You can fix this with the command fixfigscales).
copy the graph from the File menu of the plot window and paste into Powerpoint or
Word files.

December 2016
 SimuPlot5 manual 9 (25)

3.3 Make a new SIMSPEC file

SimuPlot utilises three algorithm types, which are represented by the three demo-files:
fedbatch_demo, an ode23s algorithm
chemostat_demo,a vector algorithm
Sconsumption_demo, a loop algorithm.
The algorithm type is indicated in the upper right corner of the SIMSPEC window.

To make a new simulation program, open one of the demo-files in the SIMSPECfiles folder,
representing the type of algorithm you want to use. See explanation of the different algorithm
types in next section. Then save the file with a new name using the Save menu, change the
variables, constants, and algorithm/equations to fit your new simulation, save it again, and test
by pressing the button Compile & Run. When you press Compile & Run SimuPlot
produces a temporary file (simfile.m) with the data specified in the current SIMSPEC window
even if it is not saved. Remember to save the file (use the Save menu) when you are
satisfied with the new SIMSPEC file.

3.4 Algorithm types

3.4.1 ode23s algorithms
See Fig 1 for an example. This algorithm type is applied for dynamic simulations of processes
where the state variables (concentrations of biomass, substrate, etc.) gradually change with
time. Simulations of this type utilise MATLABs function ode23s to solve the mass balance
equations (ordinary differential equations). The fedbatch_demo and the dynamic simulation of
a chemostat (chemostat_dyn) are examples of application of algorithm type ode23s. You can
change the MATLAB ode-solver to ode15s or ode45 in the menu. use the HELP function of
the ODE-menu for explanation of the different ode-solvers.

SIMSPEC structure for simulations with the ode23s/15s/45 algorithm (See Fig 1):
Variables: The x-variable (time) must be specified on the first row and all variables which are
solved by differential equations must be specified on the next rows below, and have initial
values, and the ODE button must be checked. If you want to plot other variables or control
parameters they should be listed after to ODE-variables and the ODE button must be
unchecked. Unchecking the Plot button means that the plot is invisible in the graph, but can
be made visible after the simulation from the EditGraph/Edit plots menu.
Constants: The left hand table of constants have check buttons. Constants with checked
buttons will appear in a list of changeable constants when you press the mouse arrow in the
graph during a simulation (Fig 2).
Algorithm& Equations field: Do not use a / sign on the left-hand side of a diff.-equation. Use
e.g. the syntax dSdt=...instead of dS/dt= ..(See Fig 1). All parameters in the right-hand side of
the diff.-equations must either be inserted as numeric values, declared as constants in the
Constants section, or calculated in the algorithm before the diff.-equations. Finally, pack all
diff.-equation values in a column vector (use semicolon separators!) called dydt. See last line
in the equations field of Fig 1. The dydt vector must contain the ODE-variables in the same
order as they are listed in the variables section!
All variables are scalars in the ode23s algorithm so you do not need to use the element-wise
multiplication (. *) and division (. /) syntax as in the vector algorithm below.

December 2016
 SimuPlot5 manual 10 (25)

3.4.2 Vector algorithms

Fig 5 shows a SIMSPEC file chemostat_demo for simulation of a chemostat at steady-state,
which is a simulation based on a vector type algorithm. The files monod_inhib and
HTST_sterilization are other examples of this model type.

Fig 5. A SIMSPEC
file with the
algorithm type
Vector contains a
field (x-steps) for
specification of the
number of data
points along the x-
axis vector (default
value is 1000). The
result of this
simulation is shown
in Fig. 6.

SIMSPEC structure of Vector type simulations

Variables: The first row must contain the x-variable and its scale-min and scale-max values
must be specified. In this type of simulation a column vector with the x-variable is first built
with equal steps from the Scale min to the Scale max value with the number of steps specified
in the field x-steps on the x-variable row (see Fig 5). If the Initial value is lower than Scale-
min, all data below the Scale-min are deleted. If the Initial value is omitted, the value 0 is
used. Then the other variable vectors are built according to the formulas used in the algorithm
field.

The Comments field of the SIMSPEC file chemostat_demo gives further explanation of the
model equations. It is recommended that MATLAB remarks (text after %) are located here
rather than in the algorithm field.

December 2016
 SimuPlot5 manual 11 (25)

_________________________________________________________________________
chemostat_demo
Simulates steady-state concentrations, productivities, and growth rate as functions of dilution rate in a
chemostat. It is an example of simulation using SimuPlots algorithmtype " Vector" , in which an x-axis
vector is first built according to the scale specification on the first row in the Variables section (here D
from 0.02 to 1.4divided in 1000 steps).
Note that element-wise operations (.* ./ .^) must be used for vectors.
For models and derivation of the steady state solutions see Fermentation Process Eng., that can be
downloaded from www.enfors.eu.
The default settings assumes no cell death (Kd=0) and no biomass re-cycling (delta=1).
Product formation is set as partly growth rate independent with the Luedeking-Piret model.
If also the products and productivities are plotted, some plots may become identical. Then change the
scale of one of the plots.
Individual axes are plotted only for the top 8 variables. You can move them with the mouse and add
further plots from the EditGraph/Add axes menu.

Variables:
D /h Dilution rate
my /h Specific growth rate
S g/L Limiting substrate conc.
Xv g/L Viable cell conc.
DOT %air sat. Dissolved oxygen
S2 g/L Non-limiting substrate conc.
Xd g/L Dead cell concentration
Pe g/L Extracellular product conc.
Pi g/g Intracellular product conc.

Constants:
Yem g/g Biomass yield coefficient on S, excl. maintenance
qm g/g/h Maintenance coefficient
Ks g/L Saturation constant for S
mymax /h Max specific growth rate
kd /h 1st order death rate constant
Yosresp g/g Oxygen consumed per substrate in respiration
DOTstar % DOT in equilibrium with air bubbles
Si g/L Inlet S concentration
delta - Cell recirculation factor
KLa /h Volumetric oxygen transfer coefficient
Yxs2 g/g Biomass yield on S2
S2i g/L Inlet concentration of S2
H %/(g/L) Conversion factor: % air sat. units per gO2/L
alpha g/g Luedeking-Piret constant for growth associated production
beta g/g/h Luedeking-Piret constant for non-growth associated production
Cx gC/gX Carbon concentration in cells
Cs gC/gS Carbon concentration in substrate S

Algorithm:
'my=delta*D+kd;'
'S=my*Ks./(mymax-my);' Limiting S according to Monod model
'S(find(S<=0))=Si;' Boundary condition for model
'S(find(S>Si))=Si;' Boundary condition for model
'Yxs=my*Yem./(my+qm*Yem);' Biomass yield on S incl. maintenance
'Xv=D./my.*Yxs.*(Si-S);'
'Xd=kd*Xv./(delta*D);'
'qs=my./Yxs;' Specific substrate consumption rate
'qo=Yosresp*(qs-Cx/Cs*my);' Spec. oxygen consumption rate
'DOT=DOTstar-qo.*Xv*H/KLa;'
'qp=alpha*my+beta;' Spec. product formation rate
'Pe=qp.*Xv./D;'

December 2016
 SimuPlot5 manual 12 (25)

'Pi=qp./my;'
'Pi(find(S==Si))=0;' Boundary condition for model
'qs2=my./Yxs2;' Spec. rate of S2 consumption
'S2=S2i-qs2.*Xv./D;'
'my(find(my>=mymax))=0;' Boundary condition of model
_____________________________________________________ __
This results in the following matrix (stored in the global matrix xysim) with each variable in a
column (only the first rows of the D, X and S variables are displayed here):

D X S
0.0204 33.535 0.035581
0.0216 34.158 0.037063
0.0228 34.736 0.038552
0.024 35.273 0.040047
0.0252 35.773 0.041549
0.0264 36.24 0.043057
0.0276 36.678 0.044571
etc.

Since this model type involves operations with (column) vectors, and each row represents the
values at the x-value of that row, element-wise operations must be applied for divisions and
multiplications when the vector type of algorithms are used. This is made by inserting a .
(period sign) before the operators of multiplication and division, i.e..* ./ and .^. This is
relevant only for multiplications and divisions of two vectors (or when a vector is a
denominator )- not when one vector is multiplied with or divided by a scalar (constant). Study
the equation fields in the demo-files chemostat_demo and monod_inhib if you are not familiar
with this type of vector operations.
Fig 6 shows the result of simulation of steady state values of a chemostat with the
specifications shown in Fig 5. Note that only variables that have been checked for plotting are
shown in the simulation.
DOT
2 15 1 15 100
S

Fig 6 Simulation of steady state values

DOT ( %air sat. )

DOT S2
in a chemostat with the specifications in
S2 ( g/L )

Xv ( g/L )

my ( /h )

S ( g/L )

Xv Fig 5 (not all variables plotted). Steady-

my
state concentrations and the specific
growth rate (my) are shown plotted
S2 against the dilution rate (D).
S Xv
0 0 0 0 0
0 0.2 0.4 0.6 0.8 1 1.2 1.4
D (/h)

3.4.3 Loop algorithms

An example of a loop algorithm is shown in Fig 7. The loop starts with x-variable = initial
value (in the SIMSPEC file, see Fig 7) and the first calculations are made according to the
algorithm (Fig 7). Then the x-variable value increases with the value (scalemax-
scalemin)/xsteps and the calculations are made again, according to the algorithm, until the x-
variable value reaches scalemax (or other criteria in the algorithm). The loop type of
simulation is useful for dynamic simulations processes using the Euler method for solving the
differential equations of mass balances. In this way a change of a diff.-equation variable can
be done during a simulation, for instance to study addition of a pulse of substrate or removing

December 2016
 SimuPlot5 manual 13 (25)

samples during a process. This is not possible with ode23s. However, ode23s is generally
better and much faster for solving he stiff differential equations in a fedbatch simulation. Be
careful in the specification of the time step length (number of x-steps). If you run a simulation
of a fed-batch process (like the one in fedbatch_demo) the value must be at least 20 000
otherwise oscillating solutions appear for variables included in stiff differential equations (e.g.
the DOT). This makes the simulation much slower than if the ode23s algorithm is used. A
simple demofile, Sconsumption_demo is included in the SimuPlot package and shows the S
gradient when feed is stopped in a fed-batch process with limiting S concentration (Fig 7-8).

Fig 7. The SIMSPEC window of Sconsumption_demo. This is an example of a Loop algorithm

for dynamic simulation using the Euler method to solve mass balance equations. The result of
this simulation is shown in Fig 8.

Fig 8. Simulation of limiting S-

concentration profiles after stop of
feed in a fed-batch reactor with
different biomass concentrations.
Simulations with the loop algorithm
shown in Fig 7.

December 2016
 SimuPlot5 manual 14 (25)

4. Data plotting toolbox

4.1 Data import
Data from two types of data files can be imported: ASCII coded (tab or comma separated)
data tables, e.g. Excel files saved as .txt or .csv format, and MATLABs .mat files, if produced
with SimuPlot (see the savedata command in section 7).
There are two ways to import data to SimuPlot: Use the Import to the xy-matrix button on
the start window of SimuPlot (see the cover page). and add additional data from other files
with the button "Add data to the xy-matruix" . This places the numeric data in the global
matrix xy with column headlines in the global cell matrix names, or use the command
[xyout,namesout]=readfile by which you can store the data with any matrix name (see
section 7).
If a .mat file (with numeric data previously produced with SimuPlot) is opened the data
appear immediately in MATLABs workspace with the names used when saving, and you can
proceed with plotting or calculations.
If a .txt or .csv file is opened the first 6 rows and max 6 columns are displayed (Fig 9) to
facilitate your specification of which parts of the file to include in xy and names. You can
specify reading from a certain column nr and from a certain row. Then you must specify
whether 1 or 2 rows should be included as column heads (=names). The rest of the file must
contain a strictly numeric table. Empty cells in this table will be replaced by NaN. However,
if the cell in the last rows last column is empty, SimuPlot can not read the file, so you
must, in Excel (or other software), add the letter NaN there, and save before the file can
be opened by SimuPlot.

Fig 9.File import instructions that appear when a tab (.txt) or comma (.csv) delimited text data file is
opened. The first columns of the 6 first data rows in the file are displayed to simplify the settings of
number of title rows and read from column nr and "from row nr". If the file contains decimal
comma signs (,) they are translated to decimal dots(.).
(This file import uses MATLABS readtable function, that is very fast for large data files. If a
MATLAB version previous to 2014a (version 8.3) is used, the file reading is performed by another,
much slower, function.)

December 2016
 SimuPlot5 manual 15 (25)

The numeric data, imported with the buttons on

the start window, are stored in the global matrix
xy and the title row(s) are stored in the global
cell matrix names. The names matrix can
contain one or two rows, the second assumed to
be used for optional unit information. The order
of columns and variable names in the xy/names
matrices can be edited after pressing the button
"Edit/Save xy" on SimuPlots start window).

The Edit/Save xy function also gives the

opportunity to change names and add units of
the variables, and to change the order of
columns in xy, or delete columns.

4.2 Data plotting

SimuPlot supports two methods to plot data. One is to use the Plot xy button (see cover
page, also available from the "Edit/Save xy" function). In this case only data from the global
xy and names are plotted. If you have downloaded data to other names use the command
plotxy(xyin,namesin) where xyin is a numeric matrix and namesin is a cellmatrix with column
names, correspond to xy and names. In both cases a window with the column names of the
numeric matrix is opened (Left panel in figure below). You can select one or several of these
plots. Use Ctrl (cmd in MacOS) to pick columns that are not adjacent to each other. The 1st
column is assumed to be the x-variable in the plot, but this can be changed to any of the
other columns by changing number in the x-variable field (see figure below).
When the "Plot" button is pressed a plot specification window is opened (se right fig. below).
The variable name can be edited here (influences the plot labels but not the names matrix).
The Scale-min and Scale-max values of the selected columns are shown to simplify
specification of suitable scale span. Default line width is 1 and increasing the figure to 2 or 3
gives thicker lines. An optional individual axis can be drawn for each plot if a value is
specified for Axis position: 0, -10, -20 etc. means left hand axis and 100, 110, 120 ... etc.
means axes on the right hand. (Any figures can be used, but too low/high values may place
the axis outside the page). The axes can be dragged in horizontal positions with the mouse
and edited or deleted after a mouse right-click.

December 2016
 SimuPlot5 manual 16 (25)

Fig 10. Plot specifications: Left figure shows the window for selection of
variables in the data matrix. To select non-adjacent columns use the Ctrl
(cmd) button when selecting. Right: The selected columns are listed in a panel
for specification of the plot properties. The min and max values of the vectors
are shown as defaults in the Scalemin and Scalemax fields to simplify choice
of suitable scale. If the optional data for axis position ( Ax.pos field) is filled
an axis is drawn for that plot. Position 0, 10, 20 etc. places the axis to the
left of the graph and 100, 110, 120. etc. places the axis to the right of the
graph (see Fig 6). The plot windows obtain an EditGraph menu similar to that
obtained with a simulation. The function of this menu is described in Chapter
5.2.

5.Plot window menus

The plot windows produced with SimuPlot contain MATLABs default menus plus two or
three specific SimuPlot menus: Simulation, which is only produced from a simulation and the
EditGraph and Data menus that are produced both from simulations and plotting. The
Simulation graph and Plot graph are compatible so plots can be copied and transferred in
between (if the scales have been set equal).

5.1 The Simulation menu

Pause. This function temporarily interrupts the simulation of ode- and
loop- algorithms, which can be utilised for labelling plots by double-
clicking or copying the graph for transfer to PowerPoint animations.
Continue. This function resumes simulation after a pause.
The Pause and Continue functions are also reached after a mouse right-
click in the window outside the simulation graph.
Speed control. The simulation speed control slider (see Fig 4) can be
switched on/off with this function (in dynamic simulations).
Add legend. This function adds a movable MATLAB legend to the graph, with line colours
and variable names. A mouse-right-click opens a uicontextmenu for deleting or editing the
legend.
Delete last sim. deletes irreversibly the last simulation if several simulations have been
superimposed in the same graph.
Display time displays the current simulation time (x-axis value) under the graph.
Time marker adds a moving vertical line that indicates the current simulation time.
HELP. This function opens a new window with explanations of these menu functions.5.2

December 2016
 SimuPlot5 manual 17 (25)

5.2 The EditGraph menu

Most of the objects (graphs, extra axes, text, lines) produced with SimuPlot contain UIcontext
menus (see next page) that appear when a mouse right-click is executed on the object.
Additional editing functions are controlled from the EditGraph menu that is similar for
simulation and data plotting graphs. This menu is shown bleow.
Edit plots. Opens a list of all plots in the graph (incl. invisible plots) for editing with respect
to: Colour, marker, line-style, scales, visibility (hide/show) and permanent deletion. Related
plot labels and axes are not deleted when a plot is deleted. They can be deleted from the
UIcontext menu (mouse right-click). If a scale is changed the corresponding axis is not
changed but the axis can be deleted from its UIcontext menu and a new axis drawn with the
EditGraph menu function Add axes.
Add plots. New plots can be added from the xy-matrix
to this graph or to a new window.
Edit plots. A table of all plots in the current plotaxis
is produced and for editing of scale color, marker, line
styles and scale. Plots can be made invisible or
deleted.
Hide/Show
Copy plots. Produces a list of all plots in the current
plot axis. Select the plots to be copied and return to the
window where you paste the plots in a SimuPlot graph
with the menu function Paste plots.
Add axes. Lists all plots. Adds an axis for the selected
plot(s) at the relative position "relaxpos" where
relaxpos= 0, -10 etc. (use any number) adds the axis
on the left hand side and relaxpos= 100, 110 etc. adds
the axis on the right of the graph. The axis can be
dragged horizontally with the mouse, and deleted or
edited after right-click with the mouse.
Plots axis. With this menu the plot axis is switched between visible/invisible. Invisible
plotaxis can be useful for animations in Powerpoint. Also, if an extraaxis or its label has been
moved behind the graph it may become unavailable for editing or moving with the mouse.
Hiding the plotaxis makes it available and the plotaxis can then be med visible again.
Add text. Opens an edit field for input of multi-lines text. Pressing the "Locate text" button
closes the edit field and creates a cursor cross for location of the start point of the text. The
text can be moved with the mouse, and edited or deleted after a right-click with the mouse.
Edit graph. This function opens a window from which
1: Fonts of all axes, axes labels and text can be edited with MATLABs uisetfont function
2: The linewidth of all plots and all axes can be changed
3: The color of all plots, axes and text can be specified with MATLABs uisetcolor function.
A checkbox to make the objects black & white is also included.
The editing applies to all objects of the selected class (plots, axes, text) in the graph.
Individual objects can be edited with the UIcontext menu function (mouse right-click, see
below)
Copy graph (for panel). The whole graph is copied (except of annotation arrows etc), and can
then be pasted into a multigraph panel. (Arrows must be added again from the menu).

December 2016
 SimuPlot5 manual 18 (25)

Multigraph panel. This function opens a new window with an empty panel for pasting max 3
rows and max 2 columns of graphs. See section 5.4. The graphs are copied from the
EditGraph menu.
Vertical line converts the cursor to a cross for location a vertical dotted line in the graph. The
line can be dragged horizontally with the mouse, and edited or deleted after a right-click. The
x-axis coordinate is displayed when the mouse is pressed on the line. The length of the line
can be extended outside the graph, which can be useful in multi-graph panels.
Horizontal line converts the cursor to a cross for location of a horizontal dotted line in the
graph. The line can be dragged vertically with the mouse, , and edited or deleted after a right-
click. The relative y-axis coordinate (% of scale - not the absolute value!) is displayed when
the mouse is pressed on the line. The length of the line can be extended outside the graph,
which can be useful in multi-graph panels.
Add arrows. This menu function opens a textbox for adding optional text at the arrow basis.
A cursor cross then appears to locate the arrow. Its direction and position can be moved with
the mouse. The text can be modified and the object can be deleted from its UIcontext menu
(mouse right-click)
Zoom. The cursor is changed to an amplification glass symbol when moved over the graph
and when pressing down the graph is zoomed in that point. There are three zoom options:
zoom xy, zoom x, and zoom y, which zooms both x and y axis, only the x-axis, or only the y-
axis, respectively. un-zoom returns to the graph to its original and keep zoom conserves the
zoomed state.
Print graph. This menu function prints the current window. It is the same as the Print option
in the MATLABs File menu, but works better for some combinations of printer and software
versions.
HELP prints the explanations of all functions of the EditGraph menu in the Command
window.

5.3 UIcontext menus

Many edit functions for plots, text and axes have been placed in UIcontext menus that are
opened by a mouse right-click on the objects:
Window (outside graph) in dynamic
simulations: The graph (=plotaxis): Extra axes:

Graphs in multi-
Plots: graph panels: Text:

December 2016
 SimuPlot5 manual 19 (25)

Some of the UIcontext menu functions can also be reached from the EditGraph menu.

The Display data menu shows the xy-coordinate at the point of the plot where the mouse was
pressed. A plot that has been hidden can be made visible again from the graphs UIcontext
menu and a copied plot or text can be pasted with the Edit graph menu. In multi graph panels
the y-axis tick labels can interfere and the TickLabelMode permits to modify the number of
tick labels.
Further graph editing functions are also available from the menu EditGraph. Use the HELP
function in this menu to display information on the functions of these menu options.

5.4 The Data menu

This menu contains some functions for editing the
data of the plots. For each application, a list of al
plots is first shown for selection of one plot to
treat.

Show plot data opens opens a window in which the x- and y- data of the selected plot is
displayed.

Cut plot data removes data points from

either end of the selected plot. A window
showing the number of data points in the
plot is opened for specification of the
number of data points to be removed. If
the number is negative, the elimination is
made from the beginning, else from the
end of the plot. Repeated cuts can be
made. The button UNCUT restores previously removed segments, step-wisely if several cuts
have been made.
Outlier. Opens a list of
all plots in the graph for
selection of one plot.
Option 1: Delete out-
of-scale points removes
all data outside the
min/max values of the y-
scale. Option 2 Select
zone: If a plot area is
selected by dragging a
mouse rectangle, data
points in the area are
removed. Removed data
points can be restored
consecutively in the
same order they were removed.

Datafilter. Two filter types are available: Moving mean or Forward/back filtration.

December 2016
 SimuPlot5 manual 20 (25)

Moving mean filter: The total number of data points in the selected plot is shown and an input
field is opened for entering the window size (number of data points for the moving average).

Forward-back filter: A window is opened to specify the filter parameter. -0.85 is default
value. 0 gives no filtering and lower value, e.g. -0.95 , a stronger filter.
The filtered y-vector (from both filters) is finally interpolated to the first column in the xy-
matrix and the filtered data are plotted (red) together with the un-filtered data (black) in a new
window from where options are given to plot in a SimuPlot window and/or add the filtered
data to the xy-matrix. If the option Add to xy matrix is selected a window opens for location
of the place in the xy-matrix. The vector name can also be changed here.

Datafit. This segmented curve fit function makes it possible to combine exponential and
polynomial or two polynomial fittings of different sections in one plot The figure here
illustrates an exponential fit to the batch phase (0-5 hrs) followed by a 1st order polynomial
fit of the fed-batch phase. If no exponent is given, SimuPlot calculates the exponent that gives
lowest sum of square of difference between fitted and original data. The parameters are set
and then tested with the Show button. If the fit is not accepted by you, new parameters can
be tested until the button Accept is
pressed. Then another segment is
analysed and finally accepted. The
Finish button merges the
segments. The fitted curve can be
interpolated to the first column of
the xy-matrix or to only the
measured x-variable values. Finally,
the data can be inserted in the xy-
matrix (See Datafilter above).

December 2016
 SimuPlot5 manual 21 (25)

Linear regression. After selection of which plot in the

graph to analyse the plot is redrawn in a new window
together with the linear regression line, the linear
equation and the correlation coefficient calculated with
MATLABs function corr2. A smaller part of the line
can be re-analysed after pressing the button Select a
zone and drawing a zone with the mouse. The final
result can be inserted in the xy-matrix (see Datafilter
above) and/or plotted in the original graph.

5.5 Multi-graph panels

Panels with maximum 3 rows and 2 columns of graphs can be made in one window (See
example next page). Each graph must first be made with the plotting procedure described in
section 4.2 above. Normally only the left and right axes (positions 0 and 100) fits into such a
panel if the number of columns in the panel is 2, but more extra axes may be used if the graph
size is reduced with the Edit Graph menu function or with the UIcontext menu of the graphs
in the panel. Following is a procedure of making a panel of graphs:

First a special multi-graph panel window must be created from the

EditGraph menu (or with the command panel) where number of
rows is specified to 1-3 and number of columns to 1-2.
A graph produced with SimuPlot can be copied from the
EditGraph menu for pasting into this panel.

The menu of the multi-graph panel contains the function for pasting
SimuPlot graphs into a specified row/column in the panel, adding free
text, pasting copied text, editing fontsize. Information about how to
add arrows and other annotation objects is also obtained from this
menu.

When the Paste graph menu is used a question is raised

whether to pack the panel rows or not. If Yes is
selected, the numeric x-axis scale is removed, except
for the bottom row. For editing of individual plot, axis
and text objects use the UIcontext menus (mouse right-
click) of these objects.

A mouse right-click in an individual graph in the panel opens a menu

for re-sizing, moving, or deleting the graph, or to show plots that have
been hidden. Copied plots can be added and further axes added.
Vertical and horizontal lines can be extended over the whole window
for comparisons between the different graphs.

Next page shows a multi-graph panel with packed rows so that only
the lowest graph shows the x-axis tick labels. To prevent interference

December 2016
 SimuPlot5 manual 22 (25)

between min and max ticks on the y-axes, the min value (mostly 0) of some scales have been
removed with the UIcontext menu (see section 5.3).
10 500 1000
Qi
Fs
( L/min )

)
RPM

(-
Fs

RPM
Qi

0 100
0 300

klaC(mMol/L/h) ( - )
( %air sat. )

klaC(mMol/L/h)

DO
DO

22 10
0 1
RQ
( %v/v )
( %v/v )

O2o

RQ
CO2o
O2o

CO2o

12 0 0
0 1 2 3 4 5
time 6 7 8 9 10

6. Animations in PowerPoint
Individual plots in a multi-plot graph or different time segments of a dynamic simulation can
be transferred to PowerPoint and shown step-wisely with the PowerPoint Animation function.
The following procedure shows how to make a PowerPoint animation of a fed-batch culture
in several steps, e.g. the batch phase and the fed-batch phase.

1. Start a dynamic simulation with for instance the SIMSPEC file fedbatch_demo.
2 At the end of the batch phase: Interrupt the simulation with the windows UIcontext menu
(mouse right-click outside the graph).
3. Label the plots with a double-click and make a copy with the menu function Edit/ Copy
figure.
4. Paste the copy into Power point. If this is not the first copy, select the copy object by
pointing at it with the mouse and choose Appear in the Animation menu of PowerPoint.
5. Continue the simulation (use the windows UIcontext menu).
6. Press (quickly) in the graph to interrupt again and change process control parameters (set F)
and continue the simulation.
7. Run until you have obtained the next phase for the .ppt animation, then interrupt, copy and
paste into PowerPoint.
All copies will start at time zero, but the copies usually cover each-other well. If you want to
avoid the multiple graph frames (usually not visible), you can use the menu EditGraph/Plot
axis/Hide before transferring the copy to PowerPoint.

December 2016
 SimuPlot5 manual 23 (25)

7. SimuPlot Commands
SimuPlot contains a number of
commands that are stored as m-files in
the SimuPlotCommands folder. Some
of these commands are addressed from
the SimuPlot graph menus but they may
also be useful if you work with
calculations and plotting directly from
the Command window. Pressing the
button SimuPlotCommands on the
start page of SimuPlot (see cover page)
produces a list of these commands.
Pressing one of the buttons in this list
prints an explanation of the function of
the command.

8. SimuPlot Calc files

A number of standardized
calculation files for common
bioprocess variables are
located in the folder CalcFiles.
Pressing the button "SimuPlot
Calc-files" on the SimuPlot
start window produces a list of
these files. Pressing the related
button displays the "help" text
of that file. These calculations
require that the process log-
and off-line data have been
inserted in the global xy-
matrix.

December 2016
 SimuPlot5 manual 24 (25)

9. Error messages
Always work so that you see at least some of the Command window when you use SimuPlot.
MATLAB error messages are printed out there and also some messages from SimuPlot.
Here are some examples of error messages and possible explanations:

1) ??? Undefined function or variable 'simuplot

Reason: You have not set MATLABs path to SimuPlot3 folder and its sub-folders or you
have not spelt the command correct.

2) Undefined function or variable 'commandhelp'.

Error while evaluating uicontrol Callback
Reason: You have set the MATLAB path to only the SimuPlot5 folder, and not included the
sub-folders.

3) Sometimes there is a number of statements in one error message:

??? Undefined function or variable 'f'.
Error in ==> simfile at 30
dVdt=f;
Error in ==> odearguments at 110
f0 = feval(ode,t0,y0,args{:}); % ODE15I sets args{1} to yp0.

It is usually the first of this error messages that points at the faulty code line. (In this case a
spelling error (f instead of F) in simfile at line 30). This file is produced from the compilation
of the SIMSPEC file, so the error is there. The other messages show the execution path when
the error was encountered. If you press the underlined part of the message the editor will open
this file and locate the cursor at the mentioned line.
If the error is in the temporary simfile it is most likely an incorrect spelling or decimal sign
(eg a decimal , instead of decimal .) in the SIMSPEC file. If you open the simfile to check an
error message remember to close it before you continue. simfile.m is a temporary file which is
regenerated each time you press the Compile & Run button on the SIMSPEC window.

4. If you run a simulation using ode23s you may get the following type o error message:

This is due to problems for ode23s to solve the equations. Try to reduce the maxodestep
parameter in the Simulation menu of the plot window.

5. Error using toc

You must call TIC without an output argument before calling TOC without an input
argument.
This message may appear if you try to edit a simulation or plot graph produced with SimuPlot
without previously opening SimuPlot.
Solution: Enter the command tic in the command window or start SimuPlot with the
command simuplot and do the editing again.

December 2016
 SimuPlot5 manual 25 (25)

6. Error using readtable (line 129)

The data in this file does not appear to be tabular,....
This error message comes when importing data from a .txt or .csv file in which the cell in last
row and column is empty.
Enter NaN in the empty last cell and save the file.

December 2016