:py:mod:`starling_sim.utils.paths` ================================== .. py:module:: starling_sim.utils.paths .. autoapi-nested-parse:: 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:`~starling_sim.utils.paths.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 .. code-block:: bash python3 main.py -D It is also generated when :ref:`importing the example scenarios`. ********************************** Global structure of the repository ********************************** .. code-block:: text 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 **************************** .. code-block:: text 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 .. code-block:: bash 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 *************************** .. code-block:: text 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 :ref:`create-models` for more information about the requirements for your models. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: starling_sim.utils.paths.data_folder starling_sim.utils.paths.common_inputs_folder starling_sim.utils.paths.environment_folder starling_sim.utils.paths.osm_graphs_folder starling_sim.utils.paths.graph_speeds_folder starling_sim.utils.paths.gtfs_feeds_folder starling_sim.utils.paths.models_folder starling_sim.utils.paths.model_folder starling_sim.utils.paths.scenario_inputs_folder starling_sim.utils.paths.scenario_parameters_filepath starling_sim.utils.paths.scenario_agent_input_filepath starling_sim.utils.paths.scenario_outputs_folder starling_sim.utils.paths.starling_folder starling_sim.utils.paths.schemas_folder starling_sim.utils.paths.model_import_path Attributes ~~~~~~~~~~ .. autoapisummary:: starling_sim.utils.paths._DATA_FOLDER starling_sim.utils.paths.COMMON_INPUTS_FOLDER starling_sim.utils.paths.ENVIRONMENT_FOLDER_NAME starling_sim.utils.paths.OSM_GRAPHS_FOLDER_NAME starling_sim.utils.paths.GRAPH_SPEEDS_FOLDER_NAME starling_sim.utils.paths.GTFS_FEEDS_FOLDER_NAME starling_sim.utils.paths.SCHEMAS_FOLDER_NAME starling_sim.utils.paths.MODELS_FOLDER_NAME starling_sim.utils.paths.INPUT_FOLDER_NAME starling_sim.utils.paths.OUTPUT_FOLDER_NAME starling_sim.utils.paths.PARAMETERS_FILENAME starling_sim.utils.paths._MODEL_IMPORT_FORMAT .. py:data:: _DATA_FOLDER :value: './data/' .. py:data:: COMMON_INPUTS_FOLDER :value: 'common_inputs' .. py:data:: ENVIRONMENT_FOLDER_NAME :value: 'environment' .. py:data:: OSM_GRAPHS_FOLDER_NAME :value: 'osm_graphs' .. py:data:: GRAPH_SPEEDS_FOLDER_NAME :value: 'graph_speeds' .. py:data:: GTFS_FEEDS_FOLDER_NAME :value: 'gtfs_feeds' .. py:data:: SCHEMAS_FOLDER_NAME :value: 'schemas' .. py:data:: MODELS_FOLDER_NAME :value: 'models' .. py:data:: INPUT_FOLDER_NAME :value: 'inputs' .. py:data:: OUTPUT_FOLDER_NAME :value: 'outputs' .. py:data:: PARAMETERS_FILENAME :value: 'Params.json' .. py:data:: _MODEL_IMPORT_FORMAT :value: '{starling_pkg}.models.{model_code}.model' .. py:function:: data_folder() Path to the data folder. .. py:function:: common_inputs_folder() Path to the common inputs folder .. py:function:: environment_folder() Path to the environment folder. .. py:function:: osm_graphs_folder() Path to the osm graphs folder. .. py:function:: graph_speeds_folder() Path to the graph speeds folder. .. py:function:: gtfs_feeds_folder() Path to the gtfs feeds folder. .. py:function:: models_folder() Path to the models folder. .. py:function:: model_folder(model_code) Path to the folder of the given model code. :param model_code: code of the model .. py:function:: scenario_inputs_folder(scenario_folder) Path to the input folder of the given scenario. :param scenario_folder: scenario folder path .. py:function:: scenario_parameters_filepath(scenario_folder) Path to the parameters file of the given scenario. :param scenario_folder: scenario folder path .. py:function:: 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. :param scenario_folder: scenario folder path :param filename: name of the input file .. py:function:: scenario_outputs_folder(scenario_folder) Path to the output folder in the given scenario folder. :param scenario_folder: scenario folder path .. py:function:: starling_folder() Path to the Starling folder. .. py:function:: schemas_folder() Path to the schemas folder. .. py:function:: model_import_path(starling_pkg, model_code) Import sequence for the given model. :param starling_pkg: name of the root starling package :param model_code: code of the model