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": "",
  "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": "Array of two string items, the network file and the speeds file, or null to generate an empty graph",
          "type": ["array", "null"],
          "items": {
            "type": "string"
          "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": ""
    "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
    "traces_output": {
      "advanced":  true,
      "type": "boolean",
      "title": "Traces output",
      "description": "Generate agent traces 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": [
      "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": [
              "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

python3 -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.


agentId: id of the agent


{mode}Distance: distance travelled in <mode> [meters]


{mode}Time: time travelled in <mode> [seconds]


waitTime: total traced wait time [seconds]


nbGetVehicle: number of uses of the vehicle


nbFailedGet: number of failed get requests


nbSuccessGet: number successful get requests


nbFailedPut: number of failed put requests


nbSuccessPut: number of successful put requests


nbFailedRequest: number of failed requests


nbSuccessRequest: number of successful requests


nbFailedGetStaff: number of failed gets by staff


nbSuccessGetStaff: number of successful gets by staff


nbFailedPutStaff: number of failed puts by staff


nbSuccessPutStaff: number of successful puts by staff


emptyTime: time spent empty [seconds]


emptyDistance: distance travelled empty [meters]


fullTime: time spent full [seconds]


fullDistance: distance travelled full [meters]


stockTime: stock relative time (stock*time) [seconds]


stockDistance: stock relative distance (stock*distance) [meters]


maxStock: maximum stock


serviceDuration: vehicle service duration [seconds]


destinationReachedTime: time when destination is reached, "NA" otherwise [seconds or NA]


leaveSimulation: code used when leaving the simulation (see model doc)

Traces file

The traces file is a .txt file which contains the sequence of events of the simulation agents.

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.

The different kind of events are implemented in the module.

This module contains event classes that compose agents’ traces


This event describes the generation of a traced element.


This event describes the route of an agent


This event describes a position change of an agent


This event describes the a waiting agent


This event describes an idle agent


This event describes a user request


This event describes the processing of a Stop


This event describes a staff operation


This event describes an agent getting a vehicle


This event describes an agent returning a vehicle


This event describes an agent leaving the simulation


This event describes an agent reaching its destination


This event describes an agent leaving the simulation.