At your command
xxx
You interact with the Universal Simulator software through the commands listed here. For a quick introduction to the most common commands (you will need to know only a handful), check out the Intro.
xxx
To be written
xxx
To clear the prompt dialog simply type:
> clear
The <Ctrl+L>
shortcut will also evoke the clear
command.
xxx
The run automatically copies its output to the clipboard. If you have used the clipboard for other purposes after a run
then you don't need to run the boxscript again you can simply use the clip
command to re-create the clipboard with the simulation output. This is particularly useful if a run
takes a long time.
xxx
The debug
command works just like run
. You cannot give it a boxscript as an argument though; it always works on the latest loaded or run boxscript:
> load demo/butterfly.box
...
> debug
...
debug
produces a lot of output at the Universal Simulator prompt, easily hundreds or thousands of lines. It will write a line reporting whenever it is carrying out a computational step on a box. debug is useful if you program crashes and you want to pinpoint exactly where it happens.
xxx
To be written
xxx
There are two ways to open a boxscript for editing. The first one is to open the boxscript from your editor's File|Open menu. If you are uncertain where the boxscript resides, you can find the input folder with the get folders command:
> get folders
Alternatively (and much easier), you can first load the boxscript and the invoke the edit
command:
> load demo/butterfly.box
...
> edit
The very first time you use the edit
command on a computer, it will not know which program to use to open a file with the .box type. Therefore, you will be queried which program you want to use to open the boxscript. Choose a text editor, not a word-processing program. On Windows, choose Notepad++ or Notepad.
Feel free to keep the boxscript open in the editor, while you are loading and running the boxscript in Universal Simulator. Just remember to save any changes to the boxscript in the editor before you re-load the boxscript in Universal Simulator.
xxx
Use find
to find all the nodes (i.e., boxes and ports ) in the model that match a certain path. The find
command takes a path as its single argument, for example, to find all the boxes of the Stage
class in the model:
> load demo/butterfly.box > find Stage::*
Stage sim/butterfly/egg Stage sim/butterfly/larva Stage sim/butterfly/pupa Stage sim/butterfly/adult
For each match, you will get one line with the class name and the full path to the node. Here, we found four boxes. You would possibly like to proceed with help Stage
to find the documentation for the Stage class, or maybe list Stage::* p
to see the current value of all the ports for each of the four boxes. Read more about help and list.
If you use find
to look up ports, you will be told the type of each port:
> find weather[input::*]
Port string sim/weather[fileName] Port string sim/weather[dateColumnName] Port string sim/weather[timeColumnName] Port bool sim/weather[cycle] Port datetime sim/weather[calendarDateTime]
Here we have found five nodes of the Port
class. Three are of type string
(i.e. a piece of text), one is of type bool
(i.e., with value TRUE
or FALSE
) and one a datetime
(i.e. a calendar date in combination with a time of the day).
If you are wondering about the notation for the paths above (Stage::*
and weather[input::*]
) then read up on paths. If you try out find .
, you will find the root box (often called sim
), because the root it in focus from start. You can move the focus of the find and list commands using the go command.
xxx
If you wonder where the boxscripts are located or where your output is going, use the get folders
command. You will then see something like this
> get folders
Work folder: absolute path '.../UniversalSimulatorHome' Input folder: relative path 'input' resolves to '.../UniversalSimulatorHome/input' Output folder: relative path 'output' resolves to '.../UniversalSimulatorHome/output'
The ...
part will be something else on your computer. There are three folders to have in mind:
The work folder is where you put files related to model development. If nothing else it serves as a folder to keep the input and output folders neatly in one place. This is the standard layout shown above. If you want to change it then consult the set folder command.
xxx
The go
command is used together with the find and list commands. After loading a boxscript the root node is the focus node. The focus node is used as the reference node, when you use find
or list
with a relative path (i.e. one beginning with one or two periods). You use go
to change the focus node:
> load demo/butterfly.box
Constructing... Amending... 15 boxes created
> find .
Simulation sim
> go egg
Now at Stage sim/butterfly/egg
> find ..
Box sim/butterfly
> run
...
> go time
Now at DayDegrees sim/butterfly/time
> list . x
DayDegrees time >step = 5.5 oD >> sim/butterfly/egg[timeStep] >> sim/butterfly/larva[timeStep] >> sim/butterfly/pupa[timeStep]
Beyond the use of find
and list
, it does not matter what the current focus node is.
xxx
The head
command shows the first n lines of the lates simulation output (default n=6). It mimics the behaviour of the R head command:
> run demo/butterfly.box
...
> head
Showing .../UniversalSimulatorHome/output/butterfly_nnnn.txt Tavg egg.content larva.content pupa.content adult.content iteration step 10.4 100.0 0.0 0.0 0.0 1 0 10.5 100.0 0.0 0.0 0.0 1 1 11.0 100.0 0.0 0.0 0.0 1 2 9.4 100.0 0.0 0.0 0.0 1 3 10.1 100.0 0.0 0.0 0.0 1 4 10.0 100.0 0.0 0.0 0.0 1 5
Write head n
to show up to n lines:
> head 3
Showing .../UniversalSimulatorHome/output/butterfly_nnnn.txt Tavg egg.content larva.content pupa.content adult.content iteration step 10.4 100.0 0.0 0.0 0.0 1 0 10.5 100.0 0.0 0.0 0.0 1 1 11.0 100.0 0.0 0.0 0.0 1 2
xxx
The help
command gives you quick access to information on available commands (applicable a the Universal Simulator prompt) and Box
classes (available to compose boxscripts).
The information shown by help depends on the options you give it:
help
or help ?
provides an overview of the help optionshelp c
shows all commandshelp p
shows all pluginshelp <class name>
shows specific class documentationhelp <plugin name>
shows specific plugin documentationThe output from help c
will list all the commands explained here plus some experimental ones.
If a boxscript is not working, maybe it's because a plugin is missing? You can check out the installed plugins with help p
:
> help p
boxes -Basic building blocks command -Commands for the prompt student -Student playing ground
xxx
ht
works the same way as if you write head followed by tail. It shows the first and last n lines of the output with n=6 as the default value. Here we try with n=3:
> ht 3
Showing .../output/butterfly_0020.txt Tavg egg.content larva.content pupa.content adult.content iteration step 10.4 100.0 0.0 0.0 0.0 1 0 10.5 100.0 0.0 0.0 0.0 1 1 11.0 100.0 0.0 0.0 0.0 1 2 ... 14.9 0.0 0.0 0.0 0.0 1 150 11.2 0.0 0.0 0.0 0.0 1 151 10.5 0.0 0.0 0.0 0.0 1 152
xxx
Sometimes you want to review one of your recent simulations. latest
will show you the name of the latest 10 boxscripts that you loaded or run.
xxx
You use the libr
command to check that you've got the necessary R packages installed. Thus libr
should be one of the very first commands that you invoke, once you've got Universal Simulator started. Use it with the l
option to generate code that will load the necessary libraries in R:
> libr l
# R packages needed by Universal Simulator library("colorspace") library("ggplot2") library("ggpubr") library("gridExtra") library("lubridate") library("plyr") library("reshape2") library("scales") library("splines") library("stringr") R code copied to clipboard! You may paste it into R.
You can paste the clipboard at the R prompt and check for any error messages that you are missing one or more packages.
If you miss some packages, use the libr
command again, this time with the i
option:
> libr i
# R packages needed by Universal Simulator install.packages("colorspace") install.packages("ggplot2") install.packages("ggpubr") install.packages("gridExtra") install.packages("lubridate") install.packages("plyr") install.packages("reshape2") install.packages("scales") install.packages("splines") install.packages("stringr") Copy and paste into R for any library you are missing.
This time nothing is put into the clipboard for you. You need to copy and paste into R those lines for which you are missing the library.
This whole procedure is only necessary first time you have installed Universal Simulator or if you have just (re-)installed R.
xxx
You use list
to inspect the structure of the currently loaded boxscript. You can also use it to find out the current values of ports. To try out the examples below, first do load demo/butterfly.box
.
In general you can use list
in three ways:
list
list butterfly
list butterfly pr
Here, butterfly
was used as a simple example of a path leading to just one box.
The options explained further below are
b
(to show boxes)r
(to show recursively)p
(to show ports)i
(to show input ports)o
(to show output ports)m
(to show imported ports)x
(to show exported ports)s
(to show ports in short format)To get an overview of the options at the prompt, type list ?
.
If you list
after load
, you will see the default values of ports. If you have run
the script, you will see the final values of the ports (see examples).
The default path is .
(i.e. the box in focus). You can move the focus of the find and list commands using the go command. The default options are br
. Hence, list
on its own yields list . br
.
Use list on its own to see all the boxes. The hierarchy of boxes inside boxes (or of parent-child relationships to use another metaphore) are shown by indentation:
> list
Simulation sim Calendar calendar Records weather Box butterfly DayDegrees time Stage egg Stage larva Stage pupa Stage adult OutputR PageR PlotR PlotR OutputWriter outputWriter OutputSelector selector
For each box is shown its class name followed by its object name, if it has such.
To focus on what box and its contents (i.e., its children, grandchildren, and so forth) follow list by the box name:
> list butterfly
Box butterfly DayDegrees time Stage egg Stage larva Stage pupa Stage adult
The default options are br
, so you will always recurse through boxes if you don't include any options. Here, we have included the default br
explicitly to assist the our understanding:
> list sim br
Simulation sim Calendar calendar Records weather Box butterfly DayDegrees time Stage egg Stage larva Stage pupa Stage adult OutputR PageR PlotR PlotR OutputWriter outputWriter OutputSelector selector
First, list
found one box on the path (sim
). It then proceded to recurse through and list all its descendant boxes.
Here, list found 5 boxes on path (allthe children of sim
). It then proceded to list each of those children recursively:
> list sim/* br
Calendar calendar Records weather Box butterfly DayDegrees time Stage egg Stage larva Stage pupa Stage adult OutputR PageR PlotR PlotR OutputWriter outputWriter
If we leave out the r
option, only the 5 children are listed:
> list sim/* b
Calendar calendar Records weather Box butterfly OutputR OutputWriter outputWriter
To see all ports inside a box and their current value use the p
option after the path:
> list butterfly/time p
DayDegrees time .T = 0.0 oC .timeStepDays = 0.0 d .resetTotal = FALSE .isTicking = TRUE .T0 = 5.0 oC .Topt = 100.0 oC .Tmax = 100.0 oC >step = 0.0 oD >total = 0.0 oD
Inputs are preceded with a period, outputs with a sharp parenthesis. Values are followed by their unit (nothing if they are unitless, or if the programmer of class (you?) was lazy and did not specify it). Sometimes, units are not self-explanatory (oD
in this example). If so, try out the help avalailable on the class, here help DayDegrees
. Oh, of course, it stands for day-degrees.
If values above are the default values; you will see those if you load
and then list
. If you run
the boxscript and then list
, you will get the final values after the simulation has finished together with additional information:
> list butterfly/time p
DayDegrees time .T = 10.5 oC <- sim/weather[Tavg] .timeStepDays = 1.0 d <- sim/calendar[timeStepDays] .resetTotal = FALSE const .isTicking = TRUE const .T0 = 5.0 oC const .Topt = 100.0 oC const .Tmax = 100.0 oC const >step = 5.5 oD >total = 1605.7 oD
Besides the final values, you will see const
for those inputs that had been set to constant values. For variable inputs, you will see their expressions after the arrow <-
.
To see all the input ports inside a box and their current value use the i
option after the path:
> list butterfly/time i
DayDegrees time .T = 0.0 oC .timeStepDays = 0.0 d .resetTotal = FALSE .isTicking = TRUE .T0 = 5.0 oC .Topt = 100.0 oC .Tmax = 100.0 oC
To see all the output ports inside a box and their current value use the o
option after the path:
> list butterfly/time o
DayDegrees time >step = 0.0 oD >total = 0.0 oD
To see all the imported ports inside a box and their current value use the m
option after the path:
> list butterfly/time m
DayDegrees time .T = 10.5 oC <- weather[Tavg] << sim/weather[Tavg] .timeStepDays = 1.0 d <- calendar[timeStepDays] << sim/calendar[timeStepDays]
An imported port is one referenced in an expression. For each port in the box, the imported ports are listed with a <<
prefix. Use this option to sort out a box's dependencies. You need to run
the boxscript before listing imports, because all expressions in the boxscript are only resolved when it is run.
To see all the exported ports inside a box and their current value use the `x option after the path:
> list butterfly/time x
DayDegrees time >step = 5.5 oD >> sim/butterfly/egg[timeStep] >> sim/butterfly/larva[timeStep] >> sim/butterfly/pupa[timeStep]
An exported port is one referenced in another port's expression. For each port in the box, the exported ports are listed with a >>
prefix. Use this option to find out, which other boxes make use of this box's outputs. You need to run
the boxscript before listing exports, because all expressions in the boxscript are only resolved when it is run.
To shorten the format of the listed ports use the s
option together with one or more of the options piomx
:
> list butterfly/time os
DayDegrees time step = 0.0 total = 0.0
Ports will be listed only with their name and value.
xxx
You use the load
command to read a boxscript without running it. Other commands, such as run (without boxscript argument), list and find will work on the latest loaded boxscript. You can only have one boxscript loaded at a time; when you load one, the previous will be forgotten.
load
on is own will re-load the latest loaded or run boxscript. This is useful if you just changed the boxscript in a text editor. load <boxscript>
will load the given boxscript. You can type load
followed by Ctrl+spacebar
to bring up a file picker. This is the usual procedure.
load
will report how many boxes (i.e. Box
objects) were created:
> load demo/butterfly.box
Constructing... Amending... 15 boxes created
xxx
Use this command to find out what the local decimal point character is
> location
Country: United Kingdom Decimal character in output: "."
You can include a OutputSelector box in your boxscript to use the local decimal point character, rather then the default period (i.e., 3.14
), in the simulation output.
xxx
If you wonder which boxes spend the most execution time, you invoke the profile
command after you have run a model:
> run demo/butterfly.box
...
> profile
Profile information written to '.../output/butterfly_0022.txt'
Open the .txt
file referred to in a spreadsheet program. It is a column-oriented text file with columns separated by tab characters. It is sorted to show the most time-consuming tasks from the top. Here are the top lines of the profile output:
Box | Task | msecs | Pct |
---|---|---|---|
sim/OutputR::* | debrief | 36.8495 | 22 |
sim/weather | reset | 20.1803 | 12 |
sim/weather | initialize | 14.936 | 9 |
sim/outputWriter/selector | evaluatePorts | 10.84 | 6 |
sim/outputWriter | debrief | 10.2502 | 6 |
sim/weather | update | 7.5492 | 4 |
sim | evaluatePorts | 6.935 | 4 |
sim/OutputR::* | evaluatePorts | 6.7591 | 4 |
sim | initialize | 6.3079 | 4 |
sim/outputWriter | evaluatePorts | 6.1309 | 4 |
sim/OutputR::* | initialize | 5.0027 | 3 |
sim/OutputR::*/PageR::* | evaluatePorts | 4.7758 | 3 |
sim/OutputR::*/PageR::* | initialize | 3.1924 | 2 |
sim/butterfly/time | evaluatePorts | 3.0911 | 2 |
sim | debrief | 2.8052 | 2 |
sim/outputWriter | initialize | 2.4478 | 1 |
sim/weather | evaluatePorts | 2.4023 | 1 |
sim/outputWriter | update | 2.2211 | 1 |
sim/outputWriter | reset | 1.9182 | 1 |
sim/butterfly/pupa | update | 1.7367 | 1 |
sim/OutputR::*/PageR::*/PlotR::* | evaluatePorts | 1.5676 | 1 |
sim/butterfly/egg | update | 1.4996 | 1 |
sim/calendar | initialize | 1.3263 | 1 |
sim/OutputR::*/PageR::*/PlotR::* | evaluatePorts | 1.2768 | 1 |
sim/butterfly/larva | update | 1.0669 | 1 |
sim/butterfly/egg | reset | 0.9363 | 1 |
sim/butterfly/adult | update | 0.832 | 0 |
sim/butterfly/larva | evaluatePorts | 0.7556 | 0 |
sim/butterfly/pupa | evaluatePorts | 0.6975 | 0 |
sim/calendar | update | 0.5569 | 0 |
Each box in the boxscript appears several times in the profile, because it has been logged how much time was spent on different tasks. The task is one of the steps in the computational model or the 'evaluatePorts' task, which is time spent evaluating the expressions of the inputs to the box. All tasks of all boxes will have one line in the table telling the total time spent on that task (in milliseconds) and how much that made out of the total run time (as a percentage).
Here, the boxes taking care of simulation outputs, together with the weather
box, take the most time. If you want to investigate further you can find the C++ source code by looking up the class definition (e.g., the OutputR
class is defined in the file src/plugins/boxes/output_r.cpp
) and finding the method listed under 'Task' in the profile table (e.g., the OutputR::debrief()
method). You will need to download the source code first.
xxx
quit
shuts down Universal Simulator.
xxx
To be written
xxx
To be written
xxx
To be written
xxx
run
on is own will load and run the latest loaded or run boxscript. run <boxscript>
will load and run the given boxscript. You can type run
followed by Ctrl+spacebar
to bring up a file picker.
run
first reports the number of boxes creates (well, actually load
does that behind the scenes). It continues to report at the simulation runs throught the steps of the computational model.
> run demo/butterfly.box
Constructing... Amending... 15 boxes created Initializing... Resetting... Updating... Cleaning up... Debriefing... R script written to 'C:/Users/au152367/Documents/QDev/UniSim3/output/butterfly_0013.R' Executable R snippet copied to clipboard! Data frame written to 'C:/Users/au152367/Documents/QDev/UniSim3/output/butterfly_0013.txt' Finished after 163 msecs in step 152/152
After the simulation has finished it reports, where the generated text output and R script files are located; that will be in your output folder. You are also reminded about the contents of the clipboard, which you are now expected to paste at the R prompt. The last line tells you how long it took and for how many steps (or iterations, if more than one) it was running.
xxx
You can use the get folders command to find the current location of your work, input and output folders:
> get folders
Work folder: absolute path 'C:/Users/au152367/UniversalSimulatorHome' Input folder: relative path 'input' resolves to 'C:/Users/au152367/UniversalSimulatorHome/input' Output folder: relative path 'output' resolves to 'C:/Users/au152367/UniversalSimulatorHome/output'
You can change any of these folders with the set folder
command. It comes in three flavours described below: set folder work
, set folder input
and set foldet output
.
This is how you change the work folder:
> set folder work D:/Documents/ipm-model
Work folder: absolute path 'D:/Documents/ipm-model' Input folder: relative path 'input' resolves to 'D:/Documents/ipm-model/input' Output folder: relative path 'output' resolves to 'D:/Documents/ipm-model/output' >
You must provide an absolute path to the work folder. If you don't know what an 'absolute path', look it up. In this case it is D:/Documents/ipm-model
. I recommend that you have no spaces in the path, as it can cause all kinds of trouble. General rule: Never put spaces in a folder name.
Here we kept the default input and output paths, which are both relative paths, aptly named input
and output
. These paths are interpreted as being relative to the work folder, hence they end up on the absolute paths D:/Documents/ipm-model/input
and D:/Documents/ipm-model/output
in this example.
There are two magic keywords you can use for the path you provide for the work folder. They are HOME
and DEV
as described next.
Set the work folder to HOME
to restore the work folder to its default value:
> get folders
Work folder: absolute path 'D:/Documents/ipm-model' Input folder: relative path 'input' resolves to 'D:/Documents/ipm-model/input' Output folder: relative path 'output' resolves to 'D:/Documents/ipm-model/output' > set folder work HOME Work folder: absolute path '.../UniversalSimulatorHome' Input folder: relative path 'input' resolves to '.../UniversalSimulatorHome/input' Output folder: relative path 'output' resolves to .../UniversalSimulatorHome/output'
This is just a convenience since the your home folder may be akward to find on your computer.
Set the work folder to DEV
to set the work folder to your software development folder. This might be useful if you have downloaded the source code for Universal Simulator and you want to keep your boxscripts and C++ code in the same folder:
> get folders
Work folder: absolute path '.../UniversalSimulatorHome' Input folder: relative path 'input' resolves to '.../UniversalSimulatorHome/input' Output folder: relative path 'output' resolves to .../UniversalSimulatorHome/output'
> set folder work DEV
Work folder: absolute path '.../Documents/dev/UniSim3' Input folder: relative path 'input' resolves to '.../Documents/dev/UniSim3/input' Output folder: relative path 'output' resolves to '.../Documents/dev/UniSim3/output'
xxx
I never needed to change the input folder but it would go like this using set folder input
:
> get folders
Work folder: absolute path '.../Documents/dev/UniSim3' Input folder: relative path 'input' resolves to '.../Documents/dev/UniSim3/input' Output folder: relative path 'output' resolves to '.../Documents/dev/UniSim3/output'
> set folder input test-input
relative path 'test-input' resolves to '.../Documents/QDev/UniSim3/test-input'
xxx
I have never needed to change the output folder either (see set folder input) but it would go like this using set folder output
:
> get folders
Work folder: absolute path '.../UniversalSimulatorHome' Input folder: relative path 'input' resolves to '.../Documents/dev/UniSim3/input' Output folder: relative path 'output' resolves to .../Documents/dev/UniSim3/output'
> set folder output bucket
relative path 'bucket' resolves to '.../Documents/QDev/UniSim3/bucket'
xxx
To be written
xxx
The tail
command shows the last n lines of the lates simulation output (default n=6). It mimics the behaviour of the R tail
command:
> run demo/butterfly.box
...
> tail
Showing .../UniversalSimulatorHome/output/butterfly_nnnn.txt Tavg egg.content larva.content pupa.content adult.content iteration step 14.5 0.0 0.0 0.0 0.0 1 147 15.0 0.0 0.0 0.0 0.0 1 148 15.2 0.0 0.0 0.0 0.0 1 149 14.9 0.0 0.0 0.0 0.0 1 150 11.2 0.0 0.0 0.0 0.0 1 151 10.5 0.0 0.0 0.0 0.0 1 152
Write tail n
to show up to n lines:
> tail 3
Showing .../UniversalSimulatorHome/output/butterfly_nnnn.txt Tavg egg.content larva.content pupa.content adult.content iteration step 14.9 0.0 0.0 0.0 0.0 1 150 11.2 0.0 0.0 0.0 0.0 1 151 10.5 0.0 0.0 0.0 0.0 1 152
xxx
To be written
xxx
Just in case you have forgotten what you are doing, the what
command will tell you the name of the latest loaded or run boxscript.
xxx
To be written
xxx
xxx
xxx
The escape key moves the cursor to the end of the dialog and offers you a fresh dialog.
Your usual shortcut for copying the currently selected text to clipboard.
Shortcut for the
clear
command.
Your usual shortcut for pasting the clipboard contents at the position of the cursor.
Shortcut for the
quit
command.
Shortcut for the
run
command.
The usual copy-paste-cut menu pops up when you right-click (Windows) or shift-click (Mac) or whatever (Linux).
Download the latest version with the newly published Cereal Aphid-Fungus model. Also includes the Virtual Greenhouse model.
5 Oct 2023
Read our paper on the Cereal Aphid-Fungus model and study the detailed documentation. Any questions? Write us.
2 Aug 2023
We remain candy-coloured until further notice.
1 Aug 2023
Any questions concerning our models and tools? Interested in visiting the lab? Want to chat online? Write us.