feat(mapping): configure type distributions for ScenarioVehicle

[kschrab]

Description

When using predefined SUMO scenarios with, the mapping of applications could be configured using the prototype section by defining a prototype with a name matching the vType identifier of the vehicles, with the weight attribute to control the equipment rate of applications.

However, this allowed only to configure if a vehicle type could be configured with applications or not. No distinction between multiple application deployments could be done. This is now possible with this PR.

In the mapping_config,json, we now allow the typeDistribution section to define a whole distribution of application mappings for one vType identifier from the given SUMO scenario. Let's suppose we only have one vehicle type defined in the SUMO scenario, called "DefaultVehicle", then we can configure a complex application mapping as the following:

"typeDistributions": {
  "DefaultVehicle": [
    { 
      "name": "DefaultVehicle",
      "group": "equippedWithAppA",
      "applications": ["appA"],
      "weight": 0.1 
    },
    { 
      "name": "DefaultVehicle",
      "group": "equippedWithAppB",
      "applications": ["appB"],
      "weight": 0.3 
    },
    { 
      "name": "DefaultVehicle",
      "group": "unequipped",
      "applications": [],
      "weight": 0.6 
    }
  ]
}

Issue(s) related to this PR

• Resolves issue internal issue 624

Affected parts of the online documentation

Changes in the documentation required?

Yes, LuST tutorial should be adjusted to use typeDistributions instead.

Definition of Done

Prerequisites

• You have read CONTRIBUTING.md carefully.
• You have signed the Contributor License Agreement.
• Your GitHub user id is linked with your Eclipse Account.

Required

• The title of this merge request follows the scheme type(scope): description (in the style of Conventional Commits)
• You have assigned a suitable label to this pull request (e.g., enhancement, or bugfix)
• origin/main has been merged into your Fork.
• Coding guidelines have been followed (see CONTRIBUTING.md).
• All checks on GitHub pass.
• All tests on Jenkins pass.

Requested (can be enforced by maintainers)

• New functionality is covered by unit tests or integration tests. Code coverage must not decrease.
• If a bug has been fixed, a new unit test has been written (beforehand) to prove misbehavior
• There are no new SpotBugs warnings.

Special notes to reviewer

[schwepmo]

I think we will need to adjust some further parts of the documentation:

• https://eclipse.dev/mosaic/tutorials/integrate_existing_sumo_scenarios/
• https://eclipse.dev/mosaic/docs/simulators/traffic_simulator_sumo/#adding-vehicles

[schwepmo]

Some minor remarks but overall looks fine

[schwepmo]

Wouldn't it be better to somehow re-use the StochasticSelector for each separate type distribution?

[kschrab]

I could do this somehow I guess, but I'm afraid that it would blow up the code here and would decrease readability. I'm not sure if this would even improve anything.

[schwepmo]

In the BeST-scenario this would cause ~3 million unnecessary initializations of a StochasticSelector, wouldn't it? Also I don't know how the randomness is affected if we draw a type distribution from the same selector or newly initialized ones, although I would assume this doesn't matter.

[kschrab]

I implemented this "cache".

Previous:

final CPrototype selected = new StochasticSelector<>(typeDistribution, randomNumberGenerator).nextItem();

Now:

StochasticSelector<CPrototype> selector = typeDistributionSelectors.get(scenarioVehicle.getVehicleType().getName());
if (selector == null) {
    selector = new StochasticSelector<>(typeDistribution, randomNumberGenerator);
    typeDistributionSelectors.put(scenarioVehicle.getVehicleType().getName(), selector);
}
final CPrototype selected  = selector.nextItem();

Alternative approach, but I'm not 100% sure if other objects (e.g. the object for the lambda) are created instead, that's why I ditched this for now:

final CPrototype selected  = typeDistributionSelectors.computeIfAbsent(
    scenarioVehicle.getVehicleType().getName(), (v) -> new StochasticSelector<>(typeDistribution, randomNumberGenerator)
).nextItem();

[kschrab]

I think we will need to adjust some further parts of the documentation:

• https://eclipse.dev/mosaic/tutorials/integrate_existing_sumo_scenarios/
• https://eclipse.dev/mosaic/docs/simulators/traffic_simulator_sumo/#adding-vehicles

Yes, thanks for pointing out the parts for the adjustments.

[kschrab]

@schwepmo please review again, I used the typeDistribution field in the Sievekingplatz scenario and added an intergration test for it