1. Introduction
1.1. Command line |
1.2. Running SimTree |
1.4. Simulation methods |
1.7. Usage examples |
1.8. First steps |
1.9. Reporting bugs and submitting feature requests |
1.10. Help sources |
1.11. Hints and tips |
2. SimTree Commands
2.1. Command Overview |
2.2. Help and information commands |
2.2.1. Command intro |
2.2.2. Command spec |
2.2.3. Command advanced |
2.2.4. Command help |
2.2.5. Command news |
2.3. Handling of simulation parameter values in the results tree |
2.3.1. Command prepare |
2.3.2. Command list |
2.3.3. Command add |
2.3.4. Command remove |
2.3.5. Command clean |
2.3.6. Command unlock |
2.4. Run simulations and collect results |
2.4.1. Command simulate |
2.4.2. Command collect |
2.5. Query and evaluate results |
2.5.1. Command query |
2.5.2. Command eval |
2.5.3. Command dump |
2.6. Management and Control |
2.6.1. Command control |
2.7. Graphical User Interface |
2.7.1. Command gui |
2.8. Misc commands |
2.8.1. Command null |
3. SimTree Options
3.1. Options Overview |
3.2. Help and information options |
3.2.1. Option --help |
3.2.2. Option --print-format |
3.2.3. Option --very-verbose |
3.2.4. Option --verbose |
3.3. Handling Simulation Parameter Value Sets |
3.3.1. Option --study-root |
3.3.2. Option --simulation-parameter-path |
3.3.3. Option --simulation-parameter |
3.3.4. Option --force-all-values |
3.3.5. Option --force-delete-foreign-files |
3.4. Simulate and Collect |
3.4.1. Option --remote-process-slots |
3.4.2. Option --local-process-slots |
3.4.3. Option --batches |
3.4.4. Option --drops |
3.4.5. Option --simulation-binary |
3.4.6. Option --parameter-file-template |
3.4.7. Option --filter-file |
3.5. View and Evaluate Results |
3.5.1. Option --result-path |
3.5.2. Option --column-definition |
3.5.3. Option --graph-writer |
3.5.4. Option --max-depth |
3.6. Configuration handling |
3.6.1. Option --ignore-default-config |
3.6.2. Option --save-config |
3.6.3. Option --replace-config |
3.6.4. Option --load-config |
3.7. Management and control |
3.7.1. Option --control-command |
4. Advanced topics
4.1. Saving and loading configurations |
4.2. Properties |
4.3. Execution requirements |
4.4. Hooks |
4.5. Attributes |
5. SimTree behavior specification
5.1. Definitions and conventions |
5.2. Design goals |
5.3. Consistency rules and checks |
5.4. Simulation execution |
5.5. Corner cases and how they are handled |
6. Control
6.1. Control overview |
6.2. Control reference |
6.2.1. Control object slots |
6.2.2. Control object ws |
6.2.3. Control object procs |
SimTree is a tool to support performing simulation studies. It works in close cooperation with simulation programs based on IKR SimLib, either the C++ Edition or the Java Edition.
SimTree is used to define the simulation parameters for a simulation study, to run simulations to generate results, to collect simulation results from independent runs and to query and evaluate the results of a simulation study.
Each simulation study with its metadata and its results is located in a directory of the file system which is called the StudyRoot. SimTree always requires the StudyRoot to be set at the very beginning of its operation.
More information is available in the following sub topics. Type 'SimTree intro-<Topic>' to view this content:
commandline Giving commands and options on the command line
startup How to start and run SimTree
bugs Reporting bugs
parameters Handle simulation parameters (add, remove, list)
run Generate results (simulate, collect)
eval Evaluate results (query, dump, eval)
examples Some examples
first-steps First steps when using SimTree
doc Overview on getting help
hints Hints resulting from daily operation
SimTree contains build-in help for all command and options. Type
SimTree to get a list of commands
SimTree <command> --help to get help for an command
SimTree help --<option> to get help for an option
The SimTree command line consists of a command given by its name (add, remove, ...) and one or more options.
A command name is a word which denotes the command. For some commands so called variants are defined. The name of such a variant is appended to the command name separated with a - (i.e. dump-visual for the visual variant of the dump command).
An option has a name which is preceded by --. Most options have additional arguments. Each command has a set of required options and accepts a (greater) set of options.
Most options have a name consisting of several words separated by -. Each option name may be abbreviated with the sequence of the first letters of each word, i.e. the --simulation-parameter option may be abbreviated with --sp.
SimTree always requires a valid StudyRoot to work. This is a directory in the filesystem where all data related to a simulation study is located. SimTree selects the StudyRoot in the following sequence:
When the --study-root option with a directory name as argument is given, this directory is selected. When the environment variable SIMTREE_STUDYROOT is defined, the value of this variable is taken as the StudyRoot. If neither --study-root is given nor SIMTREE_STUDYROOT is defined, the current directory is selected. In any case, the StudyRoot must exist.
Simulation parameters are organized in a file system directory tree, the so called results tree. The values of one simulation parameter are located in exactly one height of the results tree. Values for simulation parameters may be added or removed by SimTree. Each tuple of exactly one value for each simulation parameter is called a simulation parameter value set.
Each simulation parameter has an associated date type which is one of int, float, bool or string. The type of a simulation parameter is defined when the simulation parameter is added to the results tree.
The selection of the simulation parameters value sets which a command should use is done with a sequence of --simulation-parameter options. When no --simulation-parameter option is given, the default of sets used depend on the kind of operation:
| • | For operations which add something to the results tree (add, simulate, collect), all sets in the tree are used. |
| • | For operations which remove something from the tree (remove, clean), per default no set is used, so the operation does nothing when no --simulation-parameter option is given. In this case, the option --force-all-values selects all sets in the tree. |
When defining a simulation parameter value set with --simulation-parameter or --simulation-parameter-path options the options must be ordered as follows:
| • | If a --simulation-parameter-path option is present, this must be given before any --simulation-parameter option |
| • | The --simulation-parameter options may be given in any order |
With a sequence of --simulation-parameter options also a subset of values may be selected. When used without values after the simulation parameter name, the meaning of the omission depends on the operation: For adding operations, all values for the corresponding parameter are selected. For removing operations no value is selected. Again, in the latter case the --force-all-values option may be used to reverse the meaning for removing operations. The option --simulation-parameter-path may be used to abbreviate the selection of parameter value sets.
SimTree tries to support the user in performing methodical correct studies. For this it has built-in rules for the control of simulation studies and for consistency checks of the state of the results tree and the results in the tree.
SimTree support two simulation methods:
| • | Batch means method (BM): A simulation method where a simulate run is divided in a phase where simulated system reaches an stable state (transient phase) and one or more so called batch phases (batches) where batch results are obtained. In most cases the batch results are statistical values. The batch results are combined into final results. |
The final results may be obtained in a collect run by combining the results of several simulate runs where each simulate run generates one or more statistical independent batch results. |
| • | independent replication method (IR): A simulation method where one simulate run is divided in a phase where the simulated system reaches a stable state (transient phase) and exactly one phase where so called drop results are obtained. The drop results may be combined in final results by a collect run. |
Besides this, there are two modes of operation:
| • | First, for each simulation parameter value set the simulation program may be started to generate the results for this parameter value set. These results are called FinalResults and they are directly usable to be queried or evaluated. This "one-step" simulation is only applicable for the BM method. The number of batches may be specified with the --batches option. |
| • | Second, for each simulation parameter value set the simulation program may be started with different start values for the random number generator (so called seed). |
In this mode only preliminary results (export results) are generated which have to be collected in a separate run of the simulation program to generate FinalResults for this parameter value set. |
This "two-step" simulation is applicable both for the BM and for the IR method. For the BM method the number of batches may be specified with the --batches option. For the IR method the number of drops may be specified with the --drops option. |
In the first mode batches are called default batches (with a default seed). In the second mode so called seeded results (drops or batches) are obtained. For the BM method default batches and seeded results may be intermixed in one results tree: For each simulation parameter value set a different combination of batches and seeds may be selected.
A results tree is in one of three simulation modes:
| • | The simulation method is not yet set. This is the case when the tree contains no results (is empty). |
| • | The simulation method is BM. Then only default batch results or seeded results requested with the --batches option may be generated. |
| • | The simulation method is IR: Then only seeded drop results may be requested with the --drops option. |
The exact behavior of SimTree for these two supported methods is defined in the next chapter.
After the simulation parameters with their values are defined, simulation and/or collect runs may be done.
SimTree starts as many instances of the simulation program for different simulation parameters or for parallel runs as there are process slots defined on the command line. Process slots may be local (on the machine where SimTree is started) or remote (on machines on the net which must have mounted the same file system as the machine where SimTree is started). SimTree fills the defined slots as long as there are more simulations to run.
Before starting a simulation run, a parameter file is created for this simulation run. Base of the parameter file is the parameter file template. The the template there may be replacement pattern of the form %%<Replacement>%%. SimTree replaces the replacements from two sources:
| • | When the <Replacement> is the name of of simulation parameter the actual value of this simulation parameter is used as replacement. |
| • | When an optional attributes file exists, the content of this attribites file is used for additional replacements. |
Before using the so generated parameter file it is checked that no unreplaced sequences of the form %%<Replacement>%% are remaining.
A simulation program may also be a script which itself executes the real binary. This is required i.e. for Java based simulation programs where the script calls the Java virtual machine.
After the simulations are done and - if required - the results are collected, the results tree may be queried for results or diagrams containing curves may be generated. In most cases the FinalResults for different sets of simulation parameter values are used for queries and evaluations. In special cases the individual drop or batch results may serve as source in queries and evaluations. The dump command creates a plain dump of the content of result files.
A query is defined by a simulation parameter value set, the name of the query and a path in the print server hierarchy. The path elements are separated with :. The path elements may contain wildcards in Java syntax. The wildcard for "any string" is ".*". To select all names starting with "Meter", use "Meter.*".
#
SimTree help
Get list of commands
#
SimTree help --simulation-parameter
Get help on the option --simulation-parameter
#
SimTree add --help
Get help on the command add
#
SimTree null --help
Get a list of all options
#
SimTree prepare
Prepare the study-root, max be called any time even in already prepared study-root
#
SimTree null --simulation-binary TandemFeedback --local-process-slots 4
Save name of simulation binary and number of local slots in default config
#
SimTree null --save-config eval1 --result-path "q1 FinalResults:TandemModel:Meter2:TransferTime"
Save a query path in the configuration named eval1
#
SimTree query --load-config eval1
Load the options saved in the configuration eval1 and perform query command
#
SimTree list
List the contents of the results tree
#
SimTree list-visual
List the contents of the results tree in a graphical window
#
SimTree list --simulation-parameter MsgLen 100
List part of results tree where MsgLen == 100
#
SimTree list --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0
List part of results tree where MdgLen == 100 and ServiceTime == 1.0
#
SimTree list --simulation-parameter-path 100:1.0
The same as the previous example using a path of simulation parameters
#
SimTree add --simulation-parameter MsgLen int 100 200
Add simulation parameter MsgLen of type int with two values
#
SimTree add --simulation-parameter ServiceTime float 1.0 2.0
Add a second parameter ServiceTime with two values for all values of MsgLen
#
SimTree remove
Will do nothing, no simulation parameter values selected
#
SimTree remove --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 2.0
Remove selected parameters, remove results first
#
SimTree add --simulation-parameter-path 100 --simulation-parameter ServiceTime 4.0
Add value for ServiceTime for MsgLen 100, given by simulation parameter path
#
SimTree remove --force-all-values
Remove all simulation parameters with all values, remove results first
#
SimTree simulate --local-process-slots 4
Run simulation locally with 4 instances in parallel
#
SimTree simulate --local-process-slots 4 --batches 10
Run simulation locally with 4 instances in parallel
#
SimTree simulate --remote-process-slots cnode08 2 --remote-process-slots cnode09 2 --batches 10
Run simulation remotely on two different hosts with 2 instances on each host
#
SimTree simulate --local-process-slots 4 --batches 1:5 2:5
Run 4 parallel simulation runs with 5 batches each
#
SimTree collect
Collect results for all simulation parameter values
#
SimTree clean
Will do nothing, no simulation parameter values selected
#
SimTree clean --simulation-parameter MsgLen --simulation-parameter SericeTime 1.0
Remove results for the given simulation parameter values
#
SimTree clean --force-all-values
Remove all results
#
SimTree dump
Dump the contents of all FinalResults
#
SimTree dump-visual --sp MsgLen 1 --sp ServiceTime 1.0
Dump the contents of the FinalResults for MsgLen == 1 and ServiceTime == 1.0 in a grahical window
#
SimTree query --result-path q1 "TandemModel:Meter2:TransferTime:cintcov"
Query FinalResults from all simulation parameter value sets for one statictic value
#
SimTree query --result-path q1 "TandemModel"
Query FinalResults from all all statistic values inside the TandemModel
#
SimTree query --simulation-parameter-path 100:1.0 --result-path q1 "TandemModel"
Query FinalResults for one simulation parameter value set
#
SimTree query --result-path q1 "TandemModel:Meter2:TransferTime:cintcov" --batches 1:5
Query Result from batch 1,2,3,4,5 from seed 1
#
SimTree query --result-path q1 "TandemModel:Meter2:TransferTime:cintcov" --batches 1:[1,3]
Query Result from batch 1 and 3 from seed 1
#
SimTree query --result-path q1 "TandemModel:Meter2:TransferTime:cintcov" --batches [1,2]:[1,3]
Query Result from batch 1 and 3 from seed 1 and 2
#
SimTree query --result-path q1 "TandemModel:Meter2:TransferTime:cintcov" --batches [1,2]:[1-3]
Query Result from batch 1 to 3 from seed 1 and 2
#
SimTree eval --column-definition 0 simulation-parameter ServiceTime --column-definition 1 result-path TandemModel:Meter2:TransferTime:mean
Print results for the simulation parameter ServiceTime with the given result path
#
SimTree eval --cd 0 sp ServiceTime --cd 1 sp MsgLen --cd 2 rp TandemModel:Meter2:TransferTimeDist:pdf:.*:ubound
Print result for two simulation parameters with the given result path
In the following the steps are listed to create a new SimTree project:
| • | create a new directory which serves as the StudyRoot using normal system commands (mkdir) |
| • | make the new StudyRoot the current directory (cd) |
| • | prepare the new StudyRoot (SimTree prepare) |
| • | add simulation parameters and values to the newly created StudyRoot (SimTree add) |
| • | create the parameter file template in <StudyRoot>/MetaData/sim.par.template |
| • | put the simulation binary in <StudyRoot>/MetaData |
| • | run the simulation to generate results (SimTree simulate, SimTree collect) |
| • |
SimTree is not bug free. It may have lesser bugs in the future than now when bugs are reported. Also the feature set is not final but is currently mainly based on requirements of internal users. New features may be added on request - ideas are always welcome.
Please report bugs and submit feature requests either directly or by using the mail address ikrsimlib@ikr.uni-stuttgart.de.
SimTree contains a lot of build-in help. The following help oriented commands are defined
| • | SimTree intro starts an introduction to SimTree. This command understands a list of subcommands which display help for different topics. Type SimTree intro-<subtopic> to show the subtopics, |
| • | SimTree advanced displays advanced topics for experienced users, |
| • | SimTree spec shows definitions and internal behaviour specification of SimTree. |
| • | SimTree help gives help on each option given on the command line |
| • | SimTree <command> --help prints help for a specific command. |
A print-out version of the complete help-text is part of the SimTree distribution.
| • | SimTree is often used in a distributed computing environment where the computing nodes use NFS (Network File System) to create a common view on the users data. Unfortunately NFS has very lousy consistency semantic, so SimTree may not work correct when the results tree is traversed on different nodes. This may result in running unrequired simulations or wrong results displayed when using the list command. |
Usage: SimTree <command> <options>
The following commands are defined
| intro | Gives an introduction how to use SimTree |
| spec | Gives a more formal description of SimTree's behaviour |
| advanced | Advanced topics for experienced users |
| help | Print help for commands or options and their parameters |
| news | Print a summary of news in different versions in SimTree |
| prepare | Prepare the StudyRoot for usage by SimTree |
| list | List the contents of the results tree |
| add | Add simulation parameters or values for simulation parameters to the results tree |
| remove | Remove simulation parameter values from the results tree |
| clean | Clean batch result files and other files from the results tree |
| unlock | Remove stale locks from the results tree |
| simulate | Start simulations for the current results tree |
| collect | Collect export batch result files in a final results file |
| query | Query the results tree |
| eval | Evaluate the contents of simulation log files |
| dump | Dump the content of result files in printserver format |
| control | Change the internal behavior of a running SimTree instance (WIP) |
| gui | Start the SimTree GUI (WIP) |
| null | Does nothing, used to save configs and to display all possible options |
Type 'SimTree intro' to get an introduction to SimTree
Type 'SimTree <command> --help' to get help for a command
Type 'SimTree help --<option>' to get help for an option
Gives an introduction how to use SimTree
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree intro-<Variant>)
| commandline |
| startup |
| parameters |
| methods |
| run |
| eval |
| examples |
| first-steps |
| bugs |
| doc |
| hints |
Gives a more formal description of SimTree's behaviour
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree spec-<Variant>)
| wording |
| goals |
| consistency |
| execute |
| specials |
Advanced topics for experienced users
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree advanced-<Variant>)
| configuration |
| properties |
| system |
| hooks |
| attributes |
Gives help on the usage of command and options of SimTree.
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Prepare the StudyRoot for usage by this tool by creating subdirectories below the StudyRoot. It is ok to do this for an already prepared StudyRoot.
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree prepare
Prepare the current directory for usage by SimTree
#
SimTree prepare --study-root /u/user/home/Study1
prepare the StudyRoot given by the option
List the content of the results tree. It is shown for each simulation parameter combination whether final result files exists, whether export log files exist and whether lock files exist in the results tree. The output format may be selected with the --print-format Option.
| --print-format,--pf | defines the print format for the list command |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree list-<Variant>)
| visual | Display the content of the results tree in a visual tree window |
#
SimTree list
list content of the results tree in default format
#
SimTree list --simulation-parameter MsgLen 100
list content of results tree for value 100 of MsgLen
#
SimTree list --simulation-parameter-path 100:1.0
list content of results tree for one simulation parameter set
#
SimTree list --print-format leafs "%%indent%% [%%spname%% %%value%%]"
list for all leaf nodes the names and values of the simulation parameters
Add simulation parameters at the leaf of the results tree or add additional values for existing simulation parameters in the results tree.
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree add --simulation-parameter MsgLen int 100 200
add the simulation parameter MsgLen of type int with values 100 and 200
#
SimTree add --simulation-parameter MsgLen int 100 200 --simulation-parameter ServiceTime float 1.0 2.0
add the simulation parameter ServiceTime with two values for the given values of MsgLen
#
SimTree add --simulation-parameter ServiceTime float 1.0 2.0 3.0
add three values of ServiceTime
Remove simulation parameters or values for simulations parameters from the results tree. The directory for the given values must be empty. If this is not the case, use the command clean first.
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --force-all-values,--fav | when set, all values of not given parameters are used for removing operations |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree remove --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0
remove the given parameter values
#
SimTree remove --force-all-values
remove the complete results tree
| • | When no simulation parameter values are specified on the command line, SimTree assumes that no values are selected. When this is not what you want, either specify the simulation parameter values with the according options or use the --force-all-values option to select all values in the results tree (be careful, this may remove more values than wanted). |
| • | SimTree will not remove a simulation parameter value, whose directory in the results tree is not empty, i.e. which contains result files, batch result files or foreign files (files not created by SimTree). Use the list command to check whether the directories are empty and/or the clean command to remove files. |
Remove files for given simulations parameter value sets from the results tree.
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --force-all-values,--fav | when set, all values of not given parameters are used for removing operations |
| --force-delete-foreign-files,--fdff | when set, the clean command also deletes files not managed by SimTree |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree clean --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0
remove the results for MsgLen 100 and ServiceTime 1.0
#
SimTree clean --simulation-parameter-path 100:1.0
same as above using the simulation-parameter-path option
#
SimTree clean --force-all-values
remove all results for all values of all simulation parameters (but not lock files, see SimTree unlock)
#
SimTree clean --fav --force-delete-foreign-files
remove all files from all result directories, also files not managed by SimTree (but not lock files, set SimTree unlock)
| • | When no simulation parameter values are specified on the command line, SimTree assumes that no values are selected. When this is not what you want, either specify the simulation parameter values with the according options or use the --force-all-values option to select all values in the results tree (be careful, this may remove more values than wanted). |
When starting a simulation or collect run, SimTree creates a lock for the according batches. When SimTree or any of its subprocesses aborts for any reason, such a lock may remain and block further runs for these locked batches.
Use the command unlock to remove such stale locks for the whole results tree or parts of it.
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --force-all-values,--fav | when set, all values of not given parameters are used for removing operations |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree unlock --force-all-values
remove the locks for all simulation parameter value sets
#
SimTree unlock --spp 1:1
remove lock for one simulator parameter value set
| • | Only use this command when you are sure that no SimTree instance is walking through the results tree or unpredictable things will happen |
| • | When no simulation parameter values are specified on the command line, SimTree assumes that no values are selected. When this is not what you want, either specify the simulation parameter values with the according options or use the --force-all-values option to select all values in the results tree (be careful, this may remove more values than wanted). |
Run simulations either with batches with the default seed value or with given seed values. Simulations are skipped either when the requested results already exist or when for a simulation parameter value set the other kind of batches exist. Then use clean first.
| --simulation-binary,--sb | defines name and path of the simulation binary or script |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
| --drops,--d | defines the drops to handle |
| --batches,--b | defines the batches to handle |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
| --filter-file,--ff | defines path and name of the filter file |
| --parameter-file-template,--pft | defines name and path of the parameter file template file |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree simulate --batches 10
Perform simulation for all parameters and their values with 10 default batches (BM method)
#
SimTree simulate --simulation-parameter MsgLen 100 --batches 10
Perform simulation(s) for MsgLen 100 only, for other simulation parameters use all values for MsgLen 100 (BM method)
#
SimTree simulate --batches 1:5 2:5
Perform simulation with Seed 1 and 2 with 5 batches each (BM method)
#
SimTree simulate --drops 10
Perform simulation for all parameters and their values with 10 drops (seed values) (IR method)
Collect the results from previous executed seeded batch simulation runs (export result files) in final result files.
| --simulation-binary,--sb | defines name and path of the simulation binary or script |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --parameter-file-template,--pft | defines name and path of the parameter file template file |
| --filter-file,--ff | defines path and name of the filter file |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree collect --lps 1
perform collect for all simulation parameters where required using one local process slot
#
SimTree collect --simulation-parameter MsgLen 100 --lps 2
perform collect for MsgLen 100 using two local process slots
Query the content of result log files. Either final result files or batch log files may be queried. For syntax help see the help for the --result-path option.
| --result-path,--rp | defines a result path with its name and a sequence of PrintServerNames |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree query --rp r ".*"
Show the final results for all simulation parameter value sets
#
SimTree query --rp r ".*" --spp 1:2
Show the final results for one simulation parameter value set
#
SimTree query --rp r "TandemModel:Meter1:.*" --spp 1:1
Show a part of the final results for one simulation parameter value set
#
SimTree query --rp r "TandemModel:Meter1:.*" --spp 1:1 --batches 1
Show a part of one batch result file for one simulations parameter value set
| • | Always include regular expressions in quotes to prevent the system shell from interpreting special chars like * or ? |
The eval command allows the evaluation of simulation results by creating multi-dimensional tables with names and values which are usable as input for graph-creating tools like gnuplot and xmgrace.
Input for this command is
| • | the definition of columns which should appear in the generated tables. For this the option --column-definition is used. Each column has a number, a type and - depending on the type - additional parameters which defines what appears in this column. |
| • | The column number starts with 0 and the column numbers are consecutive without holes. |
| • | The type may be either a simulation-parameter, a result-path or a batch number. The type simulation-parameter may be abbreviated with sp, the type result-path may be abbreviated with rp and the type batch-number may be abbreviated with bn. |
| • | The third argument depends an the type: When using a simulation parameter, the additional parameter is the name of the simulation parameter. When using a result-path, the path is the additional parameter. The type batch-number has no additional argument. |
| • | One or more result-path definitions (Option --result-path) which may be referenced in the column definitions. |
| • | Further options |
SimTree generates a list of lines starting with a headline followed by data lines which contain the result ordered in the columns defined.
A evaluation is only valid when all given data sources in the column definitions result in the same number of values.
| --column-definition,--cd | defines a column in a chart |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --result-path,--rp | defines a result path with its name and a sequence of PrintServerNames |
| --graph-writer,--gw | Specifies the writer for the graph to use |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree eval-<Variant>)
| visual |
#
SimTree eval --column-definition 0 sp MsgLen --cd 1 sp ServiceTime --cd 2 rp "TandemModel:Meter1:TransferTime:Mean" --cd 3 rp "TandemModel:Meter1:TransferTime:pmcintm"
eval Mean and pmcintm for all combinations of the simulation parameters MsgLen and ServiceTime
#
SimTree eval --spp 1:1 --cd 0 sp MsgLen --column-definition 1 rp "%r1%" --cd 2 rp "%r1%:prob" --cd 3 sp ServiceTime --rp r1 "TandemModel:Meter2:TransferTimeDist:pdf:.*"
eval a distribution for one combination of simulation parameters by using a result-path
Print the content of final result files or batch result files in the legacy print server format.
| --max-depth,--md | Specifies the number of levels in the print server hierarchiy which are dumped |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --result-path,--rp | defines a result path with its name and a sequence of PrintServerNames |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
Valid command variants are (use SimTree dump-<Variant>)
| visual | Display the results in a visual tree window |
#
SimTree dump
Dump the content of all result files in the results tree
#
SimTree dump --rp r "TandemModel:Node2:.*"
Dump the content of all results below TandemModel:Node2 of all result files in the results tree
#
SimTree dump --spp 1:1
Dump the content of the result file of the given simulation parameter path
#
SimTree dump --rp r "TandemModel:Node2:.*" --spp 1:1
Combine different options
#
SimTree dump --spp 1:1 --batches 1
Dump the content of a batch result file for the given simulation parameter path
#
SimTree dump --max-depth 4 --spp 1:1 --rp 1 "TandemModel:Node1:Queue:.*"
Dump partial contents of the FinalResults for one simulation parameter value set with a maximum depth
WARNING: This feature is "work in progress" and neither fully implemented nor tested. Please use this feature only in close interaction with the developers.
The control framework allows changing the behavior of a running SimTree process (the controlled instance) by sending control requests to this controlled instance from another SimTree instance (the controlling instance). The controlled and the controlling instance of SimTree must run on the same host.
The controlling instance is called with the SimTree command control. This command requires at least the option --control-command with exactly one argument. This argument defines the request which is sent to the controlled instance. Depending on the kind of the request additional options to the control command are allowed or required.
The request consists of at least two parts (the control object and the control method) and optional further parameters for the control method. The object and the method are separated with a ., optional parameters are appended to this string separated with -.
For examples of control commands see the SimTree command control and the option --control-command.
For the communication between the controlled and the controlling instance a UNIX socket is used, which is created in the current StudyRoot. So the controlled and the controlling instance must use the same StudyRoot.
For a list of supported control objects, methods and their parameters see the full help text of SimTree.
| --control-command,--cc | defines a control request which is sent to a running SimTree instance (WIP) |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree control --control-command ws.list
list the current working set of the controlled SimTree instance
#
SimTree control --control-command slots.add --local-process-slot 1
Add one more local process slot for use by the controlled SimTree instance
#
SimTree control --control-command ws.add --spp 1:1
Add a simulation parameter path to the work list of the controlled SimTree instance
WARNING: This feature is "work in progress" and neither fully implemented nor tested. Please use this feature only in close interaction with the developers.
Start the Graphical User Interface for SimTree. Currently this allows listing the content of the results tree and dumping final and default batch results. The implementation is preliminary and should be considered unstable.
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --replace-config,--rc | save/replace the default or a named configuration |
| --save-config,--sc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --verbose,--v | when set, make more output during command execution |
| --very-verbose,--vv | when set, make much more output during command execution |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
Type SimTree help --<option-name> to get help for an option
#
SimTree gui
start the SimTree GUI
This command does nothing. It may be used to save options or to get a list of all implemented options.
| --help,--h | when set, help for the given command is requested |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
| --simulation-binary,--sb | defines name and path of the simulation binary or script |
| --parameter-file-template,--pft | defines name and path of the parameter file template file |
| --filter-file,--ff | defines path and name of the filter file |
| --result-path,--rp | defines a result path with its name and a sequence of PrintServerNames |
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
| --column-definition,--cd | defines a column in a chart |
| --graph-writer,--gw | Specifies the writer for the graph to use |
| --save-config,--sc | save/replace the default or a named configuration |
| --replace-config,--rc | save/replace the default or a named configuration |
| --load-config,--lc | load options from a saved configuration |
| --force-all-values,--fav | when set, all values of not given parameters are used for removing operations |
| --force-delete-foreign-files,--fdff | when set, the clean command also deletes files not managed by SimTree |
| --print-format,--pf | defines the print format for the list command |
| --very-verbose,--vv | when set, make much more output during command execution |
| --verbose,--v | when set, make more output during command execution |
| --control-command,--cc | defines a control request which is sent to a running SimTree instance (WIP) |
| --max-depth,--md | Specifies the number of levels in the print server hierarchiy which are dumped |
Type SimTree help --<option-name> to get help for an option
#
SimTree null --help
get a list of all implemented options
#
SimTree null --spp 1:1 --sc list1
Save the option spp in the config file list1
The following options are defined
| --help | when set, help for the given command is requested |
| --print-format | defines the print format for the list command |
| --very-verbose | when set, make much more output during command execution |
| --verbose | when set, make more output during command execution |
| --study-root | defines the root directory of the simulation studies data (the StudyRoot) |
| --simulation-parameter-path | defines a set of simulation parameter values, shortcut for --sp Options |
| --simulation-parameter | defines simulation parameter value sets for one simulation parameter |
| --force-all-values | when set, all values of not given parameters are used for removing operations |
| --force-delete-foreign-files | when set, the clean command also deletes files not managed by SimTree |
| --remote-process-slots | defines the number of process slots on a remote host |
| --local-process-slots | defines the number of processes to start on the local host |
| --batches | defines the batches to handle |
| --drops | defines the drops to handle |
| --simulation-binary | defines name and path of the simulation binary or script |
| --parameter-file-template | defines name and path of the parameter file template file |
| --filter-file | defines path and name of the filter file |
| --result-file-name | Name of log file to dump (may be given without extension) |
| --result-path | defines a result path with its name and a sequence of PrintServerNames |
| --column-definition | defines a column in a chart |
| --graph-writer | Specifies the writer for the graph to use |
| --max-depth | Specifies the number of levels in the print server hierarchiy which are dumped |
| --ignore-default-config | when set, the default configuration is not loaded |
| --save-config | save/replace the default or a named configuration |
| --replace-config | save/replace the default or a named configuration |
| --load-config | load options from a saved configuration |
| --control-command | defines a control request which is sent to a running SimTree instance (WIP) |
| --help,--h | when set, help for the given command is requested |
with this option, help for the current command may be requested.
this option is never saved |
#
SimTree add --help
request help for the add command
| --print-format,--pf | defines the print format for the list command |
arg ::= <FormatString>
The parameter defines the print format
This option of the list command specifies how the entries int the results tree should be printed.
The option has one argument which specifies how one entry should be printed. This is a string concatenated from replacement tags and additional characters. Replacement tags are enclosed in %%. The following replacement tags are specified:
| • | spname: Denotes the name of the simulation parameter |
| • | value: Denotes the value of the simulation parameter |
| • | dirname: Denotes the name of the node directory |
| • | content: Specifies a string describing what the node contains. This is meaningful for leaf nodes only |
| • | fullcontent: Same as content but also adds information about batch or drop result files |
| • | indent: Indent the line to make a proper column view. |
| • | command_addspp: Print the SimTree command to create the simulation parameter path contained in the resuls tree. This is useful to make a backup copy of the results tree structure or to duplicate an existing results tree. |
The format string is parsed for each simulation parameter contained in the node and the content is printed according to the name/value of the simulation parameters.
The content, fullcontent, indent, dirname and command_addspp tags are expanded only once for each node whereas the spname and value tags are interpreted for each simulation parameter.
Add " around the format string to prevent wrong interpretation and to allow adding spaces at the begin and the end of the format.
this option is always saved and saved in any kind of config file |
#
--print-format "%%spname%% "
print the names of the simulation parameters
#
--print-format "[%%spname%% %%value&&] "
print the names and values of the simulation parameters
#
--print-format "%%content%% [%%spname%% %%value&&] "
print the content and names and values of the simulation parameters
#
--print-format "%%command_addspp"
print the commands to create the results tree structure
| --very-verbose,--vv | when set, make much more output during command execution |
(no arguments)
this option is never saved |
| --verbose,--v | when set, make more output during command execution |
(no arguments)
this option is never saved |
| --study-root,--sr | defines the root directory of the simulation studies data (the StudyRoot) |
arg ::= <ExistingDirectory> ;
This option sets the root of the current simulation study (the StudyRoot) to the given directory. This directory must exist.
When this option is not used, the StudyRoot is determined from the environment variable SIMTREE_STUDYROOT or when this is not set, the current directory is used.
this option is never saved |
#
--study-root /u/user/home
Set the study root to the given directory
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
arg ::= (<val>) [ ":" <val> ]+
path elements are simulation parameter values and are separated with :
This option allows to specify a (probably) incomplete simulation parameter value set by giving a path of values, one for each simulation parameter in the results tree. This option is a shortcurt for a set of --simulation-parameter options. It may be given only once.
The path is defined by giving a list of values, one for each simulation parameter in the order of the simulation parameters in the tree (the first path element means the first parameter in the tree). The values are separated by a :.
After this option more --simulation-parameter values may be given to complete the simulation parameter value set. But no option --simulation-parameter may be given before this this option.
this option is always saved and saved in any kind of config file |
#
--simulation-parameter-path 100:1.0
shortcut for --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0
#
--simulation-parameter-path 100 --simulation-parameter ServiceTime 1.0 2.0 3.0
shortcut for --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0 2.0 3.0
#
--simulation-parameter-path :1.0
shortcut for --simulation-parameter MsgLen --simulation-parameter ServiceTime 1.0
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
arg ::= <name> [<type>] [!] (<val>)+ | (seq <first> <incr> <last>)
type ::= int | float | string | bool
val ::= rawValue | @<RegExp>
type is optional, when detection is possible
val is a raw value or a regular expression denoted by the char @
! means use values not in list
seq creates a list of values from <first> to <last> with increment <incr>
This option specifies one simulation parameter with its name, type and value(s). The parameter name is required, the type may be omitted when it is auto detectable.
The values may be given value by value or may be specified by a sequence of constructors. A value may be given as a raw string which is used as a value as is or as a regular expression which specifies a value pattern. Wehen using a regular expression, a special starting notifier is required. Regular expressions are not allowed when the option is used in the add command.
The values may be completely omitted. Then dependent on the command all values of this parameter in the current results tree (for "adding" operations like add, list, simulate) or no value of this parameter (for "removing" operations like remove and clean) are selected. The option --force-all-values may be used to select all values in the latter case. The option --simulation-parameter-path may be used as a short form of a sequence of this option.
When defining a simulation parameter value set with --simulation-parameter or --simulation-parameter-path options the options must be ordered as follows:
| • | If a --simulation-parameter-path option is present, this must be given before any --simulation-parameter option |
| • | The --simulation-parameter options may be given in any order |
this option is always saved and saved in any kind of config file |
#
--simulation-parameter MsgLen int 100 200 300
define parameter MsgLen of type int and three values
#
--simulation-parameter MsgLen int @[1-3]00
define parameter MsgLen of type int and a regular expression for the value
#
--simulation-parameter ServiceTime float 1.0 2.0
define parameter ServiceTime of type float with two values
#
--simulation-parameter ServiceTime float seq 1 1 10
define parameter ServiceTime with values from 1 to 10 with step 1
#
--simulation-parameter ServiceTime float ! 1 2 3
define all values for parameter ServiceTime except the values 1, 2 and 3
| • | Always include regular expressions in quotes to prevent the system shell from interpreting special chars like * or ? |
| --force-all-values,--fav | when set, all values of not given parameters are used for removing operations |
(no arguments)
Without this option, for removing and deleting commands (remove, clean, ...) the default for simulation parameters for which no value is given on the command line is to use no values for this simulation parameter.
When this option is set, the is reversed and for simulation parameters for which no values are given, all values in the tree are used.
Handle with care, this will remove a whole tree without asking.
this option is never saved |
| --force-delete-foreign-files,--fdff | when set, the clean command also deletes files not managed by SimTree |
(no arguments)
Without this option, the clean command only deletes files which were created by SimTree or by programs called by SimTree.
When this option is set, the clean command also deletes files not managed by SimTree.
Handle with care, this will remove all files which reside in the results tree.
this option is never saved |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
arg ::= <NodeName> <IntVal>
<NodeName> name of the remote host (reachable by rsh/ssh)
<IntVal> number of processes to start on this host
With this option, process slots on remote machines (reachable by rsh) may be defined. Given are the name of the remote host and the number of process slots to use on this machine. This option may be used more than once for different remote hosts.
this option is always saved but only in a named config file (not the global config file) |
#
--remote-process-slots cnode08 4
starts 4 instances of the simulation program on host cnode08
| • | Running simulations on remote slots requires in most cases the adaption of the hooks for remote execution to the local system environment. Be sure to check the hooks and adapt them. |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
arg ::= <SlotsOnLocalHost>
number of process slots in the local machine (> 0)
With this option, the number of process slots to use for a simulation or collect run on the local machine may be defined.
this option is always saved but only in a named config file (not the global config file) |
#
--local-process-slots 4
starts 4 instances of the simulation program on the local machine
| --batches,--b | defines the batches to handle |
arg ::= <BatchCount> | ("["<SeedPart>"]":["<BatchPart>"]")+ ;
SeedPart ::= <RangeList> ;
BatchPart ::= <RangeList> ;
RangeList ::= ( Number | Number-Number | Number(,Number )+ ;
BatchCount a number of batches to simulate/eval/dump
SeedPart specifies the seed indices (values) to use
BatchPart specifies the batch numbers to use
Defines the batches to simulate, to collect results from or to query/eval/dump results from. This option is only applicable to the simulation method batch means. For this method, there are two kinds of batches:
| • | Default batches: No seed value is passed to the simulation program, the simulation program uses the default seed value. For default batches Final Result files are generated immediately. |
| • | Seeded batches: A seed value is passed to the simulation program from which a start value for the random number generator is generated. Seeded batches are used for batch parallelization where only preliminary results (so called export results) are generated. A collect phase (see command collect) is required to generate the final results from the export results. |
Default batches and seeded batches must not be mixed in one call to SimTree. They may be mixed in a simulation tree for different simulation parameter value sets (not recommended).
A batch specification consists of an (optional) seed part and an required batch part. When a seed part is given, both parts are separated by a :.
The batch part and the seed part may be given as a single number ("5"), a list of numbers ("[1,2,3]"), a range of numbers ("[1-5]") or a mixture of lists and ranges ("[1-3,6,8]"). Ranges and lists are enclosed in "[" and "]".
For the simulate command, in the batch part only a single number (no list and no range) is allowed for specifying the batch count (number of batches to handle). For the query/eval/dump commands batches may be selected by lists/ranges of batch numbers.
this option is always saved but only in a named config file (not the global config file) |
#
--batches 10
select 10 default batches, no collect required
#
--batches 1:5 2:5
select 5 batches with seed 1 and 5 batches with seed 2 (10 batches in sum)
#
--batches [1,2,3]:5
select 5 seeded batches for each seed 1, 2 and 3 (15 batches in sum)
#
--batches [1,2,3]:[1-8]
select batches 1, 2, ... 8 for each seed 1, 2 and 3 (24 batches in sum), not allowed for simulate
#
--batches [1,3]:[1-4,7-8]
select batches 1, 2, 3, 4, 7 and 8 for each seed 1 and 3 (12 batches in sum), not allowed for simulate
| --drops,--d | defines the drops to handle |
arg ::= <DropCount> | ( "["<DropSpec>"]" )+ ;
DropSpec ::= <RangeList> ;
RangeList ::= ( Number | Number-Number | Number(,Number )+ ;
DropCount a number of drops to simulate/eval/dump
DropSpec specifies the seed indices (values) to use
Defines the drops to simulate, to collect results from or to query/eval/dump results from. This option is only applicable to the simulation method independent replication. A drop consists of exactly one result phase.
A drop is specified by a seed part which denotes which seed values are used for the simulation.
The seed part may be given as a sequence of a single number ("5"), a list of numbers ("[1,2,3]"), a range of numbers ("[1-5]") or a mixture of lists and ranges ("[1-3,6,8]"). Ranges and lists are enclosed in "[" and "]".
For the simulate command, only a single number (no list and no range) is allowed for specifying the drop count (number of drops to handle). For the query/eval/dump commands drops may be selected by lists/ranges of seed numbers.
this option is always saved but only in a named config file (not the global config file) |
#
--drops 10
select 10 drops with seed values from 1 to 10
#
--drops [2-20]
select drops with seeds from 2 to 20 (19 drops)
#
--drops [1,2,3]
select drops with seed 1, 2 and 3
#
--drops [1,2,3] [7-9]
select drops with seed 1, 2, 3, 7, 8, and 9
| --simulation-binary,--sb | defines name and path of the simulation binary or script |
arg ::= <ExecutableFile>
defines the relative or absolute name of the simulation binary
With this option, the name of the simulation binary to use for the simulate and collect commands may be defined. The binary may also be a script.
The given parameter is interpreted as follows: If the name is starting with / (absolute path), then the given path is taken directly as an absolute path. If the name is not absolute, it is first assumed to be relative to the MetaData directory in the given StudyRoot. If not found there, then the given name is assumed to be relative to the current working directory.
There is no default. The file must exist.
this option is always saved and saved in any kind of config file |
#
--simulation-binary TandemFeedback
use TandemFeedback as the simulation binary
| --parameter-file-template,--pft | defines name and path of the parameter file template file |
arg ::= <ParaFileTemplateName>
name of the parameter file template (absolute or relative)
This option defines path and name of the template file from which the parameter files are generated during simulation.
The given parameter is interpreted as follows: If the name is starting with / (absolute path), then the given path is taken directly as an absolute path. If the name is not absolute, it is first assumed to be relative to the MetaData directory in the given StudyRoot. If not found there, then the given name is assumed to be relative to the current working directory.
If not set, the file <MetaData>/sim.par.template is used as the template. The template file must exist.
this option is always saved and saved in any kind of config file |
#
--parameter-file-template myTemplate.def
Use the file myTemplate.def either from the MetaDataDir or from the current dir
#
--parameter-file-template /home/myTemplate.def
Use the file myTemplate.def from the dir /home
| --filter-file,--ff | defines path and name of the filter file |
arg ::= <FilterFileName>
name and path of the filter file (absolute or relative)
With this option, an optional filter file may be defined which is passed to the simulation program.
The given parameter is interpreted as follows: If the name is starting with / (absolute path), then the given path is taken directly as an absolute path. If the name is not absolute, it is first assumed to be relative to the MetaData directory in the given StudyRoot. If not found there, then the given name is assumed to be relative to the current working directory.
If this option is not set, no filter file is used. When using this option, the file must exist.
this option is always saved and saved in any kind of config file |
#
--filter-file myFilter.def
Use the file myFilter.def either from the MetaDataDir or from the current dir
#
--filter-file /home/myFfilter.def
Use the file myFormat.def from the dir /home
| --result-path,--rp | defines a result path with its name and a sequence of PrintServerNames |
arg ::= <JavaWildcardExpression> [ : <JavaWildcardExpression> ]+
With this option, a print server path into a results log file may be defined. The path elements are separated with :. Wildcards in Java syntax are supported. Each result source has a name which may be chosen arbitrary and which is used to reference this query in other queries or in other options.
A path element may reference another result source by using the other results source name enclosed in %. Then this path element is replaced with the print server path defined in the referenced result path. The wildcard expansion takes place after the result path expansion.
A path element may contain a match group according to the regular expression syntax. A match group is enclosed in "(" and ")". When using a match group the extracted value from the match group is used instead of the value of the selected result path.
this option is always saved and saved in any kind of config file |
#
--result-path q1 "TandemModel:Meter1:TransferTime:Mean"
select a single value from results files
#
--result-path q1 "TandemModel:Meter2:TransferTimeDist:pdf:bucket:.*:prob"
select array values from results file
#
--result-path q1 "TandemModel:Meter2:TransferTimeDist:pdf:bucket:1:prob"
select one array value from results file
#
--result-path q1 "TandemModel" --result-path q2 "%q1%:Meter2" --result-path q3 "%q2%:TransferTimeDist:pdf:bucket:1:prob"
p3 now means the same result path as in the previous example
#
--result-path ".*:Throughput:ThroughputTrace_of_MS_([0-9]+):traces:.*:trace:.*:value"
Select the number of a mobile though a match group instead of the value
#
--result-path ".*:Throughput:ThroughputTrace_of_MS_.*:traces:.*:trace:([0-9]+):value"
Select the trace number through a match group instead of the value
| • | Always include regular expressions in quotes to prevent the system shell from interpreting special chars like * or ? |
| --column-definition,--cd | defines a column in a chart |
arg ::= <ColNum> ( (simulation-parameter|sp) <SimParaName>) | ( (result-path|rp) <ResultPath> ) | batch-number | drop-number
ColNum column number starting with 0, must be consecutive
SimParaName Name of a simulation parameter in the results tree
ResultPath A result path (see --result-path)
simulation-parameter may be abbreviated with sp
result-path may be abbreviated with rp
batch-number may be abbreviated with bn
drop-number may be abbreviated with dn
This option is used with the command eval and defines a column in a chart. It defines the number of the column, the type of the column and depending on the type additional parameters.
There are three column types defined:
| • | the type simulation-parameter (abbreviated with sp) denotes a simulation parameter which is listed in this column. The parameter is the name of the simulation parameter, |
| • | the type result-path (abbreviated with rp) denotes a result path for the column. The parameter is the result path (which may reference more result pathes) |
When using a match group in a result path (see help for the result-path option) then instead of the value associated with the result path the extracted value from the match group is listed in the column.
| • | the type batch-number (abbreviated with bn) will list the batch number in the column (only valid when the --batches Option is given). This type has no parameters. Only default batches will be handled. |
| • | the type drop-number (abbreviated with dn) will list the drop number in the column (only valid when the --drops Option is given). This type has no parameters. |
this option is always saved but only in a named config file (not the global config file) |
#
--column-definition 0 sp MsgLen
Define column 0 of type simulation-parameter which contains the simulation parameter (s) MsgLen
#
--column-definition 1 rp %r1%
define column 1 of type result-path which references the result path (r) with name r1 (see --result-path)
#
--column-definition 1 rp "TandemModel:Meter2:TransferTimeDist:pdf:.*"
define column 1 of type result-path giving the print server hierarchy to a distribution
#
--column-definition 1 batch-number
define column 1 of contain the number of the batch for this result
#
--column-definition 1 drop-number
define column 1 of contain the number of the drop for this result
| --graph-writer,--gw | Specifies the writer for the graph to use |
arg ::= flat | ( family <Col> ) | external <ClassName> <OptionalParameters>
<flat> selects the flat graph writer
<family> selects the family graph writer where Col is the number of the col to sort for
<external> select a user supplied external graph writer which may have optional parameters
With this option the writer to use to create graph data from the evaluation results may be specified. All writers use the column definitions defined by the option(s) --column-definition.
Currently the following graph writers are implemented:
| • | The flat graph writer prints the results in a two-dimensional table to stdout. The first line consists of the headlines, the remaining lines contain the graph data. This writer has no additional arguments. |
| • | The family graph writer prints a family of graphs as two-dimensional tables to stdout. Graphs are collected according to the value of a given column. This writer requires exactly one numeric parameters which defines the column to use as collection criteria (family column). |
If these writers are not sufficient a user written external graph writer may be called which can access the SimTree internal data structure describing the results of an evaluation. The interface which an external graph writer must implement, some internal SimTree classes and helper methods are provided in an example package for writing an external graph writer.
When this option is not given, the flat graph writer is used.
this option is always saved and saved in any kind of config file |
#
--graph-writer flat
Use the flat graph writer (this is the default and may be omitted)
#
--graph-writer family 2
Use the family graph writer, the family value is retrieved from column 2
#
--graph-writer external ikr.externalgraphwriter.ExternalGraphWriterExample
Use the external graph writer with the given class name. See the example package how to use this
| • | The class for the external graph writer should be placed in a jar-file which is contained in the CLASSPATH for SimTree. The full name of the class (including package name-parts) must be used. The class is loaded with the call Class.forName(graphWriterClassName).newInstance(). For more information see the provided example package. |
| --max-depth,--md | Specifies the number of levels in the print server hierarchiy which are dumped |
arg ::= <MaxDepth>
where MaxDepth is an Integer greater than zero
This option specifies the number of hierarchiy levels in a print server path (depth) for which the names and (if at the leaf) results are dumped.
When this option is not given, only leafs are dumped, else all nodes are dumped up to and including the given level.
this option is always saved and saved in any kind of config file |
#
SimTree dump --max-depth 2
Print the highest two levels of the FinalResults File
| --ignore-default-config,--idc | when set, the default configuration is not loaded |
(no arguments)
When this option is set, the loading of the default configuration saved in <StudyRoot>/MetaData/simtree.conf is suppressed.
this option is never saved |
#
--ignore-default-config
| --save-config,--sc | save/replace the default or a named configuration |
arg ::= [<ConfigName>]
where <ConfigName> is the name of the configuration to save/replace
With this option, a configuration (set of options) given on the command line may be saved in a named configuration or in the default configuration when <ConfigName> is omitted. When the configuration already exists the option --replace-config must be used else the option --save-config is sufficient.
The default configuration is saved in <StudyRoot>/MetaData/simtree.conf. A named configuration is saved in <StudyRoot>/MetaData/simtree-<ConfigName>.conf.
Each option has an associated save mode which defines how an option will be saved in an configuration file when using the --save-config option: Options may never be saved (i.e. the --save-config option itself), may only be saved when given on the command line but not when read from a configuration file or when loaded from a configuration file or given on the command line.
this option is never saved |
#
SimTree add --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0 --save-config par1
saves the two options --simulation-parameter in the not-existing configuration named par1
#
SimTree add --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0 --replace-config par1
saves the two options --simulation-parameter in the (existing) configuration named par1
| --replace-config,--rc | save/replace the default or a named configuration |
arg ::= [<ConfigName>]
where <ConfigName> is the name of the configuration to save/replace
With this option, a configuration (set of options) given on the command line may be saved in a named configuration or in the default configuration when <ConfigName> is omitted. When the configuration already exists the option --replace-config must be used else the option --save-config is sufficient.
The default configuration is saved in <StudyRoot>/MetaData/simtree.conf. A named configuration is saved in <StudyRoot>/MetaData/simtree-<ConfigName>.conf.
Each option has an associated save mode which defines how an option will be saved in an configuration file when using the --save-config option: Options may never be saved (i.e. the --save-config option itself), may only be saved when given on the command line but not when read from a configuration file or when loaded from a configuration file or given on the command line.
this option is never saved |
#
SimTree add --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0 --save-config par1
saves the two options --simulation-parameter in the not-existing configuration named par1
#
SimTree add --simulation-parameter MsgLen 100 --simulation-parameter ServiceTime 1.0 --replace-config par1
saves the two options --simulation-parameter in the (existing) configuration named par1
| --load-config,--lc | load options from a saved configuration |
arg ::= <ConfigName>
where <ConfigName> is an existing configuration
Load a previously saved configuration (set of options) and uses the loaded options for the current command. This option may be used more than once on the command line. The configuration is loaded from the file <StudyRoot>/MetaData/simtree-<ConfigName>.conf.
this option is never saved |
#
--load-config eval1
Load config from <StudyRoot>/MetaData/simtree-eval1.conf
| --control-command,--cc | defines a control request which is sent to a running SimTree instance (WIP) |
arg ::= <Object>.<Method>[-<Parameter>]*
<Object> is the target object
<Method> is the method to execute
<Parameter> is an optional parameter to the method
WARNING: This feature is "work in progress" and neither fully implemented nor tested. Please use this feature only in close interaction with the developers.
Specifies a control request which is sent to a controlled SimTree instance. Each request consists of
| • | the control object. The control object is the target for the command inside the controlled SimTree instance. Each object specifies an internal resource in SimTree. |
| • | the control method. The control method tells the adressed object, what it should do. Each object understands a defined set of methods. |
| • | optional parameters to the control method. The parameters may appear in any order. |
The object and the method are separated wth a . . The parameters are appended to this string with -.
For a list of supported control objects, methods and their parameters see the full help text of SimTree.
this option is never saved |
#
--control-command slots.add --lps 2
request adding 2 local process slots to the controlled SimTree instance
#
--control-command slots.remove --rps cnode02 3 --lps 2
request removing 2 slots on cnode02 and two local process slots
#
--control-command ws.list
list all three queues of the current working set
#
--control-command ws.list-running
list the running queue of the current working set
#
--control-command ws.list-running-finished
list the running and the finished queue of the current working set
#
--control-command ws.add --sp MsgLen 2
add work items for MsgLen = 2 to the waiting qeueue of the current working set
#
--control-command ws.remove --sp MsgLen 2
remove all work items for MsgLen = 2 from waiting queue of the current working set
For experienced users SimTree allows some tweaks to its internal operation and simplifications of regular operations.
More information is available in the following sub chapters. Type 'SimTree advanced-<Topic>' to view this content:
Topics
configuration Saving and loading configurations
system System requirements
properties User definable behavior
hooks Replacing built-in functionality
attributes Using attributes for replacements in the parameter file
A set of options with its arguments may be saved under a configuration name (see the option --save-config). A configuration may have a name which may be given as parameter to the --save-config option. One or more configurations may be loaded with --load-config options which have one configuration name as argument. The configuration files are saved in the <MetaData> directory of the current simulation study. The format of these configuration files directly corresponds to the options syntax. The configuration files may be modified also by using an editor.
Each option has an associated save mode which defines how an option will be saved in an configuration file when using the --save-config option: Options may never be saved (i.e. the --save-config option itself), may only be saved when given on the command line but not when read from a configuration file or when loaded from a configuration file or given on the command line.
SimTree uses a default configuration which is always loaded. This default configuration may be saved with the --save-config option without an argument.
Expert users (and only those!) can examine and modify some internal properties of SimTree. These properties are created from built in defaults and saved in a file, when this file does not exist when SimTree is started. The values are not checked and are always assumed to be correct. Values read from the properties file take precedence over the built in defaults.
The properties file is located in the directory <StudyRoot>/MetaData and is a plain text file and may be edited with a text editor.
It is NOT guaranteed that properties (their names, their values or their meaning) are preserved between different releases (even patch releases) of SimTree. It is up to the user to adapt changed properties.
SimTree assumes and requires in its standard configuration the following system environment:
| • | In general, SimTree assumes a UNIX like system environment. Currently only Linux-Systems are supported. Using SimTree under Windows is not supported and support for this is not planned. |
| • | SimTree is written in Java and requires a Java Runtime Environment (JRE) Version 1.6 or later. SimTree does not depend on external Java libraries besides the standard JRE 1.6 libraries. |
| • | SimTree is provided as a Java jar-file. This jar file should be run by a script which calls the Java VM and transfers all commandline parameters to the executable. The script must be called SimTree because SimTree calls itself to execute simulation or collect processes. The script SimTree must be executable through the current PATH. |
| • | SimTree uses a lot of internal assertions to check its correct operation. Setting the option -ea for the java VM is recommended. Please report all failed assertions as bug reports. |
| • | SimTree uses a UNIX-shell script template to execute a simulation or collect process and assumes that this template is executable on the local and - if required - on the remote host(s). The builtin default template may be replaced by a custom template (see intro-hooks). |
| • | SimTree assumes that some commonly used programs are installed and executable (i.e. bzip2, rm). These programs are assumed to be in the current PATH. The programs may be replaced by setting according properties (see intro-properties). |
| • | When using the feature to start simulation or collect processes on remote hosts (option --remote-process-slots) the following requirements must be fulfilled: |
| • | The local host and the remote hosts(s) must share the StudyRoot in a common filesystem, i.e. by using NFS or CIFS. |
| • | Starting a process on a remote hosts must be possible by using a ssh/rsh-like command (property CMD_REMOTE_SHELL). The called command interpreter on the remote host must understand the UNIX-shell syntax. A profile is executed on the remote host (property REMOTE_PROFILE_FNAME) before starting the simulation or collect process. This profile may be used to set PATHs and other system requirements. |
Some adaption to a different system environment may be possible by changing the hooks which are used to start a simulation remotely. |
SimTree handles some of its internal operations through so-called hooks. A hook is a script template containing replaceable parameters. When SimTree executes a hook, it takes the template and instantiates the replaceable parameters with concrete values suitable for the currently required operation.
The interface of the built-in hooks is NOT guaranteed to be compatible between SimTree version or even SimTree patch revisions. It is up to the user to trace changes in the built-in hooks and adapt its own hooks.
For each operation which is executed through a hook, a default hook file template is builtin into SimTree. The user may replace such a hook file template with a customized implementation by creating a file in the directoy <StudyRoot>/<MetaData>/Hooks. A user provided hook file template must have the same name as the builtin template.
It is advisable to use the builtin templates as starting points and modify them as appropriate. The builtin templates may be retrieved by extracting them from the SimTree jar-File in the subdirectory ./res/hooks.
Hook script files which are only used during the execution time of the current SimTree process are created in the directory <StudyRoot>/Temp and deleted after the SimTree process, which has created them, has finished.
The following hooks are currently used:
| • | simtree-callsim: This script is used to start a simulation or collect run. In this the simulation binary is called and the created log files are examined and packed when requested. This script handles the execution on the lowest layer of the call hierarchy. |
| • | execute-simprog-local: This script is called when a simulation or collect run has to be started on the local host. It calls itself SimTree with specific parameters which itself lead to calling simtree-callsim. |
This script may be used to submit SimTree jobs to a batch queuing system. When this script returns immeadetely after submitting the job, the main SimTree process will return also after all jobs are submitted. |
| • | execute-simprog-remote: This script is called when a simulation or collect run has to be started on an remote host. Besides this it works like execute-simprog-local. |
| • | condition-notifier: This script is called when certain conditions during the operation of SimTree are reached. This script must not do nothing which affects the operation of SimTree. The default implementation allows sending mail to the user on certain conditions. On which conditions a mail is sent is customizable through properties (see documentation in properties file). |
Attributes are an optional mechanism to resolve replacements in the simulation parameter template file with actual values. The values used for the replacment depend on the current simulation parameter value set.
To use attributes, a single attributes file is placed in the MetaData directory of the StudyRoot. The name of the file is defined by a property.
The attributes file contains lists of attributes. Each list is associated with a simulation parameter and a value for this simulation parameter. The associated list is used for replacements when a simulation run is performed with the given value for this simulation parameter.
The simulation parameter and its value are defined in the form [SimParaName,SimParaValue]. After this the list of attributes follows as lines of the form AttName=AttValue. Each such line defines one attribute with a corresponding value.
So the format of the file is as follows
[SimParaName1,SimParaValue1]
AttName1=attValue1
AttName2=attValue2
[SimParaName1,SimParaValue2]
AttName1=attValue1
AttName2=attValue2
The file may contain empty lines and comment lines starting with #. Blanks may be inserted where appropriate.
The attributes are used when generating the simulation parameter file from the simulation parameter template. In the parameter file template there may be replacement patterns (%%<Replacement>%%) which contain attribute names besides the commonly used simulation parameter names.
During the generation of the simulation parameter file each attribute name is replaced with the attribute value for the current simulation parameter value.
When using the attributes file it is important that for each replacement pattern in the simulation parameter template file a attribute value is given. That means that for each value of a simulation parameter an attribute list must be defined.
The inner logic of SimTree tries to ensure methodical correctness while enabling flexibility for the user. For this SimTree executes build-in consistency checks and the simulation control follows defined rules for predefined method work flows.
More information is available in the following sub topics. Type SimTree spec-<Topic> to view this content:
wording Terms and Definitions
goals SimTree design goals
consistency How SimTree tries to ensure consistency
execute How SimTree executes simulations and evaluations
specials Corner cases and specialities
The following terms and definitions are used when describing SimTree's operation:
| • | Simulation parameter value set: A touple of values, exactly one for each simulation parameters defined in a simulation study (a leaf in the simulation parameter value tree). |
| • | Simulate run: The execution of a simulation program for one simulation parameter value set with the purpose of generating experimental (and eventually statistically aggregated) data (results). |
| • | Collect run: The execution of a simulation program for one simulation parameter value set where results from one or more simulate runs are combined into final results. |
| • | Batch means method (BM): A simulation method where a simulate run is divided in a phase where simulated system reaches an stable state (transient phase) and one or more so called batch phases (batches) where batch results are obtained. In most cases the batch results are statistical values. The batch results are combined into final results. |
The final results may be obtained in a collect run by combining the results of several simulate runs where each simulate run generates one or more statistical independent batch results. |
| • | independent replication method (IR): A simulation method where one simulate run is divided in a phase where the simulated system reaches a stable state (transient phase) and exactly one phase where so called drop results are obtained. The drop results may be combined in final results by a collect run. |
| • | Default batches: Batch phases in a simulation run using a default start value for the random number generator (the so called seed index). |
| • | Seeded batches: Batch phases in a simulation run using user- or tool-defined start values for the random number generator. |
| • | Drops: A phase were drop results are obtained. Each drop for one simulation parameter value set is executed with a different start value for the random number generator so the generated drop results are statistically independent. |
| • | Batch results (batch result files): Results from a batch phase stored in a file. |
| • | Export results (export result files): Internal state of the statistic sampling model components after one batch or drop phase after one batch or drop phase stored in a file. Exports results are not directly usable by the user, they are only used as input in collect runs. |
| • | Drop results (drop result files): Result from a drop stored in a file. |
| • | Final results (final result file): Combined results from several batches or several drops stored in a file. |
SimTree was designed with the following design goals:
| • | Ensure methodical correctness as far as possible. This is important for unexperienced users to prevent them from generating invalid results. It is important to note that SimTree can only prevent errors on the lowest level. Senseless modelling or senseless simulation parameter values or other methodical bugs are not detectable by SimTree. |
| • | Save computing power (and therefore energy) by only executing required simulation runs. |
| • | Implement the whole lifecycle of a simulation from creating the simulation parameters, their values, executing the simulation to obtain results and evaluating the results. Especially the evaluation phase only covers basic operations; experienced users will have to add more sophisticated evaluation tools on top of SimTree. |
The following describes the rules which are applied to ensure consistency of the simulations studies data:
A simulate run would result in inconsistencies and is therefore not executed when
| • | for default batches (BM): Seeded export and/or batch results exists [Reason: Seeded batches and default batches must not be mixed]. |
| • | for seeded batches (BM): Default batch results exists [Reason: Seeded batches and default batches must not be mixed]. |
The following actions are done to ensure consistency after a simulate run or a collect run:
| • | When a simulate run will add export results, the final results are deleted before the simulate run [Reason: Prevent inconsistencies between export results and the final results]. |
| • | Batch results are not considered in consistency checks. |
The following specifies the SimTree behavior in simulate and collect runs:
A simulate run is required and therefore executed when
| • | for default batches (BM): The final results do not exist. |
| • | for default batches (BM): The final results exist but batch results do not exist [Reason: Without batch results SimTree cannot determine whether the final results are created from a simulate run with the requested batch count] |
| • | for default batches (BM): Default batch results exists but have not the same batch count as requested [Reason: Prevent inconsistencies by differing number of default batches]. |
| • | for seeded batches (BM): Export results for the requested seed do not exist or they exist but have not the same batch count as would be created by the simulate run [Reason: Required result missing or invalid]. |
| • | for drops (IR): A drop export result with the same seed as requested does not exist [Reason: Required result missing]. |
A collect run is not required and therefore skipped when
| • | no export result files exists [Reason: Nothing to collect] |
| • | final results exists [Reason: Whenever new export results are created, the final results are deleted (see consistency). When export results are cleared, final results are always also cleared. So it is always ensured that the final results are consistent with the existing export results]. |
The user may define by properties
| • | whether batch results are generated for seeded batches. In most cases they are not required, so the default for this property is false. |
| • | whether batch results are generated for default batches. To prevent simulate runs which are not required, the default for this property is true. |
| • | whether drop results are generated. In most cases they are not required, so the default for this property is false. |
| • | whether export results are deleted after collecting them in final results. This saves disc space but may require additional simulate runs. The default for this property is false. |
There are some corner cases in handling the simulate and collect runs:
| • | (IR) Assume that for a simulation parameter value set a simulate run for a number i of drops is requested. Then the following may happen |
| • | There are exactly i drop results present. Then the simulate run ist skipped. |
| • | There are less that i drop results present. Then the simulate run will add the missing drops. |
| • | There are more than i drop results in the results tree. Then the simulate run is skipped. |
This behavior allows differing number of drop results for different simulation parameters values sets. |
| • | (BM) Assume that for a simulation parameter value set a simulate run for a number i of batches (default batches or seeded batches) is requested. Then the following may happen |
| • | There are exactly i batch results present. Then the simulate run ist skipped. |
| • | There are more or less than i batch results present. Then the simulate run will remove the existing results and start the simulate run. |
This behavior ensures consistency of the results. |
WARNING: This feature is "work in progress" and neither fully implemented nor tested. Please use this feature only in close interaction with the developers.
The control framework allows changing the behavior of a running SimTree process (the controlled instance) by sending control requests to this controlled instance from another SimTree instance (the controlling instance). The controlled and the controlling instance of SimTree must run on the same host.
The controlling instance is called with the SimTree command control. This command requires at least the option --control-command with exactly one argument. This argument defines the request which is sent to the controlled instance. Depending on the kind of the request additional options to the control command are allowed or required.
The request consists of at least two parts (the control object and the control method) and optional further parameters for the control method. The object and the method are separated with a ., optional parameters are appended to this string separated with -.
For examples of control commands see the SimTree command control and the option --control-command.
In this chapter the supported control objects, the methods which these objects support and the parameters defined for the methods are described. Additionally the options which are allowed for each object are listed. The options generally have the same functions as when they are used with other commands.
This control object allows access to the internal process slot table of SimTree.
This table contains one entry for each slot for executing of simulate or collect runs. Slots are initially defined with the options --local-process-slots and --remote-process-slots.
| list | List items currently in a table |
| add | Add an item to a table |
| remove | Remove an item from a table |
| --local-process-slots,--lps | defines the number of processes to start on the local host |
| --remote-process-slots,--rps | defines the number of process slots on a remote host |
This control object allows access to the internal working set tables of SimTree.
These tables contain the work items which SimTree has to handle. The list of work items is initially build from the current content of the results tree and from the options --simulation-parameter, --simulation-parameter-path and additional options like --force-all-values. The working set contains three tables: The wait-queue which contains work items which wait for a process slot to be handled; the run-queue which contains work items which are currently in work and the finished queue which contains all entries which are completed.
| list | List items currently in a table |
| add | Add an item to a table |
| remove | Remove an item from a table |
| running | Work on the running-queue |
| waiting | Work on the waiting-queue |
| finished | Work on the finished-queue |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |
This is not yet implemented!
This control object allows access to the list of currently running processes on the local machine or on remote machines.
| list | List items currently in a table |
| kill | Kill Process |
| --simulation-parameter,--sp | defines simulation parameter value sets for one simulation parameter |
| --simulation-parameter-path,--spp | defines a set of simulation parameter values, shortcut for --sp Options |
| --batches,--b | defines the batches to handle |
| --drops,--d | defines the drops to handle |