Documentation for SimTree (Version 2.7.0beta16)
===============================================

1. Introduction

  1.1. Command line
  1.2. Running SimTree
  1.3. Handling of simulation parameters (add, remove, list)
  1.4. Simulation methods
  1.5. Generating results (simulate, collect)
  1.6. Evaluation of results (query, eval, dump)
  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


1. Introduction
===============

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


1.1. Command line
-----------------

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.


1.2. Running SimTree
--------------------

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.


1.3. Handling of simulation parameters (add, remove, list)
----------------------------------------------------------

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.


1.4. Simulation methods
-----------------------

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.


1.5. Generating results (simulate, collect)
-------------------------------------------

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.


1.6. Evaluation of results (query, eval, dump)
----------------------------------------------

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.*".


1.7. Usage examples
-------------------

Get help

# 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)

Prepare the StudyRoot to be used by SimTree

# SimTree prepare
     (Prepare the study-root, max be called any time even in already prepared study-root)

Saving and loading SimTree configurations

# 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)

List the current content of the results tree

# 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)

Add/Remove simulation parameters to the results tree

# 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)

Run the simulation program to generate simulation results

# 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)

Collect simulation results in final results

# SimTree collect
     (Collect results for all simulation parameter values)

Remove simulation results from the results tree

# 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)

Dump result files

# 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)

Query results in the results tree

# 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)

Evaluate results in the results tree

# 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)


1.8. First steps
----------------

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)

* look at the results (SimTree query, SimTree eval, ...)


1.9. Reporting bugs and submitting feature requests
---------------------------------------------------

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.


1.10. Help sources
------------------

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.


1.11. Hints and tips
--------------------

* 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.


2. SimTree Commands
===================

2.1. Command Overview
---------------------

Usage: SimTree <command> <options>

The following commands are defined
  Help and information commands
    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
    
  Handling of simulation parameter values in the results tree
    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
    
  Run simulations and collect results
    simulate  Start simulations for the current results tree
    collect   Collect export batch result files in a final results file
    
  Query and evaluate results
    query     Query the results tree
    eval      Evaluate the contents of simulation log files
    dump      Dump the content of result files in printserver format
    
  Management and Control
    control   Change the internal behavior of a running SimTree instance (WIP)
    
  Graphical User Interface
    gui       Start the SimTree GUI (WIP)
    
  Misc commands
    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


2.2. Help and information commands
----------------------------------

2.2.1. Command intro
--------------------

Usage: SimTree intro <options>

Command description
  Gives an introduction how to use SimTree
  
Accepted 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 intro-<Variant>)
  commandline               
  startup                   
  parameters                
  methods                   
  run                       
  eval                      
  examples                  
  first-steps               
  bugs                      
  doc                       
  hints                     
  
  
2.2.2. Command spec
-------------------

Usage: SimTree spec <options>

Command description
  Gives a more formal description of SimTree's behaviour
  
Accepted 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 spec-<Variant>)
  wording                   
  goals                     
  consistency               
  execute                   
  specials                  
  
  
2.2.3. Command advanced
-----------------------

Usage: SimTree advanced <options>

Command description
  Advanced topics for experienced users
  
Accepted 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 advanced-<Variant>)
  configuration             
  properties                
  system                    
  hooks                     
  attributes                
  
  
2.2.4. Command help
-------------------

Usage: SimTree help <options>

Command description
  Gives help on the usage of command and options of SimTree.
  
Accepted 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


2.2.5. Command news
-------------------

Usage: SimTree news <options>

Accepted 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


2.3. Handling of simulation parameter values in the results tree
----------------------------------------------------------------

2.3.1. Command prepare
----------------------

Usage: SimTree prepare <options>

Command description
  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.
  
Accepted 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

Examples
  # 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)
  
  
2.3.2. Command list
-------------------

Usage: SimTree list <options>

Command description
  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.
  
Required options
  --print-format,--pf       defines the print format for the list command
  
Accepted options
  --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
  
Examples
  # 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)
  
  
2.3.3. Command add
------------------

Usage: SimTree add <options>

Command description
  Add simulation parameters at the leaf of the results tree or add additional values for
  existing simulation parameters in the results tree.
  
Accepted options
  --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

Examples
  # 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)
  
  
2.3.4. Command remove
---------------------

Usage: SimTree remove <options>

Command description
  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.
  
Accepted options
  --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

Examples
  # 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)
  
Hints
  * 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.
  
  
2.3.5. Command clean
--------------------

Usage: SimTree clean <options>

Command description
  Remove files for given simulations parameter value sets from the results tree.
  
Accepted options
  --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

Examples
  # 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))
  
Hints
  * 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).
  
  
2.3.6. Command unlock
---------------------

Usage: SimTree unlock <options>

Command description
  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.
  
Accepted options
  --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

Examples
  # 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)
  
Hints
  * 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).
  
  
2.4. Run simulations and collect results
----------------------------------------

2.4.1. Command simulate
-----------------------

Usage: SimTree simulate <options>

Command description
  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.
  
Required options
  --simulation-binary,--sb  defines name and path of the simulation binary or script
  One of the following 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
  One of the following options
    --drops,--d               defines the drops to handle
    --batches,--b             defines the batches to handle
    
Accepted options
  --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

Examples
  # 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))
  
  
2.4.2. Command collect
----------------------

Usage: SimTree collect <options>

Command description
  Collect the results from previous executed seeded batch simulation runs (export result
  files) in final result files.
  
Required options
  --simulation-binary,--sb  defines name and path of the simulation binary or script
  One of the following 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
    
Accepted options
  --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

Examples
  # 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)
  
  
2.5. Query and evaluate results
-------------------------------

2.5.1. Command query
--------------------

Usage: SimTree query <options>

Command description
  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.
  
Required options
  --result-path,--rp        defines a result path with its name and a sequence of PrintServerNames
  
Accepted options
  --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

Examples
  # 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)
  
Hints
  * Always include regular expressions in quotes to prevent the system shell from
    interpreting special chars like * or ?
  
  
2.5.2. Command eval
-------------------

Usage: SimTree eval <options>

Command description
  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.
  
Required options
  --column-definition,--cd  defines a column in a chart
  
Accepted options
  --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                    
  
Examples
  # 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)
  
  
2.5.3. Command dump
-------------------

Usage: SimTree dump <options>

Command description
  Print the content of final result files or batch result files in the legacy print server
  format.
  
Accepted options
  --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
  
Examples
  # 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)
  
  
2.6. Management and Control
---------------------------

2.6.1. Command control
----------------------

Usage: SimTree control <options>

Command description
  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.
  
Required options
  --control-command,--cc    defines a control request which is sent to a running SimTree instance (WIP)
  
Accepted 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
  --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

Examples
  # 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)
  
  
2.7. Graphical User Interface
-----------------------------

2.7.1. Command gui
------------------

Usage: SimTree gui <options>

Command description
  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.
  
Accepted 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

Examples
  # SimTree gui
       (start the SimTree GUI)
  
  
2.8. Misc commands
------------------

2.8.1. Command null
-------------------

Usage: SimTree null <options>

Command description
  This command does nothing. It may be used to save options or to get a list of all
  implemented options.
  
Accepted 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

Examples
  # 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)
  
  
3. SimTree Options
==================

3.1. Options Overview
---------------------

The following options are defined

  Help and information options
    --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
    
  Handling Simulation Parameter Value Sets
    --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
    
  Simulate and Collect
    --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)
    
  View and Evaluate Results
    --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
    
  Configuration handling
    --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
    
  Management and control
    --control-command         defines a control request which is sent to a running SimTree instance (WIP)
    
    
3.2. Help and information options
---------------------------------

3.2.1. Option --help
--------------------

Summary
  --help,--h                when set, help for the given command is requested
  
Description
  with this option, help for the current command may be requested.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # SimTree add --help
       (request help for the add command)
  
  
  
3.2.2. Option --print-format
----------------------------

Summary
  --print-format,--pf       defines the print format for the list command
  
Syntax
  arg ::= <FormatString>
  The parameter defines the print format
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
  
  
3.2.3. Option --very-verbose
----------------------------

Summary
  --very-verbose,--vv       when set, make much more output during command execution
  
Syntax
  (no arguments)
  
When using the --save-config or --replace-config option
  this option is never saved



3.2.4. Option --verbose
-----------------------

Summary
  --verbose,--v             when set, make more output during command execution
  
Syntax
  (no arguments)
  
When using the --save-config or --replace-config option
  this option is never saved



3.3. Handling Simulation Parameter Value Sets
---------------------------------------------

3.3.1. Option --study-root
--------------------------

Summary
  --study-root,--sr         defines the root directory of the simulation studies data (the StudyRoot)
  
Syntax
  arg ::= <ExistingDirectory> ;
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # --study-root /u/user/home
       (Set the study root to the given directory)
  
  
  
3.3.2. Option --simulation-parameter-path
-----------------------------------------

Summary
  --simulation-parameter-path,--spp
                            defines a set of simulation parameter values, shortcut for --sp Options
  
Syntax
  arg ::= (<val>) [ ":" <val> ]+
  path elements are simulation parameter values and are separated with :
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
  
  
3.3.3. Option --simulation-parameter
------------------------------------

Summary
  --simulation-parameter,--sp
                            defines simulation parameter value sets for one simulation parameter
  
Syntax
  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>
  
Description
  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
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
Hints
  * Always include regular expressions in quotes to prevent the system shell from
    interpreting special chars like * or ?
  
  
  
3.3.4. Option --force-all-values
--------------------------------

Summary
  --force-all-values,--fav  when set, all values of not given parameters are used for removing operations
  
Syntax
  (no arguments)
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved



3.3.5. Option --force-delete-foreign-files
------------------------------------------

Summary
  --force-delete-foreign-files,--fdff
                            when set, the clean command also deletes files not managed by SimTree
  
Syntax
  (no arguments)
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved



3.4. Simulate and Collect
-------------------------

3.4.1. Option --remote-process-slots
------------------------------------

Summary
  --remote-process-slots,--rps
                            defines the number of process slots on a remote host
  
Syntax
  arg ::= <NodeName> <IntVal>
  <NodeName> name of the remote host (reachable by rsh/ssh)
  <IntVal>   number of processes to start on this host
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved but only in a named config file (not the global config file)

Examples
  # --remote-process-slots cnode08 4
       (starts 4 instances of the simulation program on host cnode08)
  
Hints
  * 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.
  
  
  
3.4.2. Option --local-process-slots
-----------------------------------

Summary
  --local-process-slots,--lps
                            defines the number of processes to start on the local host
  
Syntax
  arg ::= <SlotsOnLocalHost>
  number of process slots in the local machine (> 0)
  
Description
  With this option, the number of process slots to use for a simulation or collect run on
  the local machine may be defined.
  
When using the --save-config or --replace-config option
  this option is always saved but only in a named config file (not the global config file)

Examples
  # --local-process-slots 4
       (starts 4 instances of the simulation program on the local machine)
  
  
  
3.4.3. Option --batches
-----------------------

Summary
  --batches,--b             defines the batches to handle
  
Syntax
  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
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved but only in a named config file (not the global config file)

Examples
  # --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)
  
  
  
3.4.4. Option --drops
---------------------

Summary
  --drops,--d               defines the drops to handle
  
Syntax
  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
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved but only in a named config file (not the global config file)

Examples
  # --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)
  
  
  
3.4.5. Option --simulation-binary
---------------------------------

Summary
  --simulation-binary,--sb  defines name and path of the simulation binary or script
  
Syntax
  arg ::= <ExecutableFile>
  defines the relative or absolute name of the simulation binary
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --simulation-binary TandemFeedback
       (use TandemFeedback as the simulation binary)
  
  
  
3.4.6. Option --parameter-file-template
---------------------------------------

Summary
  --parameter-file-template,--pft
                            defines name and path of the parameter file template file
  
Syntax
  arg ::= <ParaFileTemplateName>
  name of the parameter file template (absolute or relative)
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
  
  
3.4.7. Option --filter-file
---------------------------

Summary
  --filter-file,--ff        defines path and name of the filter file
  
Syntax
  arg ::= <FilterFileName>
  name and path of the filter file (absolute or relative)
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
  
  
3.5. View and Evaluate Results
------------------------------

3.5.1. Option --result-path
---------------------------

Summary
  --result-path,--rp        defines a result path with its name and a sequence of PrintServerNames
  
Syntax
  arg ::= <JavaWildcardExpression> [ : <JavaWildcardExpression> ]+
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
Hints
  * Always include regular expressions in quotes to prevent the system shell from
    interpreting special chars like * or ?
  
  
  
3.5.2. Option --column-definition
---------------------------------

Summary
  --column-definition,--cd  defines a column in a chart
  
Syntax
  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
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved but only in a named config file (not the global config file)

Examples
  # --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)
  
  
  
3.5.3. Option --graph-writer
----------------------------

Summary
  --graph-writer,--gw       Specifies the writer for the graph to use
  
Syntax
  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
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # --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)
  
Hints
  * 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.
  
  
  
3.5.4. Option --max-depth
-------------------------

Summary
  --max-depth,--md          Specifies the number of levels in the print server hierarchiy which are dumped
  
Syntax
  arg ::= <MaxDepth>
  where MaxDepth is an Integer greater than zero
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is always saved and saved in any kind of config file

Examples
  # SimTree dump --max-depth 2
       (Print the highest two levels of the FinalResults File)
  
  
  
3.6. Configuration handling
---------------------------

3.6.1. Option --ignore-default-config
-------------------------------------

Summary
  --ignore-default-config,--idc
                            when set, the default configuration is not loaded
  
Syntax
  (no arguments)
  
Description
  When this option is set, the loading of the default configuration saved in
  <StudyRoot>/MetaData/simtree.conf is suppressed.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # --ignore-default-config
  
  
3.6.2. Option --save-config
---------------------------

Summary
  --save-config,--sc        save/replace the default or a named configuration
  
Syntax
  arg ::= [<ConfigName>]
  where <ConfigName> is the name of the configuration to save/replace
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # 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)
  
  
  
3.6.3. Option --replace-config
------------------------------

Summary
  --replace-config,--rc     save/replace the default or a named configuration
  
Syntax
  arg ::= [<ConfigName>]
  where <ConfigName> is the name of the configuration to save/replace
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # 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)
  
  
  
3.6.4. Option --load-config
---------------------------

Summary
  --load-config,--lc        load options from a saved configuration
  
Syntax
  arg ::= <ConfigName>
  where <ConfigName> is an existing configuration
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # --load-config eval1
       (Load config from <StudyRoot>/MetaData/simtree-eval1.conf)
  
  
  
3.7. Management and control
---------------------------

3.7.1. Option --control-command
-------------------------------

Summary
  --control-command,--cc    defines a control request which is sent to a running SimTree instance (WIP)
  
Syntax
  arg ::= <Object>.<Method>[-<Parameter>]*
  <Object>    is the target object
  <Method>    is the method to execute
  <Parameter> is an optional parameter to the method
  
Description
  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.
  
When using the --save-config or --replace-config option
  this option is never saved

Examples
  # --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)
  
  
  
4. Advanced topics
==================

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


4.1. Saving and loading configurations
--------------------------------------

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.


4.2. Properties
---------------

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.


4.3. Execution requirements
---------------------------

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.


4.4. Hooks
----------

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).


4.5. Attributes
---------------

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.


5. SimTree behavior specification
=================================

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


5.1. Definitions and conventions
--------------------------------

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.


5.2. Design goals
-----------------

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.


5.3. Consistency rules and checks
---------------------------------

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.


5.4. Simulation execution
-------------------------

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.


5.5. Corner cases and how they are handled
------------------------------------------

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.


6. Control
==========

6.1. Control overview
---------------------

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.

6.2. Control reference
----------------------

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.

6.2.1. Control object slots
---------------------------

Description
  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.
  
Supported methods
list                      List items currently in a table
add                       Add an item to a table
remove                    Remove an item from a table

Supported 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
  
  
6.2.2. Control object ws
------------------------

Description
  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.
  
Supported methods
list                      List items currently in a table
add                       Add an item to a table
remove                    Remove an item from a table

Supported parameters
running                   Work on the running-queue
waiting                   Work on the waiting-queue
finished                  Work on the finished-queue

Supported options
  --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
  
  
6.2.3. Control object procs
---------------------------

Description
  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.
  
Supported methods
list                      List items currently in a table
kill                      Kill Process

Supported options
  --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
  
  
