Clocks

Overview

Clocks provide a unified interface for time abstraction in Gears. They allow you to work with either real system time or controllable virtual time for simulations.

Clock Interface

All clocks implement the Clock abstract type and must provide:

now(clock::Clock) -> Quantity{<:Number, 𝐓}

Implementations

MachineClock

Uses system time for real-time simulations.

Gears.MachineClockType
MachineClock

A clock that uses the system time. The time is represented in seconds. Supports pausing and resuming to decouple logical time from system time. The start_time, pause_start_time, and total_paused_time are all represented in seconds and are wall clock (unstretched) time. Whenever now is called, the time is stretched by the stretch_factor. This means that when the stretch_factor is greater than 1, the time will progress faster than the wall clock time.

Fields

  • start_time::T: The system time when the clock was created or last reset
  • paused::Bool: Whether the clock is currently paused
  • total_paused_time::T: Cumulative time spent paused
  • pause_start_time::Union{T, Nothing}: System time when current pause started (if any)
  • stretch_factor::F: The factor by which to stretch the time
source

VirtualClock

Controllable time for deterministic simulations.

Gears.VirtualClockType
VirtualClock

A clock that uses virtual time for simulations. The time is represented in seconds.

Fields

  • current_time::T: The current time of the clock

This clock can be advanced with the advance_time! function.

source

Usage Examples

using Gears


# Real-time clock
clock = MachineClock()
println(now(clock))  # Machine clock starts paused

# Virtual clock for simulations
clock = VirtualClock()
advance_time!(clock, 50ms)
println(now(clock))  # 0.05 s
0.0 s
0.05 s