|
|
This document shows the overall process happening in the simulator when loading a new simulation. This is what the `basic-simulator` does to run simulations.
|
|
|
|
|
|
## Loading the SimulationConfig
|
|
|
|
|
|
The [SimulationConfig](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/simulation/-/blob/master/simulator/src/main/java/de/rwth/montisim/simulation/simulator/SimulationConfig.java) class is the root of all the properties (vehicles, modules, ...) of the simulation.
|
|
|
|
|
|
A `SimulationConfig` object can be loaded from a corresponding JSON scenario using the following:
|
|
|
|
|
|
```java
|
|
|
File scenarioFile = ...;
|
|
|
SimulationConfig simConfig = SimulationConfig.fromFile(scenarioFile);
|
|
|
```
|
|
|
|
|
|
## Loading the Simulator from the SimulationConfig
|
|
|
|
|
|
The call to load a simulation is:
|
|
|
|
|
|
```java
|
|
|
// Example for these objects
|
|
|
Map map = new OsmMap(simConfig.map_name, map_path);
|
|
|
World world = new OsmToWorldLoader(map).getWorld();
|
|
|
Pathfinding pathfinding = new PathfindingImpl(world);
|
|
|
|
|
|
// Call creating the simulation
|
|
|
Simulator simulator = simConfig.build(world, pathfinding, map);
|
|
|
```
|
|
|
|
|
|
The [Simulator](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/simulation/-/blob/master/simulator/src/main/java/de/rwth/montisim/simulation/simulator/Simulator.java) class and the `SimulationConfig` class follow a similar tree structure that can be seen in [Structure Overview (graphic)](/dev-docs/Structure-Overview).
|
|
|
|
|
|
The `SimulationConfig` and all its (member) children contain the **configurable** data for the simulation.
|
|
|
|
|
|
To initialize the simulation, a `build()` method is called recursively on the *properties* tree (starting at the `SimulationConfig` object).
|
|
|
Each **properties object** is responsible to create the corresponding **simulation object**.
|
|
|
|
|
|
Here are some examples of some *properties* classes and the corresponding *simulation object* they build.
|
|
|
|
|
|
```java
|
|
|
SimulationConfig -> Simulator
|
|
|
// Modules
|
|
|
ModuleProperties -> SimulatorModule // (Abstract)
|
|
|
SimpleNetworkProperties -> SimpleNetwork // (Implementation)
|
|
|
// Vehicle
|
|
|
VehicleProperties -> Vehicle
|
|
|
// EEComponents
|
|
|
EEComponentProperties -> EEComponent // (Abstract)
|
|
|
ActuatorProperties -> Actuator // (Implementation)
|
|
|
ComputerProperties -> Computer // (Implementation)
|
|
|
...
|
|
|
```
|
|
|
|
|
|
Most objects follow the *Name*Properties -> *Name* convention.
|
|
|
|
|
|
### Data storage
|
|
|
|
|
|
Every *simulation object* receives its corresponding *properties object* on construction and keeps a reference to it. This prevents from having to copy all the parameters of the simulation, as they are directly accessible in the properties object.
|
|
|
|
|
|
Dynamic simulation data on the other hand is stored in the *simulation object* and has to be serializable (at least for components inside a `Vehicle`).
|
|
|
|
|
|
## Overall build structure
|
|
|
|
|
|
- Create `Map`, `World`, `Pathfinding`
|
|
|
- Load `SimulationConfig`
|
|
|
- `SimulationConfig.build(...)`
|
|
|
- New `Simulator` object.
|
|
|
- For every `ModuleProperties` -> build `SimulatorModule` -> add to simulator & to build context
|
|
|
- For every `VehicleProperties` -> get `VehicleBuilder` -> build `Vehicle` (calls `VehicleProperties.build()`)
|
|
|
- New `Vehicle` object.
|
|
|
- Build `EESystem`.
|
|
|
- Call `PowerTrainProperties.build()`.
|
|
|
- Depends on instance (ex: `ElectricPowerTrain`)
|
|
|
- ...
|
|
|
- Build `PhysicsModel`
|
|
|
- Get `DynamicObject` from physics model
|
|
|
- `Vehicle.addPhysicalValues()`.
|
|
|
- Create sub-build context for EE components.
|
|
|
- `EEComponentProperties.build()` for all components
|
|
|
- Ex: `ActuatorProperties.build()`, `ComputerProperties.build()`, ...
|
|
|
- Connect EE components
|
|
|
- Resolve actuators
|
|
|
- `eesystem.finalizeSetup()`
|
|
|
- Position vehicle
|
|
|
|
|
|
## Build context
|
|
|
|
|
|
In order to access other simulation objects (created before in the build() tree), some properties objects require a [BuildContext](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/commons/-/blob/master/src/main/java/de/rwth/montisim/commons/utils/BuildContext.java) object as parameter of their `build()` function.
|
|
|
|
|
|
This context is filled using key-value pairs of `String` to `Object`.
|
|
|
|
|
|
It is recommended to fill it with objects implementing the [BuildObject](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/commons/-/blob/master/src/main/java/de/rwth/montisim/commons/utils/BuildObject.java) interface. This makes the key-object association less error-prone.
|
|
|
|
|
|
The `getKey()` function returns a key **constant for the class**. (It is a static method in principle but Java interfaces work differently with static methods.) The convention is to have the key that is returned as a static field called `CONTEXT_KEY`.
|
|
|
|
|
|
### Example
|
|
|
|
|
|
An example of how it is used can be seen in the [VehicleProperties](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/simulation/-/blob/master/vehicle/src/main/java/de/rwth/montisim/simulation/vehicle/VehicleProperties.java) build function.
|
|
|
|
|
|
In this function, the `Vehicle` requires the `DiscreteEventSimulator` (which is unique in the simulation) and gets it using:
|
|
|
|
|
|
```java
|
|
|
DiscreteEventSimulator sim = context.getObject(DiscreteEventSimulator.CONTEXT_KEY);
|
|
|
```
|
|
|
|
|
|
The `DiscreteEventSimulator` was added to the context directly in the `Simulator` constructor:
|
|
|
|
|
|
```java
|
|
|
this.eventSimulator = new DiscreteEventSimulator(config.start_time);
|
|
|
...
|
|
|
buildContext.addObject(eventSimulator);
|
|
|
```
|
|
|
|
|
|
### Sub-contexts
|
|
|
|
|
|
A new `BuildContext` can be created upon another. This creates a local context that also has access to all the objects in the parent object.
|
|
|
|
|
|
This is for example used in `VehicleProperties`:
|
|
|
|
|
|
```java
|
|
|
BuildContext compContext = new BuildContext(context);
|
|
|
compContext.addObject(target.physicalValues);
|
|
|
...
|
|
|
```
|
|
|
|
|
|
This allow the `EEComponents` to have access to objects specific to the `Vehicle` being built (`PhysicalValues`, the vehicle's `Updater`, ...) but also the global simulation objects:
|
|
|
|
|
|
```java
|
|
|
/* EEComponentProperties */ properties.build(target.eesystem, /* new sub-context */ compContext);
|
|
|
``` |
|
|
\ No newline at end of file |