Instant & Duration

Time representation for the simulation. Instant is a point in time, Duration is a span.

Time representation with nanosecond precision.

This module provides two distinct time concepts:

• Instant: A point in time (e.g., "the event occurs at T=5s")
• Duration: A length of time (e.g., "the operation takes 100ms")

Both use nanoseconds internally to avoid floating-point precision issues that can cause non-deterministic behavior when comparing event times.

Special values: - Instant.Epoch: Time zero (start of simulation) - Instant.Infinity: Represents unbounded time (for auto-termination) - Duration.ZERO: Zero-length duration

Duration

Duration(nanoseconds: int)

Immutable duration value with nanosecond precision.

Represents a length of time, not a point in time. Use for latencies, timeouts, intervals, and other measurements of elapsed time.

Stores time as an integer number of nanoseconds to avoid floating-point errors. Supports arithmetic with other Durations or float seconds.

Attributes:

Name	Type	Description
nanoseconds		The duration in nanoseconds.

Create a Duration from nanoseconds.

Parameters:

Name	Type	Description	Default
nanoseconds	int	Duration in nanoseconds.	required

from_seconds classmethod

from_seconds(seconds: int | float) -> Duration

Create a Duration from a seconds value.

Parameters:

Name	Type	Description	Default
seconds	int | float	Duration in seconds (int or float).	required

Returns:

Type	Description
Duration	New Duration representing the given length of time.

Raises:

Type	Description
TypeError	If seconds is not int or float.

to_seconds

to_seconds() -> float

Convert this Duration to seconds as a float.

__add__

__add__(other: Union[Duration, int, float]) -> Duration

Add two durations or a duration and seconds.

__radd__

__radd__(other: Union[int, float]) -> Duration

Support seconds + Duration.

__sub__

__sub__(other: Union[Duration, int, float]) -> Duration

Subtract durations or seconds from a duration.

__mul__

__mul__(other: int | float) -> Duration

Multiply duration by a scalar.

__rmul__

__rmul__(other: int | float) -> Duration

Support scalar * Duration.

__truediv__

__truediv__(other: int | float) -> Duration

Divide duration by a scalar.

__repr__

__repr__() -> str

Return a human-readable duration string.

Format: D{hours}:{minutes}:{seconds}.{microseconds} Examples: D00:00:01.500000, D01:23:45.678901

Instant

Instant(nanoseconds: int)

Immutable time point with nanosecond precision.

Represents a specific point in time, not a duration. Use for event timestamps, scheduling times, and absolute time references.

Stores time as an integer number of nanoseconds to avoid floating-point errors. Supports arithmetic with Durations or float seconds.

Attributes:

Name	Type	Description
nanoseconds		The time value in nanoseconds since epoch.

Create an Instant from nanoseconds since epoch.

Parameters:

Name	Type	Description	Default
nanoseconds	int	Time in nanoseconds since simulation start.	required

from_seconds classmethod

from_seconds(seconds: int | float) -> Instant

Create an Instant from a seconds value.

Parameters:

Name	Type	Description	Default
seconds	int | float	Time in seconds (int or float).	required

Returns:

Type	Description
Instant	New Instant representing the given point in time.

Raises:

Type	Description
TypeError	If seconds is not int or float.

to_seconds

to_seconds() -> float

Convert this Instant to seconds as a float.

__add__

__add__(other: Union[Duration, int, float]) -> Instant

Add a duration to an instant, producing a new instant.

Instant + Duration = Instant (a point in time shifted by a duration) Instant + float = Instant (float interpreted as seconds)

__radd__

__radd__(other: Union[int, float]) -> Instant

Support seconds + Instant.

__sub__

__sub__(
    other: Union[Instant, Duration, int, float],
) -> Union[Instant, Duration]

Subtract from an instant.

Instant - Instant = Duration (the time between two points) Instant - Duration = Instant (a point in time shifted backwards) Instant - float = Instant (float interpreted as seconds)

__repr__

__repr__() -> str

Return a human-readable ISO-like time string with microsecond precision.

Format: T{hours}:{minutes}:{seconds}.{microseconds} Examples: T00:00:01.500000, T01:23:45.678901