DR_EVT Logo

Getting Started

  • Quick Start Guide - DR_EVT Backfilling Scheduler
    • Overview
    • Features
    • Build Instructions
      • Prerequisites
      • Setup (One-Time)
      • Dependencies
    • Usage
      • Basic Example
      • All Options
      • Examples
    • Output
    • Trace File Format
    • Understanding the Algorithms
      • EASY Backfilling
      • Conservative Backfilling
      • Priority Policies
      • Run Time Modes
    • Troubleshooting
      • CMake can’t find Boost
      • Build fails during Protobuf download
      • “No such file or directory” errors
    • Development
      • Running Tests
      • Rebuilding After Code Changes
      • Clean Build
    • Documentation
    • Citation
    • License
    • Support
    • What’s Next?
  • Installation
    • Prerequisites
      • Required
      • Optional (for full features)
      • Protocol Buffers & gRPC Details
    • Building from Source
      • Quick Build
      • CMake Configuration Options
    • Installation
    • Python Environment
    • Verification
    • Troubleshooting
      • CMake can’t find Boost
      • Build fails during Protobuf/gRPC download
      • gRPC/Protobuf version mismatch
      • Python bindings fail to build
      • MPI not found (optional dependency)
      • CMake version too old
      • Compiler not C++17 compatible
      • “No such file or directory” errors
    • Next Steps
  • Tutorial: Your First Simulation
    • Step 1: Prepare a Test Trace
    • Step 2: Run the Simulation
    • Step 3: Understand the Output
    • Step 4: Analyze Results
    • Step 5: Visualize (Optional)
    • Understanding Backfilling
    • Common Variations
      • Without Backfilling (Pure FCFS)
      • Different Priority Policies
    • Next Steps
    • Exercises

User Guide

  • DR_EVT User Guide
    • Introduction
    • Quick Start
      • Basic Usage
      • Example Output
    • Trace File Formats
      • Simple Format (Recommended for Testing)
      • Lassen Format (LLNL HPC Traces)
    • Timestamp Formats
      • Epoch (Unix Time)
      • ISO (Human-Readable)
    • Scheduler Policies
      • Backfill Policies
        • EASY Backfill (Default)
        • Conservative Backfill
      • Priority Policies
        • FCFS (First-Come-First-Served) - Default
        • SJF (Shortest-Job-First)
        • LJF (Longest-Job-First)
      • Run Time Modes
        • actual (Default)
        • distribution
        • limit (Debug Mode)
    • Command-Line Options
      • Required Options
      • Input/Output Options
      • Trace Format Options
      • Scheduler Options
      • Job Store Options
      • Run Time Options
      • Other Options
    • Usage Examples
      • Example 1: Basic Test
      • Example 2: Real HPC Trace
      • Example 3: Policy Comparison
      • Example 4: Priority Policy Study
      • Example 5: Run Time Estimation Impact
    • Understanding Output
      • Job Events
      • Backfill Messages
      • Statistics
    • Common Workflows
      • 1. Create Test Trace
      • 2. Run Simulation
      • 3. Analyze Results
      • 4. Compare Policies
    • Troubleshooting
      • Problem: “Loaded 0 jobs from trace”
      • Problem: “Job event times are incorrect”
      • Problem: “Resource over-subscription”
      • Problem: Very long simulation time
    • Performance Tips
      • For Large Traces
      • Expected Performance
    • Advanced Topics
      • Creating Custom Traces
      • Batch Processing
      • Extracting Metrics
    • Best Practices
    • References
    • Support
  • Command-Line Options
    • Basic Usage
    • Input/Output Options
      • -i, --infile FILENAME
      • -L, --infile_list FILENAME
      • -o, --outfile FILENAME
      • -R, --resource_trace FILENAME
    • System Configuration
      • -n, --total_nodes COUNT
    • Scheduling Policies
      • -b, --backfill_policy POLICY
      • -p, --priority_policy POLICY
      • -q, --queue_impl IMPLEMENTATION
      • -Q, --block_size SIZE
      • -A, --wait_queue_capacity SIZE
      • -G, --wait_queue_overflow {abort|grow}
      • -K, --job_store_capacity SIZE
      • -W, --job_store_overflow {abort|grow}
      • -m, --check_memory_pressure FRACTION
      • -H, --resource_history_capacity SIZE
    • Trace Format Options
      • -f, --trace_format FORMAT
      • -T, --timestamp_format FORMAT
      • -z, --timezone TIMEZONE
    • Simulation Mode Options
      • -r, --run_time_mode MODE
      • -D, --run_time_distribution TYPE
      • -S, --run_time_scale FACTOR
      • -V, --run_time_stddev FACTOR
    • Limit Options
      • -j, --max_jobs COUNT
      • -t, --max_time TIME
      • -s, --seed VALUE
    • Configuration File Option
      • -c, --config CONFIGFILE
    • Debug Options
      • -v, --verbose
      • -h, --help
    • Common Usage Patterns
      • Basic Simulation
      • Simulation with Resource Tracking
      • With Real HPC Trace
      • Realistic Simulation with Actual Run Times
      • Different Scheduling Policies
      • Distribution-Based Run Time Simulation
      • Using Config File
    • See Also
  • Trace File Format Options
    • Command-Line Options
      • Trace Format
      • Timestamp Format
      • Timezone
    • Usage Examples
      • Simple Test Trace with Epoch Times
      • Simple Trace with ISO Timestamps
      • Lassen Format (Default)
    • Simple Format CSV Structure
      • Simulation Mode (scheduler computes start/end times)
      • Replay Mode, With Epoch Timestamps
      • Replay Mode, With ISO Timestamps
    • Column Descriptions
      • Simple Format Columns
      • Lassen Format
    • Testing
    • See Also
  • Protocol Buffer Configuration
    • Why Use Protobuf Config?
    • Configuration File Format
      • Basic Example
      • Complete Example
    • Configuration Options Reference
      • Input/Output Parameters
      • System Configuration
      • Scheduling Policies
      • Trace Format
      • Simulation Limits
      • Run Time Simulation
      • Output Options
    • Command-Line Override
    • Common Configurations
      • Production Replay
      • What-If Analysis
      • Capacity Planning
      • Performance Testing
    • Protocol Buffer Schema
    • Validation
    • See Also
  • gRPC Client/Server Setup
    • Architecture
    • Building with gRPC Support
    • Running the Server
    • Running the Client
    • Network Configuration
      • Firewall rules
      • SSH tunneling
    • Troubleshooting
      • Connection refused
      • Large trace, high memory use
    • See Also

Algorithm & Testing

  • Backfilling Algorithms - Reference Implementation
    • Table of Contents
  • EASY Backfilling
    • Overview
    • Visual Overview
    • Data Structures
      • Wait Queue
      • Running Jobs
      • System State
    • Algorithm
      • Scheduling Events
      • Scheduling Logic (per event)
    • Step 1: Process FCFS Head
    • Step 2: Calculate Reservation
      • Reservation Timeline Example
    • Step 3: Try Backfilling
      • Backfilling Example
    • Early Completion Handling
      • Planning (Pessimistic)
      • Execution (Optimistic)
      • Example
    • Edge Cases & Clarifications
      • 1. FCFS Head Can Fit
      • 2. Multiple Running Jobs
      • 3. Backfill Time Window
      • 4. What if No Jobs Running?
    • Complete Example Trace
    • Questions to Verify Understanding
      • Q1: Job can fit but would outlast running job. Start it?
      • Q2: Reservation uses time_limit or actual_runtime?
      • Q3: Backfill check: completion < reservation or <=?
      • Q4: Multiple running jobs - which end time matters?
    • Reference
  • Conservative Backfilling
    • Overview
      • Key Difference from EASY
    • Visual Overview
    • Algorithm
      • Step 1: Process FCFS Head (Same as EASY)
    • Step 2: Calculate Reservations (Shadow Times) for ALL Waiting Jobs
    • Step 3: Conservative Backfilling
    • Conservative Backfilling Example
      • Scenario
      • EASY Decision
      • CONSERVATIVE Decision
    • Implementation Considerations
      • Effective Running Jobs
      • Complexity
    • Performance Comparison
    • When to Use Conservative Backfilling
    • Reference
  • Comparison
    • Summary Table
    • Algorithm Choice Decision Tree
    • DR_EVT Implementation
  • Testing Guide for DR_EVT Scheduler
    • Overview
    • Quick Navigation
    • How to Run Tests
      • Installed Test Binaries
    • Comprehensive Tests
      • Tier 1-2: FCFS & Basic Backfilling (10 tests)
      • Tier 3-4: Event Timing & Competition (9 tests)
      • Tier 5: Fragmentation & Sustained Load (5 tests)
      • Tier 6-9: Completion Interactions & Backfill Edge Cases (10 tests)
    • Unit Tests
    • Feature Tests
    • Scale Tests
    • Replay Tests
    • Resource History Tests
    • Job Store Tests
    • Append-Job Tests
    • Progressive Loading Tests
    • Streaming API Tests
    • Configuration Tests
    • Queue Implementation Testing
    • Column Alias Tests
    • Run Time Mode Tests
    • Test Summary
    • Test File Formats
      • Input Trace (.csv)
      • Expected Job Output (.expected_output.csv)
      • Expected Resource Timeline (.expected_resources.csv)
      • Answer File (.answer.json)
    • Generating Expected Outputs
    • Adding New Tests
    • Common Test Patterns
      • 3-Job Backfill Pattern
      • Multiple Running Jobs Pattern
      • Early Completion Pattern
    • Troubleshooting
      • Test Fails: Schedule Mismatch
      • All Tests Pass but Behavior Seems Wrong
    • Conservative Backfilling Tests
      • Algorithm Comparison
      • Test 1: Behavioral Correctness (EASY vs CONSERVATIVE)
      • Test 2: Implementation Equivalence (C++ vs Python)
      • Conservative Backfilling Implementation
      • Test Data Files
    • References
    • Key Principles

APIs

  • Streaming API Documentation
    • Overview
    • Core Concepts
      • Batch Mode vs Streaming Mode
      • Time Advancement
    • API Methods
      • initialize_trace(max_jobs = 0)
      • append_job(submit_time, num_nodes, queue, limit_time)
      • append_jobs(requests)
      • advance_to(target_time)
      • run_until_exclusive(target_time)
      • Monitoring Methods
    • Usage Patterns
      • Pattern 1: Submit All, Then Run
      • Pattern 2: Incremental Job Submission (genuinely new jobs)
      • Pattern 3: Time-Stepped Simulation
      • Pattern 4: Event-Driven Simulation
    • Complete Example
    • Implementation Details
      • Scheduling Decisions
      • Event Processing
      • Critical Fix
    • Testing
      • test_append_job_api
      • test_batch_vs_streaming
      • test_mpi_streaming (requires MPI)
    • Limitations
    • See Also
  • DR_EVT Python API
    • Overview
    • Installation
      • Prerequisites
      • Build from Source
      • Verify Installation
    • Quick Example
    • Configuration Parameters
      • Input/Output
      • System Configuration
      • Trace Format
      • Scheduling Policies
      • Run Time Mode (Simulation)
      • Output Control
    • Missing Parameters in Python Bindings
      • Currently Exposed (9 parameters)
      • Missing from Python Bindings (17 parameters)
      • Also Missing: Simulation Methods (not parameters)
      • Workarounds
      • Impact on Use Cases
      • Recommendation
    • Enumerations
      • BackfillPolicy
      • PriorityPolicy
      • RunTimeMode
    • Streaming API
      • Job Submission
      • Time Advancement
    • Monitoring API
      • Resource Status
      • Queue Status
      • Comprehensive Statistics
    • Batch Mode API
    • Use Cases
      • 1. Online Admission Control
      • 2. Policy Comparison
      • 3. Real-time Dashboard
      • 4. Custom Scheduler Integration
      • 5. What-If Simulation
    • Performance
    • Testing
    • Examples
    • Troubleshooting
      • ModuleNotFoundError: No module named ‘dr_evt’
      • Trace fails to load
      • Statistics are zero
      • AttributeError: ‘SimParams’ object has no attribute ‘X’
    • API Reference
    • Comparison: Python vs C++ API
    • Contributing
    • See Also
  • gRPC Client/Server Guide
    • Overview
    • Building
      • Dependency resolution
    • The service definition
    • Running the server and client
    • Multi-client/multi-server: the MPI test harness
      • Building and running
    • Testing

Development

  • Developer Documentation
    • What Goes Here
      • design-decisions/
  • Terminology - Clarification
    • The Confusion
    • Correct Terminology
      • 1. Reference Implementation
      • 2. Run Time Mode
      • 3. Reference Implementation vs Expected Output
    • File Naming Convention
    • Code/Script Names
    • Examples
      • ✅ Clear Usage
    • Summary Table
    • Migration Notes
    • Why This Matters
    • Verification Terminology
  • Block Queue Wait Queue Implementation
    • Quick Summary
    • Performance Results (10K jobs, 500 nodes)
    • The U-Shaped Curve
    • Architecture
      • 3-Index Design
      • Key API
      • Optimizations
      • What Didn’t Help
    • Why Deque Still Wins
    • Testing
      • Quick Test
      • Comprehensive Testing
    • Usage
      • Command-Line Options
      • Factory Pattern
    • Design Rationale
      • Block Size Selection
      • Why Not Deque + Metadata?
      • Why Not Replace Multi-Index?
    • Implementation Details
      • Template-Based Block Size
      • Block Metadata
      • Backfill Search Algorithm
    • Lessons Learned
    • Recommendations
      • Production
      • Research/Testing
      • Future Work
    • Files
      • Core Implementation
      • Tests
      • Documentation
    • References
  • Block Queue Testing Guide
    • Overview
    • Test Files
      • 1. Unit Tests
      • 2. Integration & Correctness Tests
      • 3. Block Size Performance Comparison
    • Test Traces
      • Unit Test Traces
      • Feature Test Traces
      • Scale Test Traces
      • Comprehensive Test Traces
    • Generating Test Traces
    • Key Findings
      • Correctness
      • Performance
      • Bottleneck Analysis
    • Recommendation
    • Running All Tests
    • Continuous Integration
  • Circular Buffer Wait Queue Implementation
    • Quick Summary
    • Performance Results (10K jobs, 500 nodes, average of 3 trials)
    • Why It’s Faster Than Deque
    • Why It’s Faster Than Block Queue
    • The Fixed-Capacity Trade-off
    • Testing
      • Quick Test
      • Manually Testing Capacity/Overflow
    • Usage
      • Command-Line Options
      • Factory Pattern
      • Also Reachable via Protobuf
    • Recommendations
      • Production
      • Research/Testing
    • Files
      • Core Implementation
      • Tests
      • Protobuf Wiring
    • References
  • ReadTheDocs Setup Guide
    • Overview
    • Configuration Files
      • .readthedocs.yaml (Repository Root)
      • docs/conf.py
      • docs/requirements.txt
    • Documentation Structure
    • Building Locally
    • ReadTheDocs Project Setup
      • Initial Setup (One-Time)
      • Webhook (Automatic)
      • Build Status
      • Badges
    • Version Management
      • Multiple Versions
      • Activating Versions
    • Customization
      • Theme Options (docs/conf.py)
      • Custom CSS/JS
      • Logo and Favicon
    • Troubleshooting
      • Build Failures
      • Warning: Broken Cross-References
      • Local Build vs ReadTheDocs
    • Maintenance
      • Regular Tasks
      • Documentation Updates
    • Migration Notes
      • Changes Made
      • No Breaking Changes
    • References
  • Design Decisions
    • Documents
    • Purpose
    • Adding New Decisions
  • Simulation vs Replay Modes - Design
    • Problem Statement
    • Design Goals
    • Trace Format Specifications
      • Replay Mode Format
      • Simulation Mode Format
    • Duration Determination in Simulation Mode
      • Mode 1: Actual (--run_time_mode actual)
      • Mode 2: Limit (--run_time_mode limit)
      • Mode 3: Distribution (--run_time_mode distribution)
    • Data Structure Changes
      • Job_Record Modifications
      • Data_Columns Modifications
    • Simulation Logic Updates
      • Initialization
      • Duration Determination
      • Job Completion
    • Command Line Interface
      • New Parameters
      • Example Usage
    • Data Flow
      • Replay Mode
      • Simulation Mode
    • Validation
      • Invariants
      • Test Cases
    • Implementation Plan
    • Benefits
    • Migration Path
  • Timezone Offset Support Design
    • Status: Implementation Complete (Untested)
    • Overview
    • Design Principles
    • Implementation Details
      • 1. Parse Timezone Offsets (✅ IMPLEMENTED)
      • 2. Timezone Metadata Storage (✅ IMPLEMENTED)
      • 3. Integrated Parsing (✅ IMPLEMENTED)
      • 4. Output Formatting (⚠️ TODO)
    • Examples
      • Multi-Facility Trace
    • Benefits
    • Testing Plan
    • Remaining Work
    • Files Modified
    • Build Issues
    • Next Steps
  • Trace as a self-contained, streaming-ready state container
DR_EVT
  • Search

© Copyright 2024-2026, Lawrence Livermore National Laboratory.

Built with Sphinx using a theme provided by Read the Docs.