Inputs and outputs
Simulations are run using input data and generate output data. These files are stored in
data_folder (see Repository structure).
JSON schemas
We use use JSON Schema to describe the format of some of the files and validate the inputs before running simulations.
Some of these schemas are displayed in this page, but you can also find them in
schemas_folder.
Input data
Inputs consist in environment data, that can be common to several simulation runs, and in scenario inputs, that describe a specific simulation scenario.
Environment data
Environment data is stored in sub-folders of environment_folder.
Such data can be common to several scenarios, for instance OSM graphs.
OSM graphs
OSM graphs files are stored in osm_graphs_folder.
They are .graphml files that contain OSM graphs imported using tools.generate_osm_graph.
These files represent the networks used by the agents to evolve in the simulation and are used to
setup the osm_network using the osmnx library.
Graph speeds
Graph speeds files are stored in graph_speeds_folder.
They are .json files that associate speeds to graph arcs based on their “highway” attribute. If this attribute does not match the fields of the graph speeds, the default value is fetched in the “other” field.
GTFS feeds
GTFS feeds are stored in gtfs_feeds_folder.
They are .zip files that describe a public transport timetable. See Google’s GTFS Static overview for more information. These files can be read using the gtfs-kit library.
Simulation scenario data
For each scenario, the specific input data must be stored in the scenario_input_folder.
For the dynamic and initialisation input files, they can also be stored in the
common_inputs_folder, in order to share the files between several scenarios.
The framework looks in the common inputs folder if it does not find the files in the scenario inputs folder.
Parameters file
The parameters file must be named as PARAMETERS_FILENAME and placed in the
scenario inputs folder. It is a .json file that contains values for several
simulation parameters and files.
Among other things, it contains the simulation model code and the scenario name, which must be consistent with where the parameters file is stored. It also contains the paths or filename of the other input files of the scenario.
For a complete description of the format of the parameters file, see its JSON schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Simulation parameters",
"description": "Parameters of a simulation run",
"type": "object",
"required": ["code", "scenario", "limit", "seed", "visualisation_output", "kpi_output",
"dynamic_input_file", "init_input_file", "topologies"],
"properties": {
"code": {
"type": "string",
"title": "Model code",
"description": "Code of the simulation model to be run"
},
"scenario": {
"type": "string",
"title": "Scenario name",
"description": "Name of the simulation scenario",
"example": "example_scenario"
},
"dynamic_input_file": {
"type": ["string", "null"],
"title": "Dynamic input file",
"description": "File containing the dynamic input",
"example": "CS_SB_dynamic_input.geojson"
},
"init_input_file": {
"type": ["string", "array", "null"],
"title": "Initialisation input files",
"description": "File(s) containing the initialisation input",
"example": "CS_SB_init_input.geojson"
},
"topologies": {
"type": "object",
"title": "Topologies",
"description": "Files for initialising the topologies",
"properties": {
"additional_properties": {
"description": "Object containing network initialisation information, or null to generate an empty graph",
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"graph": {
"description": "Name of the file containing the network graph describing the topology, stored in the graph folder",
"type": "string"
},
"speeds": {
"description": "Name of the file containing the network speeds (stored in the speeds folder) or a number describing a constant speed for all network edges",
"type": ["string", "number"]
},
"weight": {
"description": "Key describing pointing to the class to evaluate the weight on network edges (see topology.py::NETWORK_WEIGHT_CLASSES)",
"type": "string"
},
"network_class": {
"description": "Topology subclass used for representing this network",
"type": "string"
}
},
"required": ["graph", "speeds"]
},
{
"description": "[DEPRECATED] Array of two string items, the network file and the speeds file, or null to generate an empty graph",
"type": "array",
"items": {
"type": ["string", "number"]
},
"minItems": 2,
"maxItems": 3
}
]
}
},
"required": ["walk"]
},
"gtfs_timetables": {
"type": "string",
"title": "GTFS timetables",
"description": "Name of the archive containing the gtfs timetables, placed in the GTFS feeds folder",
"pattern": "(.)*(.zip)",
"example": "GTFS_nantes.zip"
},
"limit": {
"advanced": true,
"type": "integer",
"title": "Simulation time limit [seconds]",
"description": "Duration of the simulation",
"minimum": 1,
"default": 86400
},
"visualisation_output": {
"advanced": true,
"type": "boolean",
"title": "Visualisation output",
"description": "Generate a visualisation file",
"default": true
},
"kpi_output": {
"advanced": true,
"type": "boolean",
"title": "KPI output",
"description": "Generate key performance indicator (KPI) files",
"default": true
},
"kpi_time_profile": {
"advanced": true,
"type": ["boolean", "array"],
"title": "KPI time profile",
"description": "Divide agent KPIs by time intervals",
"default": false
},
"traces_output": {
"advanced": true,
"type": "boolean",
"title": "[deprecated] Traces output",
"description": "Generate agent traces file",
"default": false
},
"events_output": {
"advanced": true,
"type": "boolean",
"title": "Events output",
"description": "Generate a simulation events file",
"default": false
},
"time_log": {
"advanced": true,
"type": "boolean",
"title": "Simulation time log",
"description": "Log simulation time every 3600 seconds (used for run monitoring)",
"default": false
},
"early_dynamic_input": {
"advanced": true,
"type": "integer",
"title": "Early dynamic input offset [seconds]",
"description": "Offset applied to the users origin time to make them enter the simulation earlier, in seconds",
"example": 3600,
"default": 0
},
"make_static": {
"advanced": true,
"type": "string",
"title": "Make inputs static",
"description": "Make certain inputs static, ie generate them at the beginning of the simulation.",
"oneOf": [
{
"const": "all",
"description": "Make all inputs static."
},
{
"const": "prebooked",
"description": "Make static the inputs with prebooked==True."
},
{
"const": "prebooked_only",
"description": "Make static the inputs with prebooked==True and don't generate the others."
},
{
"const": "ghosts",
"description": "Make all inputs static for the resolution, then remove prebooked==False from solution and insert them dynamically."
}
]
},
"store_paths": {
"advanced": true,
"title": "Store shortest paths",
"description": "Store computed shortest paths in a dict to avoid computing them again. Either a boolean or a dict with the same keys as topologies and boolean values.",
"type": [
"boolean",
"object"
],
"default": false
},
"seed": {
"advanced": true,
"type": "number",
"title": "Random seed",
"description": "Seed used for the generation of random events",
"default": 42
},
"multiple": {
"advanced": true,
"type": "integer",
"title": "Multiple scenario",
"description": "Number of sub scenarios to generate",
"minimum": 1
},
"user_routing_parameters": {
"advanced": true,
"type": "object",
"title": "User routing parameters",
"description": "These parameters are used in models including public and on-demand transport",
"properties": {
"objective_type": {
"title": "Objective time type",
"description": "Define if the user is trying to 'depart after' or 'arrive before' the provided objective time",
"type": "string",
"enum": ["start_after", "arrive_before"],
"default": "start_after"
},
"max_nearest_stops": {
"title": "Maximum number of considered stops",
"description": "Number of stops around origin and destination considered by the users when computing journeys",
"type": "integer",
"minimum": 1,
"default": 10
},
"max_distance_nearest_stops": {
"title": "Nearest stops maximum distance [meters]",
"description": "Maximum distance accepted when looking for the nearest stops of origin and destination",
"type": "integer",
"minimum": 0,
"default": 1000
},
"cost_dict": {
"type": "object",
"properties": {
"0": {
"type": "number",
"title": "Tramway route cost",
"description": "Multiplicative factor of the time spent in tramways"
},
"1": {
"type": "number",
"title": "Subway route cost",
"description": "Multiplicative factor of the time spent in subways"
},
"2": {
"type": "number",
"title": "Train route cost",
"description": "Multiplicative factor of the time spent in trains"
},
"3": {
"type": "number",
"title": "Bus route cost",
"description": "Multiplicative factor of the time spent in buses"
},
"4": {
"type": "number",
"title": "On-demand route cost",
"description": "Multiplicative factor of the time spent in on-demand transports"
},
"-1": {
"type": "number",
"title": "Walked route cost",
"description": "Multiplicative factor of the time spent walking"
},
"first_wait": {
"type": "number",
"title": "First waiting time cost",
"description": "Multiplicative factor of the first waiting time. Default will use 'wait'"
},
"wait": {
"type": "number",
"title": "Waiting time cost",
"description": "Multiplicative factor of the time spent waiting"
},
"transfer": {
"type": "number",
"title": "Transfer cost [seconds]",
"description": "Cost value of a transfer"
}
},
"default": {
"0": 1,
"1": 1,
"2": 1,
"3": 1,
"4": 1,
"-1": 1.5,
"wait": 1.5,
"first_wait": 0.5,
"transfer": 600
}
},
"route_choice_parameters": {
"type": "object",
"description": "Parameters of the decision mode among different journeys",
"properties": {
"name": {
"type": "string",
"title": "Route choice method",
"description": "Name of the decision mode",
"enum": [
"earliest",
"min_weight",
"modified_berliaire_1999"
],
"default": "min_weight"
},
"teta": {
"type": "number",
"title": "Teta parameter (modified_berliaire_1999)",
"description": "Teta parameter for the modified_berliaire_1999 method",
"default": 0.2
},
"beta": {
"type": "number",
"title": "Beta parameter (modified_berliaire_1999)",
"description": "Beta parameter for the modified_berliaire_1999 method",
"default": -0.3
}
},
"default": {
"name": "modified_berliaire_1999",
"teta": 0.2,
"beta": -0.3
},
"required": ["name"]
}
},
"required": ["max_nearest_stops", "max_distance_nearest_stops", "cost_dict", "route_choice_parameters"]
}
},
"if": {
"required": ["gtfs_timetables"]
},
"then": {
"properties": {
"date": {
"type": "string",
"title": "Simulation date",
"description": "Date of the simulation, used for filtering services. Format YYYY-MM-DD",
"format": "date",
"example": "2019-10-28"
}
},
"required": ["date"]
}
}
Dynamic input file
The dynamic input file is a .geojson file that contains a representation of the dynamic agents of the simulation.
Here, dynamic means that agents are introduced in the course of the simulation, according to their origin_time key.
Agent inputs are described using Geojson Feature objects
with specific properties. JSON schemas for the agents of a model can be generated using the -J
(or --json-schema) option of main.py
python3 main.py -J SB_VS
The agent features are fetched by DynamicInput (or any class
that inherits from it) in order to initialise simulation agents.
Initialisation input file
The initialisation input file is a .geojson file that contains a representation of the initial agents of the simulation.
This file is similar to the dynamic input file, but here the agents are initialised before the start of the simulation. It can describe, for instance, stations and their vehicles, or a transport operator.
The initialisation file is subject to the same JSON schema than the dynamic input file, initial agents are described with the same specification.
You can also provide a list of geojson files instead of one. In this case, the feature lists of the files are concatenated and processed as in the case of one file.
Output data
For each scenario, the output data should be stored in the output folder
(see OUTPUT_FOLDER_NAME).
The main outputs of the simulation are the visualisation file and the KPI tables.
The specification of what they exactly contain is made by the model developer in the class
extending OutputFactory.
Run summary
The run summary file is a .json file generated at the end of a successful simulation. It contains information about the run (date, Starling version, commit), the simulation parameters, and the outputs of the run.
Visualisation file
The visualisation file is a .geojson file (possibly compressed) generated by a subclass of
GeojsonOutput.
It contains the traces of the simulation agents represented as Geojson Feature objects, with additional simulation information. Static objects are represented with a Point or MultiPolygon geometry, and moving agents with LineString geometry.
For the file visualisation, see the Visualisation section.
KPI tables
The KPI (Key Indicator of Performance) tables are .csv files (possibly compressed), each one generated by an instance of the
KpiOutput class.
Each file corresponds to an agent population and contains specific metrics. For instance, it can contain the total distance walked by the transport users, or the number of uses of a vehicle.
The tables can be extracted and used as any .csv file with relevant software and libraries.
KPI fields
You can find here the correspondence between the most of the KPI fields and their contents.
Events file
The events file is a XML file (possibly compressed) generated by the class
SimulationEvents. The events file replaces the former trace file.
It contains events of the simulation grouped by agent. Here is the detail of the XML elements:
The root element is <document> and contains the event_file_version attribute, the version number of the event file format
Then comes the <agents> element
This element contains an <agent> element for each agent of the simulation, with the id and agentType attributes
Each <agent> element contains the simulation events related to this agent, as XML elements (in chronological order).
An event element’s tag corresponds to the event class name. Class attributes are stored as element attributes. Some event classes store their attributes using subelements.
Traces file (deprecated)
The traces file is a .txt file which contains the sequence of events of the simulation agents. The use of this file is now deprecated, use the events file instead.
Events are grouped by agent, not in chronological order.
The string representation of an event contains the event tracing time, its class name and its main attributes.
Events
The different kind of events are implemented in the starling_sim.basemodel.trace.events module.