Basics/Using the Command Line Applications
Most of the applications from the SUMO package are command line tools. Currently, only SUMO-GUI is not. If you do not know what a "command line" is, we refer you to the page about basic computer skills.
In the following, some peculiarities of the applications from the SUMO-suite are presented.
Contents |
Using SUMO Applications from the Command Line
SUMO applications are plain executables. You just start them by typing their name from the command line; for example NETGEN is called by
netgen.exe
under Windows and by
netgen
under Linux.
This simply starts the application (NETGEN in this case). As no parameter have been given, the application does not know what to do and prints only an information about itself:
SUMO netgen Version dev-SVN-r9983 Copyright (C) 2001-2011 DLR and contributors; http://sumo.sourceforge.net License GPLv3+: GNU GPL Version 3 or later <http://gnu.org/licenses/gpl.html> Use --help to get the list of options.
Options
Each application has a set of options which define which files shall be process or generated, or which define the application's behaviour. Normally, an application needs at least two parameter - an input file and an output file - but almost always more parameter are used for a fine-grained control. Each application's options are described within the application's description. In the following, it is described how options are set.
Setting Options on the Command Line
There are two kinds of options: boolean options which do not require an argument and are set to true if - and only if - the option is present and options with an argument. Setting an option with an argument on the command line consists of two parts - the option name and the option's value. For example, if one wants the simulation to load a certain road network, "mynet.net.xml", the following must be written:
--net mynet.net.xml
The '--' in front indicates that the option's long name is following ("net") in this case. After a whitespace the option's value must be given. It is also possible to use a '=' instead of the whitespace:
--net=mynet.net.xml
Some often used options have can be abbreviated, the abbreviation for the --net-option is -n. The following has the same effect as the two examples above:
-n mynet.net.xml
Please note that an abbreviation is indicated using a single '-'.
Not all abbreviations have the same meaning across the applications from the SUMO-suite.
Option Value Types
The SUMO applications know what kind of a value they expect to be set. For example, NETGEN allows you to set the default number of lanes, which of course must be an integer value. In the case, a string or something else is given, this is recognized and the application answers with an error message on startup. Please note that the decimal point in a float is encoded using a dot (".").
A special case of value types are lists, for example the list of additional files to load into a simulation. When giving more than a single file, the files must be divided using ','. This also counts for lists of other value types, as integers or floating point numbers.
Configuration Files
Because the list of options may get very long, configuration files were introduced. You can set up a configuration file which contains all the parameter you want to start the application with and have to start the application with only this configuration file given.
A configuration file is an XML-file that has a root element named configuration. The options are written as element names, with the wanted value being stored in attribute value (or v); the option --net-file test.net.xml given on the command line would become <net-file value="test.net.xml"/> within the configuration file. For the boolean options the value should be either "true", "on", "yes", "1", or "x" for the activation and "false", "off", "no", or "0" for deactivating the option (case does not matter here).
For the example above, the configuration file (let's save it under "test.sumocfg", see below) would look like:
<configuration>
<n v="test.net.xml"/>
<r v="test.rou.xml"/>
<a v="test.add.xml"/>
</configuration>
A more verbose but equivalent version would look like:
<configuration>
<input>
<net-file value="test.net.xml"/>
<route-files value="test.rou.xml"/>
<additional-files value="test.add.xml"/>
</input>
</configuration>
The section input given above has only documentation purposes and no functional meaning.
The according SUMO execution call - working with both configuration versions - would be:
sumo.exe -c test.sumocfg
This means that instead of the parameters, we only give the name of the configuration file using the option --configuration-file <FILE> or -c <FILE>. If you want to give no further options on the command line it is possible to leave out the "-c" as well:
sumo.exe test.sumocfg
Naming Conventions for Configuration Files
Dependencing on the targetted application, the configuration files' have different extensions. It is highly recommended to follow this convention. For using simulation configurations with SUMO-GUI this is even required - SUMO-GUI can only read simulation configurations named "*.sumocfg".
All conventions for configuration extensions can be found on the page on used file extensions.
Configuration Files vs. Command Line Parameter
In addition to a configuration file, further command line parameter can also be given on the command line. Note that this is not true for the simulation gui SUMO-GUI, which needs all parameters inside the configuration file. If a parameter is set within the named configuration file as well as given on the command line, the value given on the command line is used (overwrites the one within the configuration file).
Generating Configuration File Templates
The applications of the SUMO package allow you to generate configuration file templates. It is possible to save an empty configuration - a configuration template. This can be done using the --save-template <FILE>. In this case, the configuration will only contain the parameters, filled with their default values. If further information on the parameters is wanted, one can also pass the option --save-template.commented. Then, some further comments on each parameter are generated.
Saving the current Configuration into a File
Also, it is possible to save a configuration file which contains the currently set values. An application can be forced to do this using the option --save-configuration <FILE>.
Common Options
The applications from the SUMO suite share several options. They are given in the following.
Reporting Options
| Option | Description |
|---|---|
| --verbose -v | The application is more verbose in reporting what it is doing |
| --no-warnings -W | Warnings will not be written |
| --print-options -p | The options are printed giving the currently set values |
| --help -? | The application's help screen is printed |
| --version -V | The version number and license notice are printed |
| --log <FILE> -l | All outputs are written onto the console and into the given file |
| --message-log <FILE> | All informational outputs 8no errors and warnings) are written onto the console and into the given file |
| --error-log <FILE> | All errors and warnings are written onto the console and into the given file |
Random Number Options
These options configure how the seed of the random number generator is determined. The same seed leads to the same sequence of generated random numbers.
By default the seed is a hard-coded fixed value. So, as long as all configuration settings keep the same the outputs of several simulation runs will be exactly the same. To change this use one of the following options.
| Option | Description |
|---|---|
| --seed <INT> | Set a particular seed for the random number generator. By using different values you can have different but still reproducible simulation runs. |
| --random | Make SUMO choose a seed. If available the seed will be based on output of /dev/urandom otherwise the seed will be derived from current system time. This option has precedence over option --seed <INT>. |
Attention: The precedence of --random over --seed <INT> means that it is impossible to set --random in a configuration file and overwrite it by --seed <INT> in the command line. There might be a solution to this in the future.
Generating and Reading Files
Almost all files the tools from the SUMO package read or generate are written in XML. You should get familiar with XML before starting to work with SUMO. SUMO allows you to import files from different sources, but "native" SUMO files - road network descriptions, route and/or demand descriptions, infrastructure descriptions, etc. etc. - are SUMO-specific, not following any standard. XML files can be read and written using a simple text editor and we usually do this. Nonetheless, several other tools exist and may be reused.
For some of the file types used by SUMO, a xsd (XML Schema Definition) exists. Please consult the page on file extensions for a list of described file formats.
Hints on using XML
- The default viewer for XML files on Windows is the Internet Explorer. It may be used for validating your XML files. The syntax of an XML file should be valid if the Internet Explorer can completely load it.
- Eclipse allows to write XML documents following a given xsd (XML Schema Definition).
Writing files
Several options expect a file name (<FILE>) to write into as parameter. When being given at the command line, the given path is assumed to be relative to the current working directory. When being given in a configuration file, the file path is assumed to be relative to the configuration file's path. Absolute paths are of course also allowed.
Usually, existing files with the same name are overwritten without a warning. The path the output file shall be written into must exist.
Besides writing to a file, further special notations allow to:
- write into the null-device (no output at all): use "NUL" or "/dev/null" for file name
- write into a socket: use "<HOST>:<PORT>" for file name
- write to stdout (print on command line): use "stdout" or "-" for file name