Skip to content

Commit

Permalink
Correct project specification error
Browse files Browse the repository at this point in the history 
1. Correct a few bugs in the command-line specification.
2. Add documentation discussing project specification
  • Loading branch information
@MengeCrowdSim
Sean Curtis authored and MengeCrowdSim committed May 28, 2018
1 parent 57b230c commit 020f635
Show file tree
Hide file tree
Showing 5 changed files with 109 additions and 12 deletions.
31 changes: 31 additions & 0 deletions doc/mengeDetails/commandLine.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,34 @@ Command Line Interface {#page_CommandLine}
=================

@section sec_CLI_overview Overview

The command-line interface supports all of the simulator parameters specified in the
[project specification](@ref page_ProjectSpec) as well as additional flags to access runtime
functionality:

- `-h/--help`: Displays information on the command line interface to the console.
- `-p/--project [filename]`: Specifies the project specification file from which simulator
parameters are initially drawn (but can still be overriden).
- `--verbose`: Increases the number and types of messages written to the log.
- `-l/--listModels`: Lists models that %Menge has access to upon execution, with a brief summary
for each model.
- `-L/--listModelsDetails`: Lists models that %Menge has access to upon execution, with a detailed
description of each model.

@section sec_CLI_mapping Project Specificaiton-Command Line Flag Mapping

This section defines which command line flags override which project specification attributes. See
the [project specification file](@ref page_ProjectSpec) for more details.

| Project specification | Command-line flag |
| :-------------------: | :---------------- |
| `behavior` | `-b/--behavior` |
| `dumpPath` | `-u/--dumpPath` |
| `duration` | `-d/--duration` |
| `model` | `-m/--model` |
| `random` | `-r/--random` |
| `scbVersion` | `--scbVersion` |
| `scene` | `-s/--scene` |
| `subSteps` | `--subSteps` |
| `timeStep` | `-t/--timeStep` |
| `view` | `--view` |
2 changes: 1 addition & 1 deletion doc/mengeDetails/mainpage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Menge can be used in two ways. Simply exploiting its current functionality to m

@subsubsection subsubsec_running Running a Simulation

Using Menge as a black box simulator is straight-forward. To simulate a new scenario we requires two input files: a scene specification and a behavior specification. The scene specification describes the environment and population, including the global and per-agent simulation parameters (see @ref page_SceneSpec); essentially, it defines the simulation initial conditions. The behavior specification defines how each agent defines its overall behaviors -- its goals, strategies, and responses to changes in the environment (see @ref page_BehaveSpec). These two files are provided as input to the program, specifying the pedestrian model to use. The results of the simulation can can be displayed interactively (see @ref page_ViewSpec) and/or the per-agent trajectories can be written to a cached file for later analysis or visualization (see @ref page_outSpec).
Using %Menge as a black box simulator is straight-forward. To simulate a new scenario we requires two input files: a scene specification and a behavior specification. The scene specification describes the environment and population, including the global and per-agent simulation parameters (see @ref page_SceneSpec); essentially, it defines the simulation initial conditions. The behavior specification defines how each agent defines its overall behaviors -- its goals, strategies, and responses to changes in the environment (see @ref page_BehaveSpec). These two files are provided as input to the program, specifying the pedestrian model to use. These files, as well as other relevant simulation parameters can be specified in a [project specification file](@ref page_ProjectSpec) and overrideen on the [command line](@ref page_CommandLine). The results of the simulation can can be displayed interactively (see @ref page_ViewSpec) and/or the per-agent trajectories can be written to a cached file for later analysis or visualization (see @ref page_outSpec).

@subsubsection subsubsec_Extending Extending the Simulator

Expand Down
66 changes: 66 additions & 0 deletions doc/mengeDetails/projSpec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,69 @@ Project Specification {#page_ProjectSpec}
=================

@section sec_Proj_overview Overview

The project specification file brings the high-level simulator parameters into one place. These are
the types of values that could/would be provided on the command-line. The project specification
aggregates them into a file to reduce typing.

The file takes the form (with the attributes alphabetized for convenience):

```xml
<?xml version="1.0"?>

<Project
behavior="[Relative Path]"
dumpPath="images/test"
duration="postive number"
model="valid model name"
output="[Relative Path]"
random="non-negative number"
scbVersion="valid scb version"
scene="[Relative Path]"
subSteps="non-negative number"
timeStep="positive number"
view="[Relative Path]"
/>
```

@section sec_Proj_details Description of Project Attributes

The XML `<Project>` tag attributes have the following interpretation:
- `behavior`: the path (relative to the location of the project specification file) to a
[behavior file](@ref page_BehaveSpec).
- `dumpPath`: the path (relative to the location of the project specificaiton file) to a folder in
which screen grabs should be written (aka "dumped"). It defaults to the current directory. If the
path does not currently exist, %Menge will attempt to create it.
- `duration`: A postive real number specifying the upper bound on how much time will be simulated.
NOTE: if the simulation "finishes" (i.e., all agents are simultaneously in states marked "final"),
the simulation will stop at an earlier time.
- `model`: A string indicating the pedestrian model to use. To see the models available to %Menge
execute the command: `menge.exe -l` (on Windows) or `./menge -l` (on Linux/OSX).
- `output`: The name of the scb file (relative to the location of the project specification file)
to write agent trajectory data to. If no path is given, no trajectory file will be written.
- `random`: A non-negative number to serve as the seed to the random number generator. If 0, %Menge
will seed the generators with a random value. If positive, it will seed the generators with that
value, insuring consistent initialization across multiple executions.
- `scbVersion`: A string indicating a supported trajectory (aka `scb`) file. To see the list of
supported strings, execute: `menge.exe -h`/`./menge -h` (on Windows and Linux/OSX,
respectively). Look for the values associated with the `--scbVersion` flag.
- `scene`: the path (relative to the location of the project specification file) to a
[scene specification file](@ref page_SceneSpec).
- `subSteps`: specification of the number of "minor" time steps to take between each major time
step (see `timeStep` below). The difference between major and minor time steps is that
trajectories and visualizations are only updated on *major* timesteps. So, for example, to create
trajectory files at a fixed frequency (e.g., 30 Hz) for models that require significantly different
simulation time steps, use a larger value for `subSteps` to change the effective simulation time
step from 30 Hz to 120 Hz (e.g., by passing in the value 3 -- 3 sub steps plus one major time
step).
- `timeStep`: a postivie real number indicating the size of the *major* time step.
- `view`: the path (relative to the location of the project specification file) to a
[view configuration](@ref page_ViewSpec).

A given project specification file can be indicated on the command line and any of the values given
in the project specification file can be overriden on the [command line](@ref page_CommandLine).

All of these values have default values -- if they are not given in a project file or otherwise on
the command line, the default value will be used. The default values won't necessarily lead to a
valid simulation (i.e., failure to specify scene, behavior, or model will fail to create a
simulation).
2 changes: 2 additions & 0 deletions releaseNotes.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ Release 0.9.2
Features
Moved `ProjectSpec` out of main menge application and into core library
- facilitates parsing projects in arbitrary contexts.
- Corrected relationship between command-line parameters and project specification.
- Added documentation to describe the project specification/command-line configuration.
Fixed visualization to use a right-handed frame (with z-up).
- this is significant because, previously, the agents were defined in an x-y plane that
was being inverted in the visualizer making visual interpretation difficult. Now the
Expand Down
20 changes: 9 additions & 11 deletions src/Menge/mengeMain/mengeMain.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ bool parseCommandParameters( int argc, char* argv[], ProjectSpec* spec, const Si
// Command line argument fields
bool verbose = false;
try {
TCLAP::CmdLine cmd( "Crowd simulation with behavior. ", ' ', "0.9" );
TCLAP::CmdLine cmd( "Crowd simulation with behavior. ", ' ', "0.9.2" );
// arguments: flag, name, description, required, default value type description
TCLAP::ValueArg< std::string > projArg( "p", "project", "The name of the project file", false,
"", "string", cmd );
Expand All @@ -127,15 +127,13 @@ bool parseCommandParameters( int argc, char* argv[], ProjectSpec* spec, const Si
TCLAP::ValueArg< std::string > behaveArg( "b", "behavior", "Scene behavior file", false, "",
"string", cmd );
TCLAP::ValueArg< std::string > viewCfgArg( "", "view", "A view config file to specify the "
"view - if this argument is specified, do not "
"specify the -i/-interactive argument.", false, "",
"string", cmd );
TCLAP::ValueArg< std::string > outputArg( "o", "output", "Name of output file (Only writes "
"output if file provided)", false, "",
"view.", false, "", "string", cmd );
TCLAP::ValueArg< std::string > outputArg( "o", "output", "Name of output scb file (Only writes"
" output if file provided)", false, "",
"string", cmd );
TCLAP::ValueArg< std::string > versionArg( "", "scbVersion", "Version of scb file to write "
"(1.0, 2.0, 2.1, 2.2, 2.3, or 2.4 -- 2.1 is the "
"default", false, "2.1", "string", cmd );
"default", false, "", "string", cmd );
TCLAP::ValueArg< float > durationArg( "d", "duration", "Maximum duration of simulation (if "
"final state is not achieved.) Defaults to 400 seconds.",
false, -1.f, "float", cmd );
Expand All @@ -147,11 +145,11 @@ bool parseCommandParameters( int argc, char* argv[], ProjectSpec* spec, const Si
"If not defined, or zero is given, the default seed will "
"be extracted from the system clock every time a default "
"seed is requested. Otherwise the constant value will "
"be provided.", false, 0, "int", cmd );
"be provided.", false, -1, "int", cmd );
TCLAP::ValueArg< int > subSampleArg( "", "subSteps", "Specify the number of sub steps to take."
" If the simulation time step is 10 Hz with 1 substep, it"
" actually runs at 20 Hz, but output is only updated at"
" 10 Hz.", false, 0, "int", cmd );
" 10 Hz.", false, -1, "int", cmd );

std::string modelDoc = "The pedestrian model to use. Should be one of: ";
modelDoc += simDB.paramList();
Expand Down Expand Up @@ -227,8 +225,8 @@ bool parseCommandParameters( int argc, char* argv[], ProjectSpec* spec, const Si
temp = viewCfgArg.getValue();
if ( temp != "" ) spec->setView( temp );

spec->setSubSteps( (size_t)subSampleArg.getValue() );

int sub_steps = subSampleArg.getValue();
if (sub_steps > -1) spec->setSubSteps(static_cast<size_t>(sub_steps));

temp = dumpPathArg.getValue();
if ( temp != "" ) {
Expand Down

0 comments on commit 020f635

Please sign in to comment.