SciML Clock Interfaces

Clocks

Backwards-compatible namespace for ContinuousClock, PeriodicClock, SolverStepClock, and EventClock. New code can import these public clock types directly from SciMLBase; the namespace remains available for code that uses names such as SciMLBase.Clocks.PeriodicClock.

abstract type AbstractClock

Base interface for time-domain clock objects.

Clocks describe the independent-variable times at which discrete quantities are sampled or updated. SciMLBase defines periodic clocks, solver-step clocks, continuous clocks, and event clocks as lightweight descriptors. Downstream packages may store clocks in symbolic indexing metadata and solution discrete time-series data so callers can evaluate sol(clock[idx]) at the corresponding times.

Clock objects are scalar descriptors for broadcasting, callable as clock() for backwards-compatible code paths, and can be indexed to form an IndexedClock. Use the trait helpers isclock, issolverstepclock, iscontinuous, and is_discrete_time_domain when code needs to branch on clock semantics.

struct ContinuousClock <: SciMLBase.AbstractClock

Clock representing the continuous independent-variable domain.

ContinuousClock() is used when a quantity should be interpreted on the same continuous time axis as the solution itself. Indexing a continuous clock and canonicalizing it against a saved time-series solution selects entries from sol.t.

struct PeriodicClock <: SciMLBase.AbstractClock

Clock with nominal periodic ticks.

PeriodicClock(dt; phase = 0.0) describes ticks separated by dt. A dt of nothing means the interval has not been fixed and may be inferred by downstream tooling. phase is stored as clock metadata for packages that need a phase offset.

Fields

• dt::Union{Nothing, Rational{Int64}, Float64}: Nominal tick interval, or nothing when the interval is left for downstream inference.

• phase::Float64: Phase offset metadata for the periodic clock.

struct SolverStepClock <: SciMLBase.AbstractClock

Clock that ticks at accepted solver steps.

Solver-step clocks do not generally have equidistant ticks: adaptive step-size selection and event handling can change the tick times. They are useful for querying quantities saved on the solver's internal step sequence, but they are not a fixed-sample-rate clock unless the solver itself is fixed-step and has no events that alter the step sequence.

struct EventClock <: SciMLBase.AbstractClock

Clock identified by a named event.

EventClock(id) is a descriptor for event-triggered discrete time domains. The event identity is stored in id; concrete event detection and storage semantics are supplied by downstream packages that attach event-clock data to a solution or symbolic system.

Fields

• id::Symbol: Symbol identifying the event stream associated with this clock.

TimeDomain

Backwards-compatible alias for AbstractClock.

Use TimeDomain in old code paths that dispatch on clock-like time-domain descriptors. New interface documentation should refer to AbstractClock and the concrete clock types directly.

Continuous

Singleton ContinuousClock value for the continuous time domain.

Clock(dt)
Clock(; phase = 0.0)

Construct the default PeriodicClock.

Clock(dt; phase = 0.0) converts numeric dt values to a periodic clock with that tick interval. Rational and Float64 intervals are preserved, while other numeric intervals are converted to Float64. Calling Clock(; phase) leaves dt as nothing, allowing downstream tooling to infer the interval when possible.

isclock(clock)

Return true when clock is a periodic sampled clock.

This legacy trait currently recognizes PeriodicClock values only. Use iscontinuous, issolverstepclock, and is_discrete_time_domain for the broader clock-family predicates.

issolverstepclock(clock)

Return true if clock is a SolverStepClock.

iscontinuous(clock)

Return true if clock is a ContinuousClock.

iseventclock(clock)

Return true if clock is an EventClock.

is_discrete_time_domain(clock)

Return true when clock represents a discrete time domain.

nothing is treated as not discrete. Any clock that is not continuous is treated as discrete, including periodic, solver-step, and event clocks.

first_clock_tick_time(clock, t0)

Return the first tick time for a discrete clock at or after t0.

For PeriodicClock, this is the first multiple of dt at or after t0. For SolverStepClock, the first tick is t0. Continuous and event clocks do not have a generic first tick time and throw an error.

struct IndexedClock{C<:SciMLBase.AbstractClock, I}

A struct representing the operation of indexing a clock to obtain a subset of the time points at which it ticked. The actual list of time points depends on the tick instances on which the clock was ticking, and can be obtained via canonicalize_indexed_clock by providing a timeseries solution object.

For example, IndexedClock(PeriodicClock(0.1), 3) refers to the third time that PeriodicClock(0.1) ticked. If the simulation started at t = 0, then this would be t = 0.2. Similarly, IndexedClock(PeriodicClock(0.1), [1, 5]) refers to t = 0.0 and t = 0.4 in this context.

Fields

• clock::SciMLBase.AbstractClock: The clock being indexed. A subtype of SciMLBase.AbstractClock

• idx::Any: The subset of indexes being referred to. This can be an integer, an array of integers, a range or Colon() to refer to all the points that the clock ticked.

Base.getindex(clock::AbstractClock, idx) -> IndexedClock

Select one or more tick indices from clock without resolving them to times.

Arguments

• clock: A SciML clock whose ticks will be selected.
• idx: An integer, integer collection, range, or Colon() selector.

Returns

• IndexedClock: A lazy clock/index pair. A solution resolves the pair to concrete independent-variable values when it is interpolated.

Example

indexed_clock = Clock(0.1)[2:4]
indexed_clock.idx

canonicalize_indexed_clock(
    ic::SciMLBase.IndexedClock,
    sol::SciMLBase.AbstractTimeseriesSolution
) -> Any

Convert an indexed clock reference into concrete independent-variable values for a saved time-series solution.

IndexedClock stores a clock and one or more tick indices, but the actual tick times depend on the solve. Periodic clocks are reconstructed from the problem start time and tick interval, solver-step clocks read the matching discrete time series stored on the solution, and continuous clocks index directly into sol.t. Unsupported clock types throw an error.