Spawner - BP2022-AP1/bp2022-ap1 GitHub Wiki

classDiagram
    class BaseModel {
        <<abstract>>
        +id: uuid
        +created_at: datetime
        +updated_at: datetime
        +save()
        +from_dict(data: dict): BaseModel
        +to_dict(): dict
    }
    BaseModel <|-- SpawnerConfiguration
    class SpawnerConfiguration {
    }
    BaseModel <|-- SpawnerConfigurationXSchedule
    SpawnerConfiguration <-- SpawnerConfigurationXSchedule : has
    ScheduleConfiguration <-- SpawnerConfigurationXSchedule : has
    class SpawnerConfigurationXSchedule {
        +schedule_configuration_id: uuid
        +spawner_configuration_id: uuid
    }

    class Component {
        <<abstract>>
        +logger: Logger
        +priority: int
        +next_tick(tick: int)
    }
    Component <|-- Spawner
    class ISpawnerDisruptor {
        <<interface>>
        +block_schedule(schedule_id: uuid)
        +unblock_schedule(schedule_id: uuid)
    }
    ISpawnerDisruptor <|-- Spawner : implements
    Spawner "" *-- "n" SpawnerConfiguration : configuration
    class Spawner {
        +train_spawner: TrainSpawner
        +get_schedule(schedule_id: uuid) -> Schedule
    }

    BaseModel <|-- ScheduleConfiguration
    class ScheduleConfiguration {
        +schedule_type: str
        +strategy_type: str
        +strategy_start_tick: int
        +strategy_end_tick: int
        +train_schedule_train_type: str
        +regular_strategy_frequency: int
        +random_strategy_trains_per_1000_ticks: float
        +random_strategy_seed: int
        +demand_strategy_power_station: str
        +demand_strategy_scaling_factor: float
        +demand_strategy_start_datetime: datetime
    }
    BaseModel <|-- ScheduleConfigurationXSimulationPlatform
    ScheduleConfiguration <-- ScheduleConfigurationXSimulationPlatform : has
    class ScheduleConfigurationXSimulationPlatform {
        +schedule_configuration_id: uuid
        +simulation_platform_id: uuid
        +index: int
    }

    Spawner o-- "n" Schedule : _schedules
    ScheduleConfiguration <-- Schedule : created_from
    class Schedule {
        <<abstract>>
        +id: uuid
        +from_schedule_configuration(schedule_configuration: ScheduleConfiguration): TrainSchedule
        +maybe_spawn(tick: int, traci_wrapper: ITraCiWrapper)
        +block()
        +unblock()
    }
    Schedule *-- "1" ScheduleStrategy : strategy
    ScheduleConfiguration <-- ScheduleStrategy : created_from
    class ScheduleStrategy {
        <<abstract>>
        +start_tick
        +end_tick
        +from_schedule_configuration(schedule_configuration: ScheduleConfiguration): ScheduleStrategy
        +should_spawn(tick: int): bool
    }

    Schedule <|-- TrainSchedule
    class TrainSchedule {
        +train_type: str
        +platform_ids: list[uuid]
    }

    ScheduleStrategy <|-- RegularScheduleStragegy
    class RegularScheduleStragegy {
        +frequency: int
    }

    ScheduleStrategy <|-- RandomScheduleStrategy
    class RandomScheduleStrategy {
        +trains_per_1000_ticks: float
    }

    ScheduleStrategy <|-- DemandScheduleStrategy
    class DemandScheduleStrategy {
        +power_station: str
        +scaling_factor: float
        +start_datetime: datetime   
    }

    BaseModel <|-- SmardApiIndex
    class SmardApiIndex {
        +timestamp: datetime
    }

    BaseModel <|-- SmardApiEntry
    SmardApiEntry "" *-- "1" SmardApiIndex : index
    class SmardApiEntry {
        +timestamp: datetime
        +value: float
    }

    class SmardDataAvailability {
        +available: bool
        +interval_altered: bool
        +start: datetime
        +end: datetime
        +none(): SmardDataAvailability
    }

    SmardApi <-- DemandScheduleStrategy : uses
    SmardDataAvailability <-- SmardApi : returns
    SmardApiEntry <-- SmardApi : returns
    class SmardApi {
        +data_availability(start: datetime, end: datetime): SmardDataAvailability
        +get_data(start: datetime, end: datetime): list[SmardApiEntry]
    }

The Spawner is responsible for spawning trains (and mater maybe persons) into the simulation. It is created from a SpawnerConfigruation and holds a list of Schedules. Every simulation tick the Spawners next_tick is called with the current simulation tick as argument. The Spawner then iterates through all of its Schedules and calls maybe_spawn on it to spawn a train (or person) if applicable.

Also you can block and unblock the Spawners schedules by calling block_schedule and unblock_schedule respectively and passing the corresponding schedule_id. The spawner therefore implements ISpawnerDisruptor.

The Schedule tells the SPawmer where and when to spawn a train (or person) and what type of train it is. It is created from a ScheduleConfiguration that holds all relevant information. It thereby also creates a ScheduleStrategy from the same ScheduleConfiguration. By calling maybe_spawn one instructs the Schedule to check whether it should perform a spawn. It therefore checks if it is blocked. If not it will consult its ScheduleStrategy to make the final decision and maybe perform the spawn. If the ScheduleStrategy decided to spawn, the Schedule will push the current tick to a stack. Either way it will then check if something lies on the stack. If so will try to spawn it and pop it if successful.

By calling block or unblock you can block or unblock the schedule.

The TrainSchedule inherits from Schedule and is able to spawn trains into the simulation. It holds the train_type to spawn and a list of platform ids which determines the route the trains take through the railway network.

The PersonSchedule inherits from Schedule and is should be able to spawn persons into the simulation. This feature is categorized as a could have for this project and is likely to be a won't have. It is planned to simulate persons that can act as passengers for the trains.

A ScheduleStrategy knows at which ticks a train (or person) needs to be spawned. By calling should_spawn and passing the current tick as argument, one gets a bool answer that determines whether a spawn shuld happen. The ScheduleStrategy has the attributes start_tick and end_tick. It will check if the tick that was asked for is in the range [start_tick, end_tick].

The RegularScheduleStrategy is a specialization of the ScheduleStrategy. It represents a regular (periodical) spawning behavior based on its frequency.

The RandomScheduleStrategy is a specialization of the ScheduleStrategy. It represents a random spawning behavior based on a probability. This probability is stored as trains_per_1000_ticks: float. A value of 1.0 then means that per 1000 ticks a single spawn will occur on average.

To achieve reproducability the RandomScheduleStrategy can also be given a seed.

The DemandScheduleStrategy is a specialization of the ScheduleStrategy. Given a power_station and a start_datetime it can spawn trains based on an estimated coal consumption for this plant based on historical data of electricity production from coal. For further information see Coal Consumption.

The coal consumption can be scaled with the scaling_factor.

A ScheduleConfiguration holds all necessary information to construct a Schedule and its corresponding ScheduleStrategy. It inherits from BaseModel and is therefore serializable, deserializable and stored in the database. It has the following attributes:

• schedule_type: str

  • This is the type of Schedule this configuration represents. It can be one of ('TrainSchedule', 'PersonSchedule') if already implemented.

• strategy_type: str

  • This is the type of ScheduleStrategy this configuration represents. It can be on of ('RegularScheduleStrategy', 'RandomScheduleStrategy', 'DemandScheduleStrategy') if already implemented.

• strategy_start_tick

  • The value for the start_tick of the ScheduleStragety.

• strategy_end_tick

  • The value for the send_tick of the ScheduleStragety.

• regular_strategy_frequency

  • The value for the frequency of the RegularScheduleStrategy.

• random_strategy_trains_per_1000_ticks

  • The value for the trains_per_1000_ticks of the RandomScheduleStrategy.

• random_strategy_seed

  • The value for the seed of the RandomScheduleStrategy.

• demand_strategy_power_station

  • The name of the power station to calculate the coal consumption for from which the amount of trains to spawn is determined. It is one of ["jaenschwalde", "boxberg", "schwarze_pumpe"].

• demand_strategy_start_datetime

  • The Datetime the historical electricity production data, on which the coal consumption calculation is based, should start.

• demand_strategy_scaling_factor

  • A factor the calculated coal consumption is multiplied by before the amount of trains to spawn is determined.

Note that one ScheduleConfuguration has more attributes than are necessary to construct a single specialized ScheduleStrategy because all ScheduleConfigurations are stored in a single table in the database.

Additionally there exists an ordered m:n-relation between ScheduleConfiguration and platforms inside the simulation. This relation is realized with the ScheduleConfigurationXSimulationPlatform. Its index attribute is used to realize the order.

The SpawnerConfiguration holds all necessary information for the construction of a Spawner. It inherits from BaseModel and is therefore serializable, deserializable and stored in the database.

It has no own attributes but is in a m:n-relation with Schedule which is realized with SpawnerConfigurationXSchedule. The SpawnerConfiguration is therefore "just" a container for ScheduleConfigurations.