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.
The following presents some peculiarities of the SUMO-suite applications.
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 NETGENERATE is called by
netgenerate.exe
under Windows and by
netgenerate
under Linux.
This simply starts the application (NETGENERATE in this case). As no parameter has been given, the application does not know what to do and prints only an information about itself:
SUMO netgenerate 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 processed 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 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, NETGENERATE 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. Moreover, you 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 the 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>
<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.
A less verbose but equivalent version would look like:
<configuration>
<n v="test.net.xml"/>
<r v="test.rou.xml"/>
<a v="test.add.xml"/>
</configuration>
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
Depending 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 Files, Templates and Schemata
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 by using the --save-template <FILE>. In this case, the configuration will only contain the parameters filled with their default values.
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>.
Last but not least one can generate an XML schema (using the option --save-schema <FILE>) to validate configuration files against. For the SUMO application this schema should be equivalent to the one found at http://sumo.sourceforge.net/xsd/sumoConfiguration.xsd (respectively for the other executables). Please note that the schema is more strict than the SUMO options parser since it only validates the verbose version given above.
In either case, if further information on the parameters is wanted, one can also pass the option --save-commented. Then, some further comments on each parameter are generated.
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 on the console in reporting what it is doing |
| --no-warnings -W | Warnings will not be written to the console |
| --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 into the given file |
| --message-log <FILE> | All informational outputs (no errors and warnings) are written into the given file |
| --error-log <FILE> | All errors and warnings are written into the given file |
The logging options --log and --message-log also enable the verbose output but only into the given file (unless --verbose was given as well). Errors get always printed to the console (in addition to a possible log-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 in future.
Generating and Reading Files
Almost every file 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. - 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 directory must exist, where the output file shall be written.
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 (both notations work platform independent)
- write into a socket: use "<HOST>:<PORT>" for file name
- write to stdout (print on command line): use "stdout" or "-" for file name
- write to stderr: use "stderr" for file name