Update readme and the machine clock docs

Author: wouterwln

README.md

@@ -13,103 +13,38 @@ A Julia package for scheduling tasks in simulation environments with precise tim
 ```julia
 using EnvironmentEngine
 
-# Schedule a task every 20ms
-every(20ms) do dt
-    println("Task executed")
-end
-
-# Process scheduled jobs
-update!()
-```
-
-This will schedule a task to run every 20 milliseconds. Whenever `update!` is called, `EnvironmentEngine` will sync the clock with the real time and execute the scheduled tasks. A common pattern is the following:
-
-```julia
-using EnvironmentEngine
-
-# Schedule a task every 200ms
+# Schedule a task every 200 milliseconds
 every(200ms) do dt
     println("Task executed at $(now(global_clock()))")
 end
 
-# Process scheduled jobs
-for_next(5s) do
+# Run the scheduler for 1 second
+for_next(1s) do
     update!()
 end
 ```
 
-## Features
-
-- **Timed Jobs**: Execute tasks at regular intervals
-- **ASAP Jobs**: Execute tasks as soon as possible  
-- **Event Jobs**: Execute tasks when data arrives on channels
-- **Multiple Clocks**: Machine time or controllable virtual time
-- **Flexible Scheduling**: Global or custom schedulers
-
 ## Installation
 
 ```julia
 using Pkg
 Pkg.add("EnvironmentEngine")
 ```
 
-## Basic Example
-
-```julia
-using EnvironmentEngine
-
-# Schedule different types of jobs
-every(3ms) do dt
-    println("Timed job: $(now(global_clock()))")
-    # Irregularly send events
-    if rand() < 0.5
-        put!(events, "Event $(rand())")
-    end
-end
-
-# Run this as often and soon as possible
-every(asap) do
-    println("ASAP job executed")
-end
-
-# Create a channel for event-driven jobs
-events = Channel{String}(Inf)
-
-# Run this when an event is received
-every(events) do event
-    println("Event received: $event")
-end
-
-# Simulate time progression
-for_next(20ms) do
-    update!()
-end
-```
-
-## Clock Types
-
-### Machine Clock
-Uses system time:
-
-```julia
-clock = MachineClock()
-println(now(clock))  # Current system time
-```
-
-### Virtual Clock
-Controlled time for simulations:
+## Features
 
-```julia
-clock = VirtualClock()
-set_time!(clock, 0.0s)
-advance_time!(clock, 50ms)
-println(now(clock))  # 0.05 s
-```
+- **Timed Jobs**: Execute tasks at regular intervals
+- **ASAP Jobs**: Execute tasks as soon as possible  
+- **Event Jobs**: Execute tasks when data arrives on channels
+- **Multiple Clocks**: Machine time or controllable virtual time
+- **Flexible Scheduling**: Global or custom schedulers
+- **Multi-threading**: Parallel job execution
 
 ## Documentation
 
-- [Getting Started](https://lazydynamics.github.io/EnvironmentEngine.jl/dev/getting_started/) - Quick setup and basic examples
-- [API Reference](https://lazydynamics.github.io/EnvironmentEngine.jl/dev/api/) - Complete function documentation
+- [Getting Started](https://lazydynamics.github.io/EnvironmentEngine.jl/dev/) - Quick setup and basic examples
+- [Tutorials](https://lazydynamics.github.io/EnvironmentEngine.jl/dev/tutorials/) - Step-by-step learning guide
+- [API Reference](https://lazydynamics.github.io/EnvironmentEngine.jl/dev/user_guide/api_reference/) - Complete function documentation
 
 ## License
 

docs/src/tutorials/clocks_and_time.md

@@ -35,6 +35,21 @@ When created, the `MachineClock` is paused by default, and can be resumed and pa
 EnvironmentEngine.MachineClock
 ```
 
+#### Stretch Factor
+The `MachineClock` has a stretch factor, which is a factor by which the time is stretched. This is useful for building real-time applications, where the time is stretched to make the simulation run faster or slower than the real time. The stretch factor is set to 1.0 by default. If the stretch factor is greater than 1.0, the time will progress faster than the real time. For example, if the stretch factor is 2.0, the time will progress twice as fast as real time. You can set the stretch factor when creating the clock:
+
+```@example clocks-machine-fast
+using EnvironmentEngine
+
+clock = MachineClock(stretch_factor = 2.0)
+resume!(clock)
+sleep(1.0)
+pause!(clock)
+println(now(clock))  # Current system time, 2.0 seconds
+```
+
+This is especially useful for debugging, and when you want to test if your agent has more/less computational resources available than on the machine you are running the simulation on.
+
 **Use MachineClock when:**
 - Building real-time applications
 - You want to sync with wall clock time