`starling_sim.utils.paths`

Starling has a precise repository structure in order to separate the base classes of the framework, the simulation models and the simulation data.

You will find here the structure of different parts of the project.

Data folder generation

The data_folder and sub-folders are not included in the git repository, but they can be generated using the -D (or --data-tree) option of main.py

python3 main.py -D

It is also generated when importing the example scenarios.

Global structure of the repository

starling-repo
├── starling_sim            # simulation modules
|   |
│   ├── basemodel           # base classes of the framework
│   ├── models              # concrete models extending the basemodel
|   ├── schemas             # json schemas
│   └── utils               # programming utils
|
├── tools                   # tools for the simulation runs
├── data                    # data folder
├── tests                   # testing
├── docs                    # documentation files and scripts
├── main.py
├── requirements.txt
├── .gitignore
├── CHANGELOG.md
└── README.md

Structure of the data folder

data
├── common_inputs           # inputs shared between scenarios
|
├── environment             # environment data
│   |
│   ├── graph_speeds        # .json files containing the graph speeds
│   ├── gtfs_feeds          # .zip files containing the gtfs feeds
│   └── osm_graphs          # .graphml files containing the OSM graphs
|
└── models                  # simulation scenarios
    |
    ├── SB_VS               # SB_VS scenarios
    |   |
    |   ├── scenario_1      # scenario_1 data
    |   |   |
    │   |   ├── inputs      # scenario_1 inputs
    │   |   └── outputs     # scenario_1 outputs
    |   |
    |   └── scenario_2      # scenario_2 data
    └── ...

The path to the data repository can be changed using the –data-folder option of main.py

python3 main.py path/to/scenario/ --data-folder path/to/data_folder/

However, the structure of the data repository must remain the same. This is ensured by the functions declared in starling_sim.utils.paths.py, that build the paths to the different folders by concatenating the folder names in the correct order.

Structure of models package

starling_sim
└── models
    ├── SB_VS             # public SB_VS model
    ├── ...               # other public models
    │
    └── MY_MODEL          # your own model
        |
        ├── model.py      # model module containing class Model(SimulationModel)
        ├── my_agent.py   # other simulation modules for your model
        └── ...

The models package is where concrete models extending the base model are placed. It contains public models and the ones you developed.

The packages must be named with the model code, and contain a model.py module. This module must contain a Model class extending SimulationModel of the base model. See Creating your own models for more information about the requirements for your models.

Module Contents

Functions

`data_folder`()	Path to the data folder.
`common_inputs_folder`()	Path to the common inputs folder
`environment_folder`()	Path to the environment folder.
`osm_graphs_folder`()	Path to the osm graphs folder.
`graph_speeds_folder`()	Path to the graph speeds folder.
`gtfs_feeds_folder`()	Path to the gtfs feeds folder.
`models_folder`()	Path to the models folder.
`model_folder`(model_code)	Path to the folder of the given model code.
`scenario_inputs_folder`(scenario_folder)	Path to the input folder of the given scenario.
`scenario_parameters_filepath`(scenario_folder)	Path to the parameters file of the given scenario.
`scenario_agent_input_filepath`(scenario_folder, filename)	Get the path to the scenario input file (dynamic or initialisation file).
`scenario_outputs_folder`(scenario_folder)	Path to the output folder in the given scenario folder.
`starling_folder`()	Path to the Starling folder.
`schemas_folder`()	Path to the schemas folder.
`model_import_path`(starling_pkg, model_code)	Import sequence for the given model.

Attributes

`_DATA_FOLDER`
`COMMON_INPUTS_FOLDER`
`ENVIRONMENT_FOLDER_NAME`
`OSM_GRAPHS_FOLDER_NAME`
`GRAPH_SPEEDS_FOLDER_NAME`
`GTFS_FEEDS_FOLDER_NAME`
`SCHEMAS_FOLDER_NAME`
`MODELS_FOLDER_NAME`
`INPUT_FOLDER_NAME`
`OUTPUT_FOLDER_NAME`
`PARAMETERS_FILENAME`
`_MODEL_IMPORT_FORMAT`

starling_sim.utils.paths._DATA_FOLDER = './data/'

starling_sim.utils.paths.COMMON_INPUTS_FOLDER = 'common_inputs'

starling_sim.utils.paths.ENVIRONMENT_FOLDER_NAME = 'environment'

starling_sim.utils.paths.OSM_GRAPHS_FOLDER_NAME = 'osm_graphs'

starling_sim.utils.paths.GRAPH_SPEEDS_FOLDER_NAME = 'graph_speeds'

starling_sim.utils.paths.GTFS_FEEDS_FOLDER_NAME = 'gtfs_feeds'

starling_sim.utils.paths.SCHEMAS_FOLDER_NAME = 'schemas'

starling_sim.utils.paths.MODELS_FOLDER_NAME = 'models'

starling_sim.utils.paths.INPUT_FOLDER_NAME = 'inputs'

starling_sim.utils.paths.OUTPUT_FOLDER_NAME = 'outputs'

starling_sim.utils.paths.PARAMETERS_FILENAME = 'Params.json'

starling_sim.utils.paths._MODEL_IMPORT_FORMAT = '{starling_pkg}.models.{model_code}.model'

starling_sim.utils.paths.data_folder(): Path to the data folder.

starling_sim.utils.paths.common_inputs_folder(): Path to the common inputs folder

starling_sim.utils.paths.environment_folder(): Path to the environment folder.

starling_sim.utils.paths.osm_graphs_folder(): Path to the osm graphs folder.

starling_sim.utils.paths.graph_speeds_folder(): Path to the graph speeds folder.

starling_sim.utils.paths.gtfs_feeds_folder(): Path to the gtfs feeds folder.

starling_sim.utils.paths.models_folder(): Path to the models folder.

starling_sim.utils.paths.model_folder(model_code)

Path to the folder of the given model code.

Parameters:: model_code – code of the model

starling_sim.utils.paths.scenario_inputs_folder(scenario_folder)

Path to the input folder of the given scenario.

Parameters:: scenario_folder – scenario folder path

starling_sim.utils.paths.scenario_parameters_filepath(scenario_folder)

Path to the parameters file of the given scenario.

Parameters:: scenario_folder – scenario folder path

starling_sim.utils.paths.scenario_agent_input_filepath(scenario_folder, filename)

Get the path to the scenario input file (dynamic or initialisation file).

First, look in the scenario input folder. If the file is not found, look in the common inputs folder. If the file is not there, raise a FileNotFoundError.

Parameters:

scenario_folder – scenario folder path
filename – name of the input file

starling_sim.utils.paths.scenario_outputs_folder(scenario_folder)

Path to the output folder in the given scenario folder.

Parameters:: scenario_folder – scenario folder path

starling_sim.utils.paths.starling_folder(): Path to the Starling folder.

starling_sim.utils.paths.schemas_folder(): Path to the schemas folder.

starling_sim.utils.paths.model_import_path(starling_pkg, model_code)

Import sequence for the given model.