From 992d669fe11d302912bccfba068f265817a2ab43 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 04:12:24 +0000 Subject: [PATCH 1/4] Initial plan From fbbb1e55b8396c6f12bb33ad5467497ee26866c4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 04:17:55 +0000 Subject: [PATCH 2/4] Implement growth-based velocity model with configurable parameters Co-authored-by: SomeRandmGuyy <127457986+SomeRandmGuyy@users.noreply.github.com> --- .../continuum/terminal_velocity.py | 97 +++++++++++++++++-- 1 file changed, 90 insertions(+), 7 deletions(-) diff --git a/src/fsl_continuum/continuum/terminal_velocity.py b/src/fsl_continuum/continuum/terminal_velocity.py index 54f0c49..af946f9 100644 --- a/src/fsl_continuum/continuum/terminal_velocity.py +++ b/src/fsl_continuum/continuum/terminal_velocity.py @@ -2,6 +2,12 @@ Terminal Velocity Flow state optimization and terminal velocity calculations. + +Velocity Model: +- Velocity increases with uptime (building momentum) +- Flow state provides a velocity multiplier +- Configurable acceleration and max velocity +- Intuitive: higher values = better performance """ import time @@ -9,12 +15,33 @@ class TerminalVelocity: - """Terminal Velocity optimization class.""" + """Terminal Velocity optimization class. + + The velocity calculation uses a growth model where: + - Base velocity grows with uptime (momentum building) + - Flow state applies a multiplier to velocity + - Configurable acceleration factor and velocity cap + - Higher values indicate better/faster performance + """ + + # Default configuration + DEFAULT_ACCELERATION = 1.0 # Base acceleration factor + DEFAULT_MAX_VELOCITY = 100.0 # Maximum velocity cap + FLOW_STATE_MULTIPLIER = 1.5 # Velocity boost when in flow state + BASE_VELOCITY = 1.0 # Starting velocity - def __init__(self): + def __init__(self, acceleration: float = None, max_velocity: float = None): + """Initialize Terminal Velocity with optional configuration. + + Args: + acceleration: Acceleration factor (higher = faster velocity growth) + max_velocity: Maximum velocity cap (prevents unbounded growth) + """ self.flow_state = False self.metrics = {} self.start_time = time.time() + self.acceleration = acceleration if acceleration is not None else self.DEFAULT_ACCELERATION + self.max_velocity = max_velocity if max_velocity is not None else self.DEFAULT_MAX_VELOCITY def enter_flow_state(self): """Enter flow state.""" @@ -30,10 +57,28 @@ def exit_flow_state(self): self.metrics['last_flow_duration'] = duration def get_velocity(self) -> float: - """Calculate terminal velocity.""" - if not self.start_time: - return 0.0 - return 1.0 / (time.time() - self.start_time) if time.time() > self.start_time else 0.0 + """Calculate terminal velocity. + + Uses a growth-based model where velocity increases with uptime. + Formula: velocity = BASE + (uptime * acceleration) * flow_multiplier + + Returns: + Current velocity (higher = better performance) + """ + uptime = time.time() - self.start_time + + # Calculate base velocity with acceleration + # Velocity grows linearly with uptime and acceleration factor + velocity = self.BASE_VELOCITY + (uptime * self.acceleration) + + # Apply flow state multiplier if in flow state + if self.flow_state: + velocity *= self.FLOW_STATE_MULTIPLIER + + # Cap at maximum velocity + velocity = min(velocity, self.max_velocity) + + return velocity def get_status(self) -> Dict[str, Any]: """Get current status.""" @@ -41,5 +86,43 @@ def get_status(self) -> Dict[str, Any]: 'flow_state': self.flow_state, 'velocity': self.get_velocity(), 'metrics': self.metrics, - 'uptime': time.time() - self.start_time + 'uptime': time.time() - self.start_time, + 'config': { + 'acceleration': self.acceleration, + 'max_velocity': self.max_velocity, + 'flow_multiplier': self.FLOW_STATE_MULTIPLIER + } + } + + def set_acceleration(self, acceleration: float) -> None: + """Update acceleration factor for velocity growth. + + Args: + acceleration: New acceleration factor (higher = faster growth) + """ + if acceleration < 0: + raise ValueError("Acceleration must be non-negative") + self.acceleration = acceleration + + def set_max_velocity(self, max_velocity: float) -> None: + """Update maximum velocity cap. + + Args: + max_velocity: New maximum velocity cap + """ + if max_velocity <= 0: + raise ValueError("Max velocity must be positive") + self.max_velocity = max_velocity + + def get_config(self) -> Dict[str, float]: + """Get current velocity configuration. + + Returns: + Dictionary with acceleration, max_velocity, and flow_multiplier + """ + return { + 'acceleration': self.acceleration, + 'max_velocity': self.max_velocity, + 'flow_multiplier': self.FLOW_STATE_MULTIPLIER, + 'base_velocity': self.BASE_VELOCITY } From db794d6aa4d672585cca33f4dc39b4cda2f530be Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 04:19:08 +0000 Subject: [PATCH 3/4] Add comprehensive documentation for new velocity model Co-authored-by: SomeRandmGuyy <127457986+SomeRandmGuyy@users.noreply.github.com> --- .../terminal-velocity-model.md | 219 ++++++++++++++++++ .../terminal-velocity-quickref.md | 60 +++++ 2 files changed, 279 insertions(+) create mode 100644 docs/0003-architecture/terminal-velocity-model.md create mode 100644 docs/0003-architecture/terminal-velocity-quickref.md diff --git a/docs/0003-architecture/terminal-velocity-model.md b/docs/0003-architecture/terminal-velocity-model.md new file mode 100644 index 0000000..16ae7b8 --- /dev/null +++ b/docs/0003-architecture/terminal-velocity-model.md @@ -0,0 +1,219 @@ +# Terminal Velocity Model + +## Overview + +The Terminal Velocity system in FSL Continuum uses a **growth-based model** where velocity increases over time, representing momentum building as the system operates continuously. This design is intuitive: **higher velocity values indicate better performance**. + +## Key Concepts + +### Growth-Based Velocity + +Unlike traditional models where velocity decreases over time (inverse relationship), FSL Continuum's velocity **increases** with uptime: + +``` +velocity = BASE_VELOCITY + (uptime * acceleration) +``` + +This represents: +- **Momentum Building**: Longer runtime = higher velocity +- **Continuous Improvement**: System gets faster as it maintains state +- **Intuitive Metrics**: Higher numbers = better performance + +### Flow State Multiplier + +When the system enters "flow state" (optimal operation mode), velocity receives a **1.5x multiplier**: + +``` +if in_flow_state: + velocity *= 1.5 +``` + +This represents the productivity boost from uninterrupted, focused work. + +## Configuration Parameters + +### Acceleration Factor + +Controls how quickly velocity grows over time: + +```python +# Slow growth (0.5x) +tv = TerminalVelocity(acceleration=0.5) + +# Normal growth (1.0x - default) +tv = TerminalVelocity() + +# Fast growth (2.0x) +tv = TerminalVelocity(acceleration=2.0) +``` + +**Use cases:** +- **Low acceleration (0.1-0.5)**: Long-running services that need stable velocity +- **Normal acceleration (1.0)**: Standard CI/CD pipelines +- **High acceleration (2.0-10.0)**: Short-lived tasks that need quick ramp-up + +### Maximum Velocity Cap + +Prevents unbounded growth by capping velocity at a maximum value: + +```python +# Cap at 50 +tv = TerminalVelocity(max_velocity=50.0) + +# Cap at 100 (default) +tv = TerminalVelocity() + +# Cap at 500 (for high-performance scenarios) +tv = TerminalVelocity(max_velocity=500.0) +``` + +**Use cases:** +- **Low cap (10-50)**: Resource-constrained environments +- **Normal cap (100)**: Standard deployments +- **High cap (200-1000)**: High-performance computing, real-time systems + +## API Reference + +### Initialization + +```python +from fsl_continuum.continuum.terminal_velocity import TerminalVelocity + +# Use defaults +tv = TerminalVelocity() + +# Custom configuration +tv = TerminalVelocity( + acceleration=2.0, # Faster velocity growth + max_velocity=200.0 # Higher velocity cap +) +``` + +### Getting Velocity + +```python +# Get current velocity +velocity = tv.get_velocity() +print(f"Current velocity: {velocity}") + +# Get full status including configuration +status = tv.get_status() +print(f"Velocity: {status['velocity']}") +print(f"Uptime: {status['uptime']}") +print(f"Config: {status['config']}") +``` + +### Flow State Management + +```python +# Enter flow state (1.5x velocity boost) +tv.enter_flow_state() + +# Exit flow state +tv.exit_flow_state() +``` + +### Runtime Configuration + +```python +# Update acceleration factor +tv.set_acceleration(5.0) + +# Update max velocity cap +tv.set_max_velocity(300.0) + +# Get current configuration +config = tv.get_config() +print(f"Acceleration: {config['acceleration']}") +print(f"Max velocity: {config['max_velocity']}") +``` + +## Example Scenarios + +### Scenario 1: CI/CD Pipeline + +```python +# Standard CI/CD with normal acceleration +tv = TerminalVelocity(acceleration=1.0, max_velocity=100.0) + +# Start pipeline +tv.enter_flow_state() # Enter flow for focused execution + +# After 10 seconds of uptime +# velocity ≈ 1.0 + (10 * 1.0) = 11.0 +# With flow state: 11.0 * 1.5 = 16.5 +``` + +### Scenario 2: Long-Running Service + +```python +# Stable, long-running service with slow growth +tv = TerminalVelocity(acceleration=0.1, max_velocity=50.0) + +# After 100 seconds of uptime +# velocity ≈ 1.0 + (100 * 0.1) = 11.0 +# Eventually caps at 50.0 for stability +``` + +### Scenario 3: High-Performance Batch Job + +```python +# Fast ramp-up for batch processing +tv = TerminalVelocity(acceleration=10.0, max_velocity=500.0) + +# After 5 seconds +# velocity ≈ 1.0 + (5 * 10.0) = 51.0 +# Reaches high velocity quickly +``` + +## Velocity Interpretation + +| Velocity Range | Interpretation | Typical Scenario | +|----------------|----------------|------------------| +| 0-10 | Starting up | Fresh start, < 10s uptime | +| 10-50 | Building momentum | Normal operation, stabilizing | +| 50-100 | High velocity | Sustained operation, flow state | +| 100+ | Terminal velocity | Maximum performance, capped | + +## Migration from Legacy Model + +The legacy model used inverse velocity calculation: + +```python +# OLD: velocity = 1.0 / uptime (decreases over time) +# NEW: velocity = base + (uptime * acceleration) (increases over time) +``` + +**Key differences:** +1. **Direction**: New model increases (not decreases) with time +2. **Intuitive**: Higher values = better performance +3. **Configurable**: Acceleration and cap are adjustable +4. **Flow state**: Explicit multiplier for flow state boost + +**Backward compatibility**: The new model maintains the same API (`get_velocity()`), so existing code continues to work, but the semantics have changed to be more intuitive. + +## Best Practices + +1. **Choose appropriate acceleration** based on your use case: + - Short tasks: Higher acceleration (2.0-10.0) + - Long services: Lower acceleration (0.1-0.5) + +2. **Set realistic velocity caps** to prevent resource exhaustion: + - Development: 100 (default) + - Production: 200-500 + - Critical systems: Custom based on monitoring + +3. **Use flow state** for focused execution: + - Enter flow state during critical operations + - Exit flow state during idle/maintenance periods + +4. **Monitor velocity trends** over time: + - Velocity should grow steadily + - Sudden drops indicate issues + - Caps being hit indicate optimization opportunities + +## Related Documentation + +- [System Architecture](0001-system-architecture.md) +- [State Management](../../src/fsl_continuum/continuum/state_management.py) +- [Metrics Collection](../../src/fsl_continuum/continuum/metrics.py) diff --git a/docs/0003-architecture/terminal-velocity-quickref.md b/docs/0003-architecture/terminal-velocity-quickref.md new file mode 100644 index 0000000..e5e574c --- /dev/null +++ b/docs/0003-architecture/terminal-velocity-quickref.md @@ -0,0 +1,60 @@ +# Terminal Velocity Quick Reference + +## Basic Usage + +```python +from fsl_continuum.continuum.terminal_velocity import TerminalVelocity + +# Create instance +tv = TerminalVelocity() + +# Get velocity (increases over time) +velocity = tv.get_velocity() + +# Enter flow state (1.5x boost) +tv.enter_flow_state() + +# Exit flow state +tv.exit_flow_state() +``` + +## Configuration + +```python +# Custom acceleration and max velocity +tv = TerminalVelocity( + acceleration=2.0, # Faster growth + max_velocity=200.0 # Higher cap +) + +# Change at runtime +tv.set_acceleration(5.0) +tv.set_max_velocity(300.0) + +# View configuration +config = tv.get_config() +``` + +## Velocity Formula + +``` +velocity = BASE_VELOCITY + (uptime * acceleration) + +If in flow state: + velocity *= 1.5 + +Final velocity = min(velocity, max_velocity) +``` + +## Default Values + +- `BASE_VELOCITY`: 1.0 +- `DEFAULT_ACCELERATION`: 1.0 +- `DEFAULT_MAX_VELOCITY`: 100.0 +- `FLOW_STATE_MULTIPLIER`: 1.5 + +## Key Principle + +**Higher velocity = Better performance** + +Velocity increases as the system runs longer, representing momentum building. This is intuitive and easy to understand. From 6a7955bf10c97d79d16b0ea04e8a909a425df919 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 07:12:37 +0000 Subject: [PATCH 4/4] Fix formula documentation to accurately reflect flow state multiplier application Co-authored-by: SomeRandmGuyy <127457986+SomeRandmGuyy@users.noreply.github.com> --- src/fsl_continuum/continuum/terminal_velocity.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fsl_continuum/continuum/terminal_velocity.py b/src/fsl_continuum/continuum/terminal_velocity.py index af946f9..76c3751 100644 --- a/src/fsl_continuum/continuum/terminal_velocity.py +++ b/src/fsl_continuum/continuum/terminal_velocity.py @@ -60,7 +60,7 @@ def get_velocity(self) -> float: """Calculate terminal velocity. Uses a growth-based model where velocity increases with uptime. - Formula: velocity = BASE + (uptime * acceleration) * flow_multiplier + Formula: velocity = (BASE + uptime * acceleration) * flow_multiplier (when in flow state) Returns: Current velocity (higher = better performance)