Skip to content

Commit

Permalink
feat: unify parameters filename (#41)
Browse files Browse the repository at this point in the history
The name "Params.json" (stored in paths.py) is now mandatory for the parameters file
leo-desbureaux-tellae authored Mar 14, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 249cf0f commit 93fdd22
Showing 5 changed files with 30 additions and 26 deletions.
28 changes: 11 additions & 17 deletions docs/run/io.rst
Original file line number Diff line number Diff line change
@@ -59,10 +59,7 @@ 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 input folder
(see :data:`~starling_sim.utils.paths.INPUT_FOLDER_NAME)`.

For each scenario, the specific input data must be stored in the :data:`~starling_sim.utils.paths.scenario_inputs_folder`.
For each scenario, the specific input data must be stored in the :data:`~starling_sim.utils.paths.scenario_input_folder`.

For the dynamic and initialisation input files, they can also be stored in the
:data:`~starling_sim.utils.paths.common_inputs_folder`, in order to share the files between several scenarios.
@@ -71,34 +68,31 @@ The framework looks in the common inputs folder if it does not find the files in
Parameters file
+++++++++++++++

The parameters file is a .json file that contains values for several simulation parameters.
The parameters file must be named as :data:`~starling_sim.utils.paths.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:

.. literalinclude:: ../../schemas/parameters.schema.json
.. literalinclude:: ../../starling_sim/schemas/parameters.schema.json
:language: json

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.

Here, dynamic means that agents are introduced in the course of the simulation, according to their "origin_time" key.
For now, this file is dedicated to the description of the transport users.

The JSON schema describing these agents is:
Agent inputs are described using `Geojson <https://geojson.org/>`_ 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

.. literalinclude:: ../../schemas/AgentFeature.schema.json
:language: json
.. code-block:: bash
As you can see, agents are described using `Geojson <https://geojson.org/>`_ Feature objects
with additional properties. These properties are described by this second JSON schema:

.. literalinclude:: ../../schemas/AgentProperties.schema.json
:language: json
python3 main.py -J SB_VS
The agent features are fetched by :class:`~starling_sim.basemodel.input.dynamic_input.DynamicInput` (or any class
that inherits from it) in order to initialise simulation agents.
5 changes: 5 additions & 0 deletions starling_sim/basemodel/parameters/simulation_parameters.py
Original file line number Diff line number Diff line change
@@ -3,6 +3,7 @@
"""

import logging
import os
from copy import deepcopy

from starling_sim.utils.utils import json_load, validate_against_schema
@@ -131,6 +132,10 @@ def __init__(self, filepath):
:param filepath:
"""

# check that the parameters file has the correct name
if os.path.basename(filepath) != paths.PARAMETERS_FILENAME:
raise ValueError("The parameters file must be named " + paths.PARAMETERS_FILENAME)

# read json
json_param = json_load(filepath)

7 changes: 0 additions & 7 deletions starling_sim/schemas/starling_config.schema.json
Original file line number Diff line number Diff line change
@@ -15,13 +15,6 @@
"exclusiveMinimum": 0,
"default": 1.1
},
"parameters_file": {
"title": "Parameters filename",
"description": "Parameters filename used if none is provided",
"type": "string",
"pattern": "(.)*(.json)",
"default": "Params.json"
},
"geojson_format": {
"title": "GeoJSON output format",
"description": "Filename format of the GeoJSON output. Placeholder: {scenario}",
13 changes: 13 additions & 0 deletions starling_sim/utils/paths.py
Original file line number Diff line number Diff line change
@@ -138,6 +138,9 @@
#: name of the output folder
OUTPUT_FOLDER_NAME = "outputs"

#: unique parameters filename
PARAMETERS_FILENAME = "Params.json"

#: format of the model import string
_MODEL_IMPORT_FORMAT = "{starling_pkg}.models.{model_code}.model"

@@ -220,6 +223,16 @@ def scenario_input_folder(model_code, scenario):
return scenario_folder(model_code, scenario) + INPUT_FOLDER_NAME + _SEP


def scenario_parameters_filepath(model_code, scenario):
"""
Path to the parameters file of the given scenario.
:param model_code: code of the model
:param scenario: name of the scenario
"""
return scenario_input_folder(model_code, scenario) + PARAMETERS_FILENAME


def scenario_output_folder(model_code, scenario):
"""
Path to the output folder of the given scenario.
3 changes: 1 addition & 2 deletions starling_sim/utils/test_models.py
Original file line number Diff line number Diff line change
@@ -3,7 +3,6 @@
from starling_sim.utils.simulation_logging import TEST_LOGGER
from starling_sim.utils.utils import gz_decompression
from starling_sim.utils import paths
from starling_sim.utils.config import config

import os
import subprocess
@@ -126,7 +125,7 @@ def test_model(model_code, pkg):
def test_scenario(model_code, pkg, scenario):

# get the scenario parameters file
parameters_path = paths.scenario_input_folder(model_code, scenario) + config["parameters_file"]
parameters_path = paths.scenario_parameters_filepath(model_code, scenario)

# test the existance of the scenario
if not os.path.exists(parameters_path):

0 comments on commit 93fdd22

Please sign in to comment.