csv_event_output

csv_event_output … end_csv_event_output
csv_event_output
   file [ <file-name> | STDOUT | NULL]
   flush_output <boolean>
   insert_data_tags <boolean>
   disable [ <event> | all ]
   enable [ <event> | all ]
end_csv_event_output

Overview

The csv_event_output block allows the user to create a time-stamped file of simulation events. The general output of a given event varies based on the number of parties involved. This is detailed in General Format.

Since csv_event_output is comma-separated values, it is useful for importing into tables or spreadsheets, as well as use in post-processing tools for data analysis.

General Format

One-party event:

 
<time>,<event>,<party-1>,<extra-data>

Two-party event:

 
<time>,<event>,<party-1>,<party-2>,<extra-data>

Three-party event:

 
<time>,<event>,<party-1>,<party-2>,<party-3>,<extra-data>

Examples:

General Breakdown

An event within the file is composed of a logical line which may be one or more physical lines. If a physical line ends in a backslash (\), then the logical line continues on the next line. A logical line ends when a physical line is read that does not end in a backslash (\).

Field

Description

<time>

The current simulation time

<event>

The event name

<party-1>

The subject platform name (where the event originates)

<party-2>

The object platform name

<party-3>

The non-subject, non-object platform name relating to the event

<extra-data>

Any other pertinent data

Note

This Field’s format varies by event. Contact development if additional event data is needed.

Event Index

Commands

file [ <file-name> | STDOUT | NULL]

Specifies the name of the file to which the csv_event_output is written. If the file already exists, then it will be overwritten. The special name STDOUT indicates the csv_event_output is to be written to standard output. The special name NULL indicates that no csv_event_output is to be written. NULL can be used to cancel a file name specified in an earlier csv_event_output block.

Warning

The simulation will fail and csv_event_output will not output anything if the directory path provided here does not exist.

Note

To insert the run number in the file name use “%d”.

For example:

file events.csv
file events%d.csv   //with the run number
flush_output <boolean>

Specifies if the output buffer should be flushed after each event is written.

Note

Setting this value to ‘true’ can result in performance problems because the output is written to the output file after every event. This should only be used when attempting to diagnose problems where the program terminates abnormally and the buffer would not otherwise be flushed. This ensures that the last event that occurred is successfully recorded.

Default false

disable [ <event> | all ]
enable [ <event> | all ]

Specifies the names of the events to be included or excluded in the event log. These commands are typically specified multiple times to select the events of interest. The commands are processed in order of appearance with each successive command selecting or deselecting events as appropriate.

Note

By default, all events start out as being disabled.

Warning

Be careful about using enable all. It can generate a lot of output and the addition of new events in the future could result in enormous amounts of output.

insert_data_tags <boolean>

Specifies if the CSV header is written. This describes the format of each event in the log.

Note

This is used by the post-processing tools to parse the event log.

Default true

Sample csv_event_output

The following csv_event_output block:

csv_event_output
   file events.csv
   disable all    # This is not necessary, unless the user explicitly wants to reset the event list.
   enable PLATFORM_ADDED
   enable PLATFORM_DELETED
   enable SIMULATION_STARTING
   enable SIMULATION_COMPLETE
end_csv_event_output

Produces the following csv_event_output in simple_scenario demo:

0,PLATFORM_ADDED,SimpleStriker,blue,BLUE_STRIKER,,0,0,0,2.23167444e+06,5.97496947e+06,-7.95753188e+02,1.571,0.000,0.000,0.000,0.000,0.000,0.000,465.101,-0.937,0.350,0.000,0.000,0.000,0.000,0.000,0.034,-0.350,-0.937,0.000
0.000000e+00,SIMULATION_STARTING,2003,6,1,12,0,0.000000e+00
6.010010e+02,SIMULATION_COMPLETE,2003,6,1,12,10,1.000000e+00
6.010010e+02,PLATFORM_DELETED,SimpleStriker,blue,BLUE_STRIKER,1.000000e+00,1.050603e+00,2.661749e+00,9.14400000e+03,1.68605423e+06,6.15963498e+06,1.15696178e+05,1.571,0.000,0.000,298.378,0.000,1.000,-0.000,764.068,-0.965,0.264,0.000,0.014,0.000,0.000,1.000,0.091,-0.264,-0.965,-0.003