Repository structure

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.