Load Generation¶

Source entities, event providers, arrival time providers, and load profiles.

Load generation components for simulations.

ArrivalTimeProvider ¶

ArrivalTimeProvider(profile: Profile, start_time: Instant)

Bases: ABC

Computes arrival times by integrating a rate profile.

Finds the time t such that the integral of the rate from current_time to t equals a target value. The target value determines the arrival distribution (constant for deterministic, exponential for Poisson).

Uses scipy's numerical integration and root-finding for accuracy with arbitrary rate profiles.

Attributes:

Name	Type	Description
`profile`		Rate function over time.
`current_time`		Time of the last arrival (updated after each call).

next_arrival_time ¶

next_arrival_time() -> Instant

Compute the next event arrival time.

Integrates the rate profile forward until the accumulated area reaches the target value from _get_target_integral_value().

Returns:

Type	Description
`Instant`	The next arrival time.

Raises:

Type	Description
`RuntimeError`	If the rate is zero indefinitely or optimization fails.

EventProvider ¶

Bases: ABC

Abstract factory for creating payload events at specified times.

Implement this interface to define what events a Source generates. Called by Source.handle_event() at each tick.

get_events `abstractmethod` ¶

get_events(time: Instant) -> list[Event]

Create one or more events to be scheduled at the given time.

Parameters:

Name	Type	Description	Default
`time`	`Instant`	The simulation time when these events should occur.	required

Returns:

Type	Description
`list[Event]`	A list of Events to schedule.

ConstantRateProfile `dataclass` ¶

ConstantRateProfile(rate: float)

Bases: Profile

Profile that returns a constant rate regardless of time.

Parameters:

Name	Type	Description	Default
`rate`	`float`	The constant rate value (e.g., requests per second).	required

LinearRampProfile `dataclass` ¶

LinearRampProfile(
    duration_s: float, start_rate: float, end_rate: float
)

Bases: Profile

Load profile that ramps linearly from start_rate to end_rate.

Parameters:

Name	Type	Description	Default
`duration_s`	`float`	Time over which to ramp.	required
`start_rate`	`float`	Initial rate (e.g., requests per second).	required
`end_rate`	`float`	Final rate (e.g., requests per second).	required

Profile ¶

Bases: ABC

Abstract base class for time-varying rate functions.

Implement get_rate() to define how the rate changes over time. Common patterns: - Constant rate: return same value regardless of time - Step function: return different values for different time ranges - Ramp: linearly interpolate between rates - Periodic: model daily/hourly traffic patterns

get_rate `abstractmethod` ¶

get_rate(time: Instant) -> float

Return the rate at the given simulation time.

Parameters:

Name	Type	Description	Default
`time`	`Instant`	The simulation time to query.	required

Returns:

Type	Description
`float`	The rate value (interpretation depends on usage context).

SpikeProfile `dataclass` ¶

SpikeProfile(
    baseline_rate: float = 10.0,
    spike_rate: float = 150.0,
    warmup_s: float = 10.0,
    spike_duration_s: float = 15.0,
)

Bases: Profile

Load profile that models a spike pattern.

Timeline: - [0, warmup_s): baseline_rate (warm up period) - [warmup_s, warmup_s + spike_duration_s): spike_rate (overload) - [warmup_s + spike_duration_s, ...): baseline_rate (recovery)

This models a realistic scenario where a customer suddenly increases their request rate, potentially saturating a server.

Parameters:

Name	Type	Description	Default
`baseline_rate`	`float`	Normal request rate.	`10.0`
`spike_rate`	`float`	Rate during spike (should saturate server).	`150.0`
`warmup_s`	`float`	Time before spike starts.	`10.0`
`spike_duration_s`	`float`	How long the spike lasts.	`15.0`

ConstantArrivalTimeProvider ¶

ConstantArrivalTimeProvider(
    profile: Profile, start_time: Instant
)

Bases: ArrivalTimeProvider

Deterministic event arrival with regular spacing.

Uses target integral value of 1.0, meaning each event occurs when the accumulated rate reaches 1.0. With constant rate r, this yields events every 1/r seconds.

Use this for reproducible tests and scenarios where exact timing matters.

DistributedFieldProvider ¶

DistributedFieldProvider(
    target: Entity,
    event_type: str,
    field_distributions: dict[str, ValueDistribution],
    static_fields: dict[str, Any] | None = None,
    stop_after: Instant | None = None,
)

Bases: EventProvider

EventProvider that samples event context fields from distributions.

Creates events where specified context fields are dynamically sampled from ValueDistribution instances at each tick. Supports mixing distributed fields with static constant values.

Parameters:

Name	Type	Description	Default
`target`	`Entity`	Target entity for generated events.	required
`event_type`	`str`	Type string for generated events.	required
`field_distributions`	`dict[str, ValueDistribution]`	Dict mapping field names to ValueDistributions. Each field will be sampled independently.	required
`static_fields`	`dict[str, Any] \| None`	Dict of constant field values (optional).	`None`
`stop_after`	`Instant \| None`	Stop generating events after this time (Instant, optional).	`None`

Attributes:

Name	Type	Description
`generated`	`int`	Count of events generated.

Example

provider = DistributedFieldProvider( target=router, event_type="Request", field_distributions={ "customer_id": ZipfDistribution(range(1000), s=1.0), "region": UniformDistribution(["us-east", "us-west", "eu"]), }, static_fields={ "api_version": "v2", }, )

Initialize the provider.

Parameters:

Name	Type	Description	Default
`target`	`Entity`	Entity to receive generated events.	required
`event_type`	`str`	Event type string.	required
`field_distributions`	`dict[str, ValueDistribution]`	Mapping of field names to distributions.	required
`static_fields`	`dict[str, Any] \| None`	Constant values to include in context.	`None`
`stop_after`	`Instant \| None`	Optional time after which to stop generating.	`None`

target `property` ¶

target: Entity

Return the target entity.

event_type `property` ¶

event_type: str

Return the event type string.

get_events ¶

get_events(time: Instant) -> list[Event]

Generate an event with sampled field values.

Parameters:

Name	Type	Description	Default
`time`	`Instant`	Current simulation time.	required

Returns:

Type	Description
`list[Event]`	List containing a single event, or empty list if past stop_after.

PoissonArrivalTimeProvider ¶

PoissonArrivalTimeProvider(
    profile: Profile, start_time: Instant
)

Bases: ArrivalTimeProvider

Stochastic event arrival following a Poisson process.

Uses exponentially distributed target integral values. Combined with a rate profile, this produces a non-homogeneous Poisson process where the instantaneous rate can vary over time.

Use this for realistic load modeling where arrival times have natural variability (e.g., user requests, network traffic).

SimpleEventProvider ¶

SimpleEventProvider(
    target: Entity,
    event_type: str = "Request",
    stop_after: Instant | None = None,
    context_fn: Callable[[Instant, int], dict]
    | None = None,
)

Bases: EventProvider

Event provider that creates targeted events with auto-incrementing IDs.

For simple cases, use directly. For custom context, pass a context_fn::

provider = SimpleEventProvider(
    target=server,
    context_fn=lambda time, count: {
        "created_at": time,
        "request_id": count,
        "priority": "high",
    },
)

Parameters:

Name	Type	Description	Default
`target`	`Entity`	Entity to receive generated events.	required
`event_type`	`str`	Type string for generated events.	`'Request'`
`stop_after`	`Instant \| None`	Stop generating after this time (Instant).	`None`
`context_fn`	`Callable[[Instant, int], dict] \| None`	Optional function(time: Instant, count: int) -> dict to generate custom event context. When None, generates `{"created_at": time, "request_id": count}`.	`None`

Source ¶

Source(
    name: str,
    event_provider: EventProvider,
    arrival_time_provider: ArrivalTimeProvider,
)

Bases: Entity

Self-scheduling entity that generates load events at specified intervals.

Combines an EventProvider (what to generate) with an ArrivalTimeProvider (when to generate) to produce a stream of events. The source maintains its own schedule by creating SourceEvents that trigger the next generation.

Attributes:

Name	Type	Description
`name`		Identifier for logging.

Parameters:

Name	Type	Description	Default
`name`	`str`	Source identifier.	required
`event_provider`	`EventProvider`	Creates the payload events.	required
`arrival_time_provider`	`ArrivalTimeProvider`	Determines timing between events.	required

generated_count `property` ¶

generated_count: int

Number of events generated by this source.

start ¶

start(start_time: Instant) -> list[Event]

Bootstrap the source by scheduling its first tick.

Called by Simulation during initialization. Synchronizes the arrival time provider to the simulation start time.

handle_event ¶

handle_event(event: Event) -> list[Event]

Generate payload events and schedule the next tick.

This implements the source's self-perpetuating loop: 1. Create payload events via the EventProvider 2. Calculate next arrival time 3. Schedule the next SourceEvent 4. Return both payload and next tick for scheduling

constant `classmethod` ¶

constant(
    rate: float,
    target: Entity | None = None,
    event_type: str = "Request",
    *,
    name: str = "Source",
    stop_after: float | Instant | None = None,
    event_provider: EventProvider | None = None,
) -> Source

Create a Source with constant (deterministic) arrival rate.

Parameters:

Name	Type	Description	Default
`rate`	`float`	Events per second.	required
`target`	`Entity \| None`	Entity to receive generated events. Required unless event_provider is given.	`None`
`event_type`	`str`	Type string for generated events.	`'Request'`
`name`	`str`	Source identifier for logging.	`'Source'`
`stop_after`	`float \| Instant \| None`	Stop generating events after this time. Accepts seconds (float) or Instant.	`None`
`event_provider`	`EventProvider \| None`	Custom event provider. When given, target and event_type are ignored.	`None`

Returns:

Type	Description
`Source`	A fully-wired Source ready for use in a Simulation.

poisson `classmethod` ¶

poisson(
    rate: float,
    target: Entity | None = None,
    event_type: str = "Request",
    *,
    name: str = "Source",
    stop_after: float | Instant | None = None,
    event_provider: EventProvider | None = None,
) -> Source

Create a Source with Poisson (stochastic) arrival rate.

Parameters:

Name	Type	Description	Default
`rate`	`float`	Mean events per second.	required
`target`	`Entity \| None`	Entity to receive generated events. Required unless event_provider is given.	`None`
`event_type`	`str`	Type string for generated events.	`'Request'`
`name`	`str`	Source identifier for logging.	`'Source'`
`stop_after`	`float \| Instant \| None`	Stop generating events after this time. Accepts seconds (float) or Instant.	`None`
`event_provider`	`EventProvider \| None`	Custom event provider. When given, target and event_type are ignored.	`None`

Returns:

Type	Description
`Source`	A fully-wired Source ready for use in a Simulation.

with_profile `classmethod` ¶

with_profile(
    profile: Profile,
    target: Entity | None = None,
    event_type: str = "Request",
    *,
    poisson: bool = True,
    name: str = "Source",
    stop_after: float | Instant | None = None,
    event_provider: EventProvider | None = None,
) -> Source

Create a Source with a custom rate profile.

Parameters:

Name	Type	Description	Default
`profile`	`Profile`	Rate profile defining how arrival rate varies over time.	required
`target`	`Entity \| None`	Entity to receive generated events. Required unless event_provider is given.	`None`
`event_type`	`str`	Type string for generated events.	`'Request'`
`poisson`	`bool`	If True (default), use stochastic Poisson arrivals. If False, use deterministic constant arrivals.	`True`
`name`	`str`	Source identifier for logging.	`'Source'`
`stop_after`	`float \| Instant \| None`	Stop generating events after this time. Accepts seconds (float) or Instant.	`None`
`event_provider`	`EventProvider \| None`	Custom event provider. When given, target and event_type are ignored.	`None`

Returns:

Type	Description
`Source`	A fully-wired Source ready for use in a Simulation.

downstream_entities ¶

downstream_entities() -> list[Entity]

Expose the event provider's target for topology discovery.

SourceEvent ¶

SourceEvent(
    time: Instant,
    source_entity: Entity,
    daemon: bool = False,
)

Bases: Event

Tick event that triggers a Source to generate its next payload.

When processed, the Source creates payload events via its EventProvider and schedules the next SourceEvent based on its ArrivalTimeProvider. This bootstrapping pattern keeps the source running without external intervention.

Parameters:

Name	Type	Description	Default
`time`	`Instant`	When this tick should fire.	required
`source_entity`	`Entity`	The Source that will handle this event.	required
`daemon`	`bool`	If True, this tick won't prevent auto-termination.	`False`

Load Generation¶

ArrivalTimeProvider ¶

next_arrival_time ¶

EventProvider ¶

get_events abstractmethod ¶

ConstantRateProfile dataclass ¶

LinearRampProfile dataclass ¶

Profile ¶

get_rate abstractmethod ¶

SpikeProfile dataclass ¶

ConstantArrivalTimeProvider ¶

DistributedFieldProvider ¶

target property ¶

event_type property ¶

get_events ¶

PoissonArrivalTimeProvider ¶

SimpleEventProvider ¶

Source ¶

generated_count property ¶

start ¶

handle_event ¶

constant classmethod ¶

poisson classmethod ¶

with_profile classmethod ¶

downstream_entities ¶

SourceEvent ¶

get_events `abstractmethod` ¶

ConstantRateProfile `dataclass` ¶

LinearRampProfile `dataclass` ¶

get_rate `abstractmethod` ¶

SpikeProfile `dataclass` ¶

target `property` ¶

event_type `property` ¶

generated_count `property` ¶

constant `classmethod` ¶

poisson `classmethod` ¶

with_profile `classmethod` ¶