tellae / starling Goto Github PK

Problem exposition

Stop points are an exception in Starling, as they are stored in the agent population as if they were agents. They are stored here because it is convenient to have the global collection of stop points instead of each operator having its collection of stops.

Solution proposed

It could be useful to make StopPoint inherit from SpatialAgent. They are not so different from stations, and could even also use a SimPy store for their agent queues.

It would also allow tracing events for stop points and compute specific KPIs.

This implies many modifications on how stop points are managed, at many different points in Starling.

It would be nice to have default values for the parameters that are not common to all models. This would allow creating scenario instances based on a single form, containing the common parameters.

I think the graph_speeds should probably rename speed_graphs

Problem exposition

At the current date, the output file containing the simulation events is stored in .txt file, with events formatted as strings using their str() method.

This makes the event file little usable from outside, as it would demand a very specific parsing.

However, the event log of the simulation can be very useful, as it contains the rawest description of the whole simulation.
For instance, it can be used to compute KPIs instead of having to compute them in Starling, or generate visualisation files using a different format from Starling.

Proposed solution

Generate the event output file at a more common format for this type of file.

The best format for this seems to be XML (it is the format used by MATSim for its event log)

Problem exposition

It would often be preferable to have the operator input and its fleet separated in different files.

The operator input describes the transport service, it is almost part of the model definition. It is therefore less likely to change than the fleet of vehicles, as they describe the transport offer, which is often modified in simulation scenarios to see how the service quality evolves.

In a more generic matter, Starling users may want to separate their inputs by agent types, as they may be generated in different ways (e.g. staff vehicles may be added manually and bikes generated from open data stocks).

Proposed solution

Allow the "init_input_file" parameter to be an array that contains a list of filenames. Files are read and agents are added following the array order.

This could also be done for the "dynamic_input_file" parameter, but all files would be read at once in order to get all the agents and introduce them in the simulation in chronological order.

Following #37, we encountered the need of height data on our graphs.

One source for such data is EU-DEM, that provides a file containing height data (raster) for European countries with a good precision. The format used is TIF.

Proposition

Create a script that enriches a given graph with height data from a given TIF file. Maybe add an option to the generate_osm_graph script to enrich the OSM graph after extracting it.

Following #35, the next step for network weight class feature is to support agent parameters for the computation of the network weight.

The specification of the agent parameters needs to be decided:

• Associate user groups to sets of parameters. But this does not allow dynamic changes of the parameters, during the simulation (for instance when the agent gets a vehicle, parameters may depend on the presence of an electric assistance)
• Should these groups and parameters be inputs of the model, or defined within the model ?
• Some simulation dependent parameters could apply a fixed effect on other parameters

Since v1.1.0, OSMnx get_nearest_nodes function can also return the array of distances to the given localisation.

Proposition:

Get the distances from get_nearest_nodes instead of computing them in Environment.nearest_node_in_modes()

Problem exposition

Today, the unused fields of the inputs properties are lost: they are not present in the output trace.

For instance, a synthetic population may contain socioeconomic profiling of the users. It could be nice to keep these in the trace geojson.

Proposed solution

Add a new attribute in the Agent class that stores the unused properties, and use it when generating the trace.

Problem exposition

The specifications of the inputs of a given model (which properties are available, required, their type, etc) cannot be known from the outside of the simulator.

For instance, to know that the SB_VS User class can be provided with "max_tries" or "closest_station_evaluation" properties, one has to go look at the class declaration (and its parent class').

Same goes for the "operation_parameters" property of the SB_VS_R Operator class, which must contain the fields "start_time", "duration", "neighbor" and other ones.

Even the allowed agent types are stored in the Model class.

Today, new scenario inputs are created based on existing scenarios, which limits the use to the same properties.

Proposed solution

The idea is to generate JSON Schemas dynamically for a specific model. Call main.py with an option to get a complete JSON Schema for each agent type.

How to do so ?

• Each agent could store the schema for its own properties in class attributes, and inherit from its parent' schema if needed.

  • The implementation can be fast enough (?). The idea is already present in the Person PROPERTIES class attribute.
  • Replication of code (enumeration of the parameters, default values...)

• The schema could be generated from the class meta information (parameters with default values, description from docstring, etc)

  • The implementation may be difficult (no sure it is doable)
  • No replication of code

Sections of Starling's documentation that are missing or incomplete

• Understanding Starling: a section that explains the functioning of Starling, its different parts (SimulationModel, Environment, DynamicInput, Scheduler, etc) and how they interact. Ideas of subsections:

  • Global structure of a multi-agent simulator
  • Simulation model
  • Environment
  • Agent population
  • Agents
  • Scheduler
  • Dynamic input
  • Output factory

• Creating your own models: a section that explains how to create your own model. The classes to create, the methods and attributes to implement, etc.

• Algorithms: a section that describes the existing algorithms and explains the interface used for the integration of new algorithms.

Problem exposition

The computation of the maximum trip time using the max detour parameter is duplicated in several models.

Proposed solution

Create a static method in the Operator class that refactors the code.

Following #37, it appears that we may need additional OSM tags than those kept by osmnx (see useful_tags_way here).
An option should be added to the generate_osm_graph script and the corresponding function import_osm_graph in utils.py.

To specify additional tags to keep when extracting with osmnx, we can do this:

ox.config(useful_tags_way=ox.settings.useful_tags_way + ['cycleway'])

This is not very nice since we have to list manually all relevant tags (for instance, we may want to add 'cycleway:left' and 'cycleway:right' here). However, this seems inevitable regarding the number of tags OSM proposes.

https://docs.python.org/3.7/library/time.html?highlight=time%20clock#time.clock

time.clock is deprecated since Python 3.3, it should be replaced with time.time

Mettre des informations sur la page pypi pour qu'elle ne soit pas vide https://pypi.org/project/starling-sim/
Et expliquer qu'il ne s'agit pas d'un package très classique.
Ultérieurement il faudra en faire un usage plus classique.

Problem exposition

Agent-based simulators are not easy to test. There are many levels of implementation that need testing ([1] proposes the micro, meso and macro-level). Furthermore, since Starling is still a prototype, the expected results may change frequently.

Today, the existing test process is a set of scenarios and their expected results. The output files of the scenario on the current branch are compared to the expected outputs, and if they differ, the test fails. This process is launched using the -t option with main.py.

This is test process is clearly insufficient, or at least more test scenarios should be developed. You are very welcome to propose new test procedures and scenarios.

[1]: Gürcan, Ö, O Dikenelli, and C Bernon. ‘A Generic Testing Framework for Agent-Based Simulation Models’. Journal of Simulation 7, no. 3 (August 2013): 183–201. https://doi.org/10.1057/jos.2012.26.

Problem exposition

Some agents depend on others to be created, therefore enforcing a specific order in agent initialisation. For instance a vehicle sharing station must be created before its vehicles, or an operator before its staff members.

Today, initialisation (non-users) agents are created following the input's order. If a shared bike appears before its station, an error occurs. This is a problem, since there is no real specification of the required input order. Moreover, having to sort its inputs depending on the agent type is really annoying in itself.

Proposed solution

I think that in most of the current cases, the required ordering exclusively depends on the agent's type. Therefore, specifying an order on the agent types, and then sorting the inputs according to this order could be a solution. Maybe using an OrderedDict for the agent_type_class specification could do the trick, and avoid repetition of the agent types.

Problem exposition

Scenario can be created manually or by doing a copy of an existing scenario and adding small modifications.

In the second case, the modeler may forget to change the scenario name in the parameters file.

This can lead to simulation problem and even overwriting the outputs of the original scenario.

Proposed solution

Check that the scenario folder has the same name than the scenario name specified in the parameters file when reading the parameters file. Raise an error if it is not the case.

A config file already exists in Starling, but we should move most of the global variables used in Starling in the config (like the data folder)

A default config containing default value for each attributes should be stored in the package.

Some of the config values are related to the actual simulation (walking speed, distance factor?), while others are related to the environment and the inputs/outputs. Should we separate these two types of configs ?

Maybe use a class like this:

class StarlingConfig:
    def __init__(self, config_dict):
        self.provided_config = config_dict
        
        final_config = copy.deepcopy(DEFAULT_CONFIG)
        final_config.update(config_dict)
        self._config = final_config
        
    @property
    def config(self):
        return self._config
    
    def __getitem__(self, item):
        return self._config[item]

Problem exposition

Vehicles of the StationBased models require a "station" property which describes their first station, and therefore determine their origin position and update the first station stock.

Today, this property is read in the SB_VS DynamicInput subclass, which does not allow a full readability.

Proposed solution

Create a StationBasedVehicle class that requires a "station" parameter and that does the necessary processing (infer origin, update station stock, and even store origin station ?)

It would be great to be able to specify both input and output dir, if we want to run a simulation with a simpler directory structure

Problem exposition

Sometimes it can be useful to specify the value of an agent input property as equal to the attribute of another agent.

For instance, in the SB_VS model, users OD may be defined from one station to another. Today, the "origin_station" and "destination_station" fields can be used for this purpose. A generic way of defining inputs as a copy of an agent attribute could avoid us creating and reading such specific fields.

Proposed solution

The following JSON Schema could describe this generic property:

SCHEMA_PROPERTY_FROM = {
    "title": "Properties from other objects",
    "description": "Creates new fields as copies of attributes of other objects.",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "attribute": {"description": "Attribute copied from the target object.", "type": "string"},
            "id": {"description": "Id of the target object.", "type": ["string", "number"]},
            "population": {"description": "Population of the target object.", "type": "string"},
            "key": {"description": "Key used for the created field. Default as the attribute name.", "type": "string"},
        },
        "required": ["attribute", "id", "population"]
    }
}

Objective: add more content to the run summary, in order to help reading the scenario contents once the run has finished