Add documentation for undocumented SciMLBase API components

docs/pages.jl

@@ -10,6 +10,7 @@ pages = [
         "interfaces/Solutions.md",
         "interfaces/Init_Solve.md",
         "interfaces/Ensembles.md",
+        "interfaces/ClockSystem.md",
         "interfaces/Common_Keywords.md",
         "interfaces/Differentiation.md",
         "interfaces/PDE.md"],

docs/src/interfaces/ClockSystem.md

@@ -0,0 +1,262 @@
+# Clock and Timing System
+
+SciMLBase provides a sophisticated clock and timing system for discrete-time models, hybrid systems, and event-driven simulations. This system enables precise control over when events occur and how different time domains interact within complex models.
+
+## Overview
+
+The clock system is designed to handle:
+- Discrete-time models with regular sampling
+- Event-driven systems with irregular timing
+- Hybrid continuous-discrete systems
+- Multi-rate systems with different time scales
+- Scheduled events and periodic triggers
+
+## Abstract Clock Types
+
+### Core Abstractions
+
+```julia
+abstract type TimeDomain end
+abstract type Clocks end
+```
+
+These form the foundation of the clock system:
+- `TimeDomain`: Represents different types of time domains (continuous, discrete, etc.)
+- `Clocks`: Base type for all clock implementations
+
+## Concrete Clock Types
+
+### ContinuousClock
+
+```julia
+ContinuousClock()
+```
+
+Represents continuous time domains where events can occur at any real-valued time instant. This is the default for continuous differential equations.
+
+### PeriodicClock
+
+```julia
+PeriodicClock(period)
+```
+
+Creates a clock that triggers at regular intervals.
+
+**Arguments:**
+- `period`: The time interval between clock ticks
+
+**Use Cases:**
+- Discrete-time control systems
+- Regular sampling of continuous signals
+- Periodic boundary conditions
+
+### SolverStepClock
+
+```julia
+SolverStepClock()
+```
+
+A clock that triggers at every solver step. This is useful for monitoring solver progress or implementing step-dependent logic.
+
+### EventClock
+
+```julia
+EventClock(condition, affect!)
+```
+
+A clock that triggers when a specified condition is met.
+
+**Arguments:**
+- `condition`: Function that returns true when the event should trigger
+- `affect!`: Function to execute when the event occurs
+
+**Use Cases:**
+- State-dependent events
+- Threshold crossing detection
+- Condition-based state changes
+
+## Clock Properties and Traits
+
+### Time Domain Classification
+
+```julia
+is_discrete_time_domain(clock)
+iscontinuous(clock)
+```
+
+- `is_discrete_time_domain`: Returns `true` if the clock operates in discrete time
+- `iscontinuous`: Returns `true` if the clock operates in continuous time
+
+### Clock Type Checking
+
+```julia
+isclock(obj)
+issolverstepclock(clock)
+```
+
+- `isclock`: Returns `true` if the object is a valid clock
+- `issolverstepclock`: Returns `true` if the clock triggers on solver steps
+
+## Indexed Clock System
+
+### IndexedClock
+
+```julia
+IndexedClock(base_clock, index)
+```
+
+Wraps a base clock with an index for use in multi-clock systems.
+
+**Arguments:**
+- `base_clock`: The underlying clock
+- `index`: Unique identifier for this clock instance
+
+### Clock Canonicalization
+
+```julia
+canonicalize_indexed_clock(clock)
+```
+
+Converts clocks to their canonical indexed form for consistent internal representation.
+
+## Usage Patterns
+
+### Simple Periodic Sampling
+
+```julia
+using SciMLBase
+
+# Create a periodic clock with 0.1 time unit intervals
+clock = PeriodicClock(0.1)
+
+# Use in a discrete problem
+function discrete_update!(u, p, t, clock)
+    if isclock(clock) && is_discrete_time_domain(clock)
+        u[1] = u[1] * 0.9  # Decay
+        u[2] = u[2] + sin(t)  # Periodic forcing
+    end
+end
+```
+
+### Event-Driven Systems
+
+```julia
+# Create an event clock that triggers when x > 1.0
+event_condition(u, t, integrator) = u[1] - 1.0
+event_affect!(integrator) = integrator.u[1] = 0.0
+
+event_clock = EventClock(event_condition, event_affect!)
+
+# Use with hybrid systems
+```
+
+### Multi-Rate Systems
+
+```julia
+# Different clocks for different subsystems
+fast_clock = PeriodicClock(0.01)    # Fast dynamics
+slow_clock = PeriodicClock(0.1)     # Slow dynamics
+event_clock = EventClock(condition, affect!)  # Event-driven
+
+# Indexed for system identification
+clocks = [
+    IndexedClock(fast_clock, 1),
+    IndexedClock(slow_clock, 2),
+    IndexedClock(event_clock, 3)
+]
+```
+
+### Solver Step Monitoring
+
+```julia
+# Monitor every solver step
+step_clock = SolverStepClock()
+
+function monitor_steps(integrator)
+    if issolverstepclock(step_clock)
+        println("Step: $(integrator.step), Time: $(integrator.t)")
+        # Log solution values, check convergence, etc.
+    end
+end
+```
+
+## Integration with Problem Types
+
+### Discrete Problems
+
+```julia
+using SciMLBase
+
+function discrete_dynamics!(u_next, u, p, t, clock)
+    # Clock-dependent discrete update
+    if is_discrete_time_domain(clock)
+        u_next[1] = p[1] * u[1] + p[2] * u[2]
+        u_next[2] = p[3] * u[1] + p[4] * u[2]
+    end
+end
+
+# Problem with explicit clock
+prob = DiscreteProblem(discrete_dynamics!, u0, tspan, p, 
+                      clock = PeriodicClock(0.1))
+```
+
+### Hybrid Systems
+
+```julia
+# Continuous dynamics with discrete events
+function hybrid_dynamics!(du, u, p, t)
+    du[1] = -u[1] + u[2]  # Continuous part
+    du[2] = -2*u[2] + u[1]
+end
+
+# Event clock for state jumps
+jump_condition(u, t, integrator) = u[1] - 2.0
+jump_affect!(integrator) = integrator.u[2] += 1.0
+
+hybrid_clock = EventClock(jump_condition, jump_affect!)
+```
+
+## Advanced Features
+
+### Clock Synchronization
+
+```julia
+# Synchronize multiple clocks
+function synchronize_clocks(clocks)
+    canonical_clocks = [canonicalize_indexed_clock(c) for c in clocks]
+    # Implementation depends on specific synchronization requirements
+    return canonical_clocks
+end
+```
+
+### Dynamic Clock Modification
+
+```julia
+# Dynamically change clock periods
+mutable struct AdaptiveClock <: Clocks
+    base_period::Float64
+    current_period::Float64
+    adaptation_rule::Function
+end
+
+function update_clock!(clock::AdaptiveClock, system_state)
+    clock.current_period = clock.adaptation_rule(system_state)
+end
+```
+
+## Performance Considerations
+
+- **Clock Overhead**: Frequent clock checks can impact performance; use appropriate clock types for your application
+- **Event Detection**: Event clocks require root-finding which can be computationally expensive
+- **Memory Usage**: Multiple clocks in large systems should be managed efficiently
+- **Synchronization**: Multi-clock systems may require careful synchronization for deterministic behavior
+
+## Best Practices
+
+1. **Choose Appropriate Clock Types**: Use `PeriodicClock` for regular sampling, `EventClock` for condition-based events
+2. **Minimize Clock Frequency**: Higher frequency clocks increase computational overhead
+3. **Index Clocks**: Use `IndexedClock` for systems with multiple clock domains
+4. **Test Clock Logic**: Verify clock behavior with simple test cases before complex integration
+5. **Monitor Performance**: Profile clock-dependent systems to ensure acceptable performance
+
+The clock system provides powerful tools for modeling complex temporal behavior in scientific simulations while maintaining the performance and reliability expected from the SciML ecosystem.

src/clock.jl

@@ -47,30 +47,60 @@ discrete-time systems that assume a fixed sample time, such as PID controllers a
 filters.
 """ SolverStepClock
 
+"""
+    isclock(clock)
+
+Returns `true` if the object is a valid clock type (specifically a `PeriodicClock`).
+This function is used for type checking in clock-dependent logic.
+"""
 isclock(c::Clocks.Type) = @match c begin
     PeriodicClock() => true
     _ => false
 end
 isclock(::TimeDomain) = false
 
+"""
+    issolverstepclock(clock)
+
+Returns `true` if the clock is a `SolverStepClock` that triggers at every solver step.
+This is useful for monitoring solver progress or implementing step-dependent logic.
+"""
 issolverstepclock(c::Clocks.Type) = @match c begin
     SolverStepClock() => true
     _ => false
 end
 issolverstepclock(::TimeDomain) = false
 
+"""
+    iscontinuous(clock)
+
+Returns `true` if the clock operates in continuous time (i.e., is a `ContinuousClock`).
+Continuous clocks allow events to occur at any real-valued time instant.
+"""
 iscontinuous(c::Clocks.Type) = @match c begin
     ContinuousClock() => true
     _ => false
 end
 iscontinuous(::TimeDomain) = false
 
+"""
+    iseventclock(clock)
+
+Returns `true` if the clock is an `EventClock` that triggers based on specific events.
+Event clocks are used for condition-based triggering in hybrid systems.
+"""
 iseventclock(c::Clocks.Type) = @match c begin
     EventClock() => true
     _ => false
 end
 iseventclock(::TimeDomain) = false
 
+"""
+    is_discrete_time_domain(clock)
+
+Returns `true` if the clock operates in discrete time (i.e., is not a continuous clock).
+Discrete time domains have specific sampling intervals or event-based triggering.
+"""
 is_discrete_time_domain(c::TimeDomain) = !iscontinuous(c)
 
 # workaround for https://github.com/Roger-luo/Moshi.jl/issues/43