In the root directory of V-HAB, a "vhab" control class exists which can be used to start simulations. Each simulation in turn is initialized by a "setup" class, which has to reside in the respective user directory (e.g., and for this page as an example, in "user/+tutorials/+p2p", file "setup.m"). Setup files have to derive from the basic "simulation.infrastructure" class that provides methods like "configureMonitors" and "plot" used by the setup file to create the simulation. This basic class also contains the commands to control the progress of the simulation, like "pause", "stop", "tickFor" etc.
Below, the "vhab" and the "setup"/"simulation.infrastructure" classes are briefly described.
The "vhab" Class to control the Virtual Habitat Simulation
In the root directory of the STEPS/V-HAB repository, a static class named "vhab.m" can be found. The term "static class" right now simply means: several methods are available under the namespace "vhab". Those serve to initialize V-HAB, clear variables, and start simulations.
vhab.init()
When downloading V-HAB and switching to the root directory of the download, V-HAB functionality is actually not immediately available, as the appropriate paths are not yet added to the Matlab path. Therefore, to initialize V-HAB, the command on the right can be used.
Note: when starting a simulation, V-HAB executes "vhab.init()" automatically, so this method does not need to be called manually, if one simply wants to start a simulation.
vhab.clear()
When code was changed, or memory should be freed, the command on the right can be used. Often, this command is not needed, but when used, one of its advantages over the Matlab "clear all" command is that it preserves breakpoints (exept vhab.clear(false) is called).
>> vhab.init() -------------------------------------- -------- V-HAB Initialization -------- -------------------------------------- >>
>> vhab.clear() % preserves breakpoints >> vhab.clear(true) % removes breakpoints as well
vhab.exec()
Used to start a new simulation. It has three predefined parameters, and an arbitrary amount of additional ones directly passed through to the simulation setup:
- simulation name: path to the setup class of the simulation (string)
- configuration parameters: can be used to set properties on vsys objects (containers.Map)
- solver parameters: can be used to influence the solving process (struct)
- ... (passed through to simulation setup)
The first parameter is in the format of a Matlab package path. The associated file in the example on the right would be "user/+tutorials/+p2p/setup.m". Setup files should only be placed within the "user" space.
The third parameter can be a struct (or "[]" if omitted), containing some parameters influencing the solving process. The most important right now is "rUpdateFrequency". The smaller the value, the less often "matter.phase" objects will update themselves.
Note: often, setting a lower "rUpdateFrequency", might at first speed up the simulation. Then, the lower the value gets, as the simulation becomes less stable, the simulation speed will go down again. Sometimes it might even make sense to set a higher value for "rUpdateFrequency", leading to more stable flow rates therefore speeding up the simulation. Long story short: you CAN play with this parameter, there's just no guarantee for anything.
>> vhab.exec('tutorials.p2p.setup', [], struct('rUpdateFrequency', 0.01))
Configuration Parameters
This is a feature that can be used in "vsys" derived classes. To activate the behavior, the code on the right needs to be placed at the appropriate place in the class constructor.
Via configuration parameters, it is then possible to set the "vsys" properties to any value - therefore be aware that it would be possible to set attributes to ANY values.
To configure a specific "vsys", a containers.Map has to be passed in. Various key/value combinations can be provided, with the value being a struct holding all data (attribute name as struct key, new attribute value as struct value). The key of the containers.Map can address the "vsys" in two ways:
- constructor name: if your "vsys" resides in "user/+tutorials/+p2p/+systems/Example1.m", the according key would be "tutorials.p2p.systems.Example1"
- path: based on the actual path of the "vsys" in the simulation. If the "Example1" vsys above would be initialized with a name of "topLevel", and had a child named "leftBranch", the according path would be "topLevel.leftBranch".
eval(this.oRoot.oCfgParams.configCode(this));
V-HAB Simulation Object
After a simulation executes, the Matlab base workspace contains the variable "oLastSimObject', which represents the simulation object. It contains:
- toMonitors: struct with monitor objects, e.g. the logger, or the console output
- oSimulationContainer: root container for the actual simulation vsys hierarchy
Note: if dumping to .mat files was active, the simulation object will NOT contain all data. Else, you could just save the variable to a .mat file.
The object contains several methods that can be used to controll the simulation, as can be seen on the right.
To save the simulation to a file, the following command can be used:
oLastSimObj.saveSim('fileNameAppendix')
Saves the .mat file in the "data" directory.
>> oLastSimObj.tick() >> oLastSimObj.tickFor(10) % run 10 ticks >> oLastSimObj.tickTo(10000) % run until this tick is reached >> oLastSimObj.advanceFor(1) % advance one second >> oLastSimObj.advanceTo(3600) % advance to this simulation time >> oLastSimObj.plot() % plot data