SumoSlang is a very powerful tool for developing your own "customized" process models. The purpose of this little document is to provide a tour through a stripped down version of the SumoSlang language. To highlight the features that will be familiar to someone with a basic understanding of process modelling and simulation and help get you started on building your own custom models so that you can "learn by doing". So SumoSlang for Dummies, or maybe SumoSlang for Doers... call it what you want.
The tutorials are organized as follows:
SVfrom an Influent element, through a basic CSTR and into an Effluent element.
SVcomponents are directly mapped with no reactions performed. Not very interesting but a good place to start.
PARand calculated variables
CVAR. What do they add to the model, how are they tracked and how do they leverage SUMO's
C:\Users\cdhou\AppData\Local\Dynamita\Sumo21. There should be a folder here named "My Process Code" and inside of that you will find "Process Units" and "My Process Unit Category". This is where we are going to work.
\TutorialOne basic CSTRcontaining the following three files:
basic CSTR image.emfwhich is an image file to visually represent the process unit on the SUMO drawing board,
TutorialOne basic CSTR Group Info.xlsxwhich is an Excel file to explain to SUMO the organization and use of the files in this folder.
TutorialOne basic CSTR.xlsxwhich is the Excel file which contains the actual code describing the process unit model.
TutorialOne basic CSTR Group Info.xlsxmust be organized with the following elements:
Unitcontaining a table with the column headings
DefaultUnit. Note that
DefaultUnitrefers to the name of the Excel file in the current folder where the Sumo Model Translator (SMT) should look for process unit model code.
TutorialOne basic CSTR.xlsxwe need to include two worksheets named
Unitworksheet needs to include three tables:
Porttable which explains the number of connections that can be made to the element, how they should be named, and more.
Modeltable which identifies which are valid and invalid biokinetic models that can be associated with this model file.
Appearancetable which identifies which image file from the working folder should be displayed on the drawing board.
\My Process Code\Process Units\My Process Unit Category\TutorialOne basic CSTR.xlsxwhich you can download from here.
Codeworksheet can be even simpler. In this tutorial we make it a single table that includes two lines:
$D$4which, respectively, assign the value of the flow in the output
outp..Qto the value of the flow in the input
inp..Q. Simple mapping of the inlet flow to the outlet.
$D$5which, respectively, assign the value of the state variables in the output
outp..L.SVto the value of the flow in the input
inp..L.SV. Simple mapping of the inlet state variables to the outlet with no transformations or conversions. Boring, I know, but a good place to start. Patience young grasshopper!
inp..L.SVis SumoSlang's, well... "slang" for all of the state variables in the input stream to the "basic CSTR". And, if we are more precise, it is actually the liquid phase state variables and so excludes gas phase state variables (i.e. bubbles and headspace) which are assumed in most cases to not travel between CSTRs. And maybe one final point, the definition of the input is in fact anything connected to the port location identified in
$D$5. But it's actually not necessary to understand all of that detail. A lot can be accomplished just by carefully following and tweaking the template files.
TutorialOne basic CSTR. We find that our new category
My Process Unit Categoryappears to the left of the SUMO drawing board along with the standard library of SUMO process units. We can drag our unit to the drawing board where it is given the name of our folder
\TutorialOne basic CSTRand, by looking in the bottom left hand corner under
Manual, we see that the process unit file referenced is also named
TutorialOne basic CSTR.xlsx. Note if you created a copy of
TutorialOne basic CSTR.xlsxin the
\My Process Unit Categoryfolder then it would also appear in this list as shown below. This is a useful feature in cases where you want to have alternate versions of your process unit code.
XBIOin the effluent object. The reason for this is that the standard library "Effluent" object in SUMO is looking for parameters in addition to the
L.SVwhich were mapped to the
TutorialOne basic CSTR.xlsx. So for this tutorial we cannot use the standard library
Effluentobject. Instead we will create a
TutorialOne basic Effluentelement inside
\My Process Unit Category.
TutorialOne basic Effluent Group Info.xlsxlooks very similar to
TutorialOne basic CSTR Group Info.xlsx:
basic Effluent.xlsxis also very similar to
TutorialOne basic CSTR.xlsxwith the exception that there is now only an input port which, somewhat ironically, we name "eff":
Codeworksheet can therefore be completely empty:
Popupworksheet that will allow display of model variables. We will display flow
Flow elementscategory together with our
TutorialOne basic CSTRand
TutorialOne basic Effluentfrom the
My Process Unit Categorythen we can successfully build a model. And when we simulate in steady state and then place our cursor over the effluent element, we see from the popup that the model has successfully mapped the influent flow from the influent element, through our basic CSTR and in the effluent element.
basic CSTR.xlsx. Is the new value of
outp..SNHxcorrectly mapped to the effluent object when you run steady state in SUMO? What happens if you omit the rule
Model Basethat includes a vast library of components with associated biokinetic, water chemistry, and gas transfer processes. We will explore how SumoSlang interacts and leverages the
Model Basein the next tutorial.
At its heart, process simulation is about solving the following mass balance across the
Change in Mass of Component X with respect to time = Mass Flow of X in - Mass Flow of X out + Conversion rate of X
The Conversion rate of X in the above equation is what we think about when we talk about "ASM" or "Activated Sludge Models". In many cases, it is the most interesting part of the model and where most of the complexity lies. But even though it is possible to directly code ASM process equations in the
Code worksheet of the
Process Units ,in our case the
basic CSTR.xlsx, this would not be the best way to use SumoSlang. In SumoSlang, the code for the ASM-type models are referred to as the
Model Base and kept separately from the code for the
Process Units. One way to think about this is that the Conversion rate of X in the mass balance described above is coded in the
Model Base whereas the rest of the mass balance equation is coded in the
The separation of code for the
Model Base and
Process Units is shown in the folder structure below.
The advantage of this separation is that the
Process Units code can be used with different
Model Base codes. And new constituents added to the
Model Base, one might for example want to add PFAS, are automatically pulled into and compatible with the
Process Units code. There is no need to update the code for each of the 30+ models coded in the
Process Units folder structure. What a relief! So let's get started building reactions into our basic CSTR.
C:\Users\cdhou\AppData\Local\Dynamita\Sumo21\Process code\Model base\Full plant models. Copy this file into the "Model base" folder in the parallel "My Process code" folder structure and rename it
TutorialTwo_Mini_Sumo.xlsx. In my computer it is
C:\Users\cdhou\AppData\Local\Dynamita\Sumo21\My Process Code\Model base\My Model Categoryand looks as follows:
Modelworksheet, delete rows 4-6 (corresponding to r1, r2 and r3) as well as rows 9-29 (corresponding to r6 to r26). This should leave you with only r4 and r5, which represent the growth and decay of nitrifying organisms
TutorialTwo_Mini_Sumo.xlsxwith all process deleted except NITO Growth and Decay. The stoichiometric matrix contains symbolic or "parametized" terms like
1/YNITOwhich we want to "deparametize":
XNITOand the utilization of ammonia
SNHx(-6.667) and generation of nitrate
SNOx(+6.667) associated with growth of nitrifiers. We will ignore all other stoichiometric terms like
SALKor even dissolved oxygen
SO2for this simplified case:
SNHxbut otherwise does not contain any symbolic parameters:
TutorialTwo basic CSTR:
\Tutorial One basic CSTRinto
\Tutorial Two basic CSTRbut we need to update the names of the Excel files as follows:
Codeworksheet is updated to include four tables.
SVin the CSTR compartment to their initial conditions
SV_0. Note that the heading to this table cell
$D$3specifies that this assignment is only to be made once, in the
Codelocation(ZeroTime). That means initial conditions are assigned only at the very beginning of the simulation.
rate_SVas the matrix multiplication of the individual process rates
rMODEL.Model.jand the stoichiometric matrix
rMODEL.Model.jis a reference to the rate expressions of the
Model Basefollowing SumoSlang's "triplet notation". More on this notation can be found in the BoSS. For the
TutorialTwo_Mini_Sumo.xlsmfile we developed, it refers to the expressions defined in cells
vMODEL.Model.j,SVis SumoSlang's triplet notation for the stoichiometric matrix described in cells
$E$4:$AM$5of this same worksheet.
rate_SVas part of the mass balance to define the change with respect to time of the concentration of liquid state variables
dL.SV_dt. This is the so called differential equation that the SUMO numeric engine will integrate during a model simulation. Note that this mass balance introduces a new parameter
L.Vto represent the liquid volume of the
basic CSTR. We will define
L.Vin a new worksheet named
Parameters. More about the
inp..Qto the reactor effluent
outp..Qas well as the concentration of state variables in the reactor compartment
SVto the reactor effluent
Parametersworksheet is used by SumoSlang to define any user defined parameters or pull them in from the
Model Base. In this case we define the liquid volume
L.Vto 24000 and the initial conditions for the state variables
"MODEL.Components.Activated sludge". The expression
"MODEL.Components.Activated sludge"refers to the column labelled
Activated sludgein the
Componentsworksheet of the
Model Base. In our file
TutorialTwo_Mini_Sumo.xlsmit is found in column F.
Unitworksheet does not require any updating.
L.Vthat we defined in the
basicTwo CSTR.xlsxcan be changed by the user in
INPUT SETUPtab. How does the predicted effluent ammonia change if double the reactor volume to 48000 m3?
Process Units, we learned how to leverage the
Model Basewhich we pulled into the
Process Unitsusing "triplet notation". Unfortunately, the process unit file
basicTwo CSTR.xlsxis not compatible with the standard library of SUMO
Model Base. The reason for this is that it is missing the code to import the
PAR. Also it does not calculate and map certain calculated variables
CVARthat other process units expect to be mapped to the
..outpport of our basic CSTR. These shortcomings will be addressed in the remaining two tutorials.
The purpose of this tutorial is to make our
basic CSTR compatible with the
Mini_Sumo from SUMO's standard
Tutorial Two basic CSTRinside the
My Process Unit Categoryand call it
TutorialThree basic CSTR:
\TutorialThree basic CSTRas follows:
Group Infofile references the
TutorialThree basic CSTR.xlsx:
TutorialThree basic CSTRand
TutorialOne basic Effluentfrom the
My Process Unit Category. Also, let's select
Advancedoption in the
MODEL SETUPstep. SUMO should then display
Mini_Sumoat the bottom of the drawing board window:
muOHO_T. This is a parameter associated with the
Mini_Sumo.xlsx for this
muOHO_T, we find that it is used in the very first process rate equation of the
Modelworksheet. In addition, a search throughout this file
CTRL+Freveals that it is calculated in the
Calculated variablesworksheet based on parameters like
Tbasewhich are defined in the
Parametersworksheet. Notice how Greek letters in Excel are translated into their latin equivalent in SUMO and commas are replaced with underscores. So what is referred to as
muOHO_Tin SUMO is actually
μOHO,Tin the Excel file.
PARand calculated variables
Model Baseusing the following two lines in
TutorialThree basic CSTR.xlsx
muOHO_Tno longer appears. But instead we have a new error related to
kLaGCH4_bub. After searching the
Mini_Sumo.xlsxwe find it in the
Methane gas transfer - bubblesrate in the
Modelworksheet. Interestingly, it does not appear in the
Calculated variablesworksheets. Actually, SumoSlang is looking for this to be calculated directly in the process unit file. For example in the standard library CSTR process units, this parameter would be calculated in
G.SVis expanded by SumoSlang to include all gas phase state variables including
Codeworksheet and assigning them placeholder values of
kLacoefficients. SumoSlang provides a nice way to handle this by adding a
Ruleto the calculation of mass balance. This
Rulespecifies that the mass balance will only be calculated for state variables
SVwhich have been identified in
Model Baseto have
Handling(Integrated). The handling of each of the state variables is identified in the
Componentsworksheet table heading
Mini_Sumo.xlsxyou will find that most state variables are
Integratedbut gases are
PARand calculated variables
Model Base. In addition, the reliance of the SUMO standard model library on calculation of gas transfer
kLacoefficients in the
Process Codewas demonstrated. The updates to the
basic CSTRprocess unit code in this tutorial makes it compatible with the standard SUMO
Model Base. However, there is still one more step required to make it compatible with the standard SUMO
Process Units. This final change is demonstrated in Tutorial Four.
TutorialThree basic CSTRfolder and rename it
TutorialFour basic CSTR. Update the names of the files in this folder to make it consistent with the folder name and also remember to change the name of the process unit file referenced inside the
Mini_Sumomodel as described in Tutorial Three but using the
TutorialFour basic CSTR.
TutorialOne basic Effluentand replace it with the
Effluentelement from the standard SUMO
Flow elements. When we try to build this model we get the following error:
Effluentto the value in the effluent of the
basic CSTR. A review of the
Model Baseindicates that
XBIOis a calculated variable
CVARand so we conclude that our code is not mapping
..outpof the reactor. We can add the following line to the
TutorialFour basic CSTR.xlsxto rectify this:
Effluentelement. Success! And when we mouseover the
Effluentelement we see the calculated variables from the
Model Basedisplayed on the screen:
CVARto the effluent of our
basic CSTRprocess unit. This is important because it makes our process unit compatible with the standard library of SUMO process units. Many of these process units are very simple like splitter and mixer element that do need to not interface with the
Model Base. They therefore rely on the mapping of both
CVARfrom upstream process units. Based on these four tutorials you have the fundamental tools to build custom process unit models that can leverage the
Model Baseand interface with the rest of the SUMO standard library of
Process Units. So have fun! For further tips on style I suggest the BoSS as well as studying some of the standard library
The previous tutorials provided an overview of how to get started building customized process models in SumoSlang. What are some good next steps? How about the following:
SVare preferentially directed to one outlet at the expense of the other. Looking at how this is coded for a hydrocyclone in the standard SUMO library
C:\Dynamita\Sumo21\Process code\Process units\Separators\Cyclonemight be a good place before getting started with your own customized version.
\Dynamita\Sumo21\Process code\Process units\Bioreactors\Ponduses the code for an equalization basin
\Dynamita\Sumo21\Process code\Process units\Flow elements\Equalization basinto model the interaction between a pond water column and its sediment layer. Note how the
Pondmodel includes an additional worksheet named
Structurewhich invokes several process units from the standard library including the
Variable volume equalization basin.
\Dynamita\Sumo21\Process code\Process units\Bioreactors\PFR.
 SumoSlang can be a little intimidating to the uninitiated, even for an experienced modeller. These tutorials are written for you if you are already familiar with how process models work, the Gujer matrix, systems of differential equations, maybe you have even done some coding on your own, but nothing as a sophisticated as what's "under the hood" of a commercial simulation software package like SUMO. Imagine Orville Wright transported in time into the cockpit of a 747. Arguably he would know as much as anyone about airplanes and how to fly them. But in a 747 cockpit there are so many buttons, so many little lights, he would have no idea what does what! No question of "learning by doing". Common sense dictates he should not touch anything without supervision and hours of training. You think this example too dramatic? After all, no one ever died crashing their computer. True, but the fact is that it is easier to learn when complexity is stripped away. And this is just as true for modelling as it is for learning to fly an airplane. After all if Orville Wright had been forced to learn to fly in a Boeing 747, then the history of aviation might have turned out very differently.
 The BoSS aka Book of SumoSlang
 When do we need to code SumoSlang? Can't we create models directly in SUMO? In fact, for most cases, creating models doesn't require any coding at all. A novel BNR process may be unique and different from any other BNR process in the world, but it is still just a combination of aerated and unaerated bioreactors. So no need for SumoSlang, just drag and drop bioreactor elements into the SUMO drawing board and away you go, happy modelling! But suppose the model involves a hybrid reactor with unique interactions between suspended and attached growth, maybe even something interesting happening with the gas phase too. And perhaps there is no process unit in the standard SUMO library that adequately captures the unique behavior in this reactor. This is a more complex case and in most commercial software you would be stuck. But in SUMO it's not a problem because you can just code it yourself.... in SumoSlang!
 Note that if you find a directory named "Process Code" but not "My Process Code" then you chose separate locations for the "Install" and "Working" directories on installation of SUMO. Another way to find the location of "My Process Code" is from the main menu of the SUMO "View | Directories | My process code".
 The names of these files is important. First, it is critical that the "Group Info" file include the same name as the folder in which it is found. For example, if the folder name is "Industrial DAF" then the "Group Info" file would need to be "Industrial DAF Group Info.xlsx". Or, since in this case the folder name is "TutorialOne basic CSTR" then the file name is "TutorialOne basic CSTR Group Info.xlsx". There are no constraints on the image file and other ".xlsx" files names other than no special characters, that includes hyphens! The names of the image file(s) will be referenced in the process unit excel file(s) and in a similar manner the names of the process unit excel file(s) will be referenced in the Group Info file. I use "(s)" in "file(s)" to indicate that there can be one or several of these. There can, however, be only one "Group Info" file.
 You might ask "Which state variables?" "I haven't defined any state variables yet!" The state variables refer will be the ones associated with the Model Base file that is activated in the SUMO flowsheet. When you open SUMO, the default Model Base is the Sumo1 model. This model includes some X state variables and so
outp..L.SV refer to the entire list of liquid state variables associated with the input and output streams to our process unit, the basic CSTR. If you were to change the Model Base file to something different, Sumo2 or maybe your own custom Model Base, then
L.SV would refer to state variables in that Model Base file.
 What is the best way to create images for the drawing board? In this case I have used Powerpoint to create a rectangle with some text inside it. Then I select the image, right click and select "Save as Picture" from the drop down menu. In order to create some space in the image for the ports to appear, create a second rectangle behind the blue one. The second rectangle should have no fill and no outline. But it will define the boundaries of the image file slightly larger than the blue rectangle. This will create space for the ports to appear.
 The purpose of deparametizing the model in Tutorial Two is so that we do not need to include code to import the
Model Base "parameters" or "PARAM" in
basic CSTR.xlsx. There are different ways to import "parameters" from the
Model Base into the
Process Units code and so it is preferable to treat this in a separate tutorial.
 The stoichiometry of the growth of nitrifiers is presented at its simplest here. The utilization of 1 g NH4-N generates Y g of nitrifying organisms
XNITO. Therefore to generate 1 g of
XNITO we require 1/Y g of NH4-N. Assuming Y=0.15 explains the hardcoded values of -6.667 and +6.667 for ammonia and nitrate, respectively.
 Don't forget to check out the BoSS aka Book of SumoSlang!
 SumoSlang allows you to identify and perform calculations on the liquid state variables
L.SV separately from the longer list of all state variables
SV which also includes gaseous components
G.SV associated with bubbles and head space. This is a useful distinction because
L.SV travel from reactor to reactor whereas
G.SV do not. How does SumoSlang know whether
SV is an
L.SV? SumoSlang looks for these definitions in in the
Phase column of the
Components worksheet of the
Model Base. Take a look in our
TutorialTwo_Mini_Sumo.xlsm or any other of the files in the SUMO
 On my computer this file is located in
C:\Users\cdhou\AppData\Local\Dynamita\Sumo21\Process code\Model base\Full plant models.
 On inspecting coding of
CSTR with diffused aeration and calculated DO.xlsx from the standard SUMO process unit library we find
PAR defined three times in the
Parameters worksheet and then another three times in the
Code worksheet. What's going on? Do understand this we need to look at the
Rule column. First, in the both worksheets, the three definitions of
PAR apply, respectively, to
Type(Equilibrium). So the first thing to understand about these definitions is that they import parameters from the
Model Base depending on whether the table heading in the
Parameters worksheet includes
Type(Equilibrium). Secondly, in the
Parameters worksheet these definitions are only applied if
In contrast, in the
Code worksheet, the rules are opposite:
InheritequPAR. Which will prevail? The answer lies in the definitions for these inheritances which are found in the
Unit worksheet. Since these inheritance parameters are assigned to
TRUE, only the definitions of
PAR from the
Code worksheet apply.
PAR is defined in the
Code in terms of the parent unit
So what does this mean? What is the parent unit? In short,
Parent..PAR can be thought of as a set of "Global parameters" that are applied to all process units in the SUMO flowsheet. "Local parameters" only apply if the user makes "local" changes to the
Key parameters as shown below. If local changes are made, then the relevant inheritance parameters (
InheritequPAR) for this process unit will switch to
 Located on my computer at
C:\Users\cdhou\AppData\Local\Dynamita\Sumo21\Process code\Process units\Bioreactors\CSTR\CSTR with diffused aeration and calculated DO.xlsx