.. _program_listing_file_examples_README.md:

Program Listing for File README.md
==================================

|exhale_lsh| :ref:`Return to documentation for file <file_examples_README.md>` (``examples/README.md``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS

.. code-block:: markdown

   # diffeq Examples
   
   This directory contains comprehensive examples demonstrating how to use the diffeq library for solving differential equations.
   
   ## Example Programs
   
   ### Core Integration Examples
   
   - **`working_integrators_demo.cpp`** - Demonstrates all working ODE integrators (RK4, RK23, RK45, BDF, LSODA)
   - **`rk4_integrator_usage.cpp`** - Basic RK4 integrator usage with various ODE systems
   - **`advanced_integrators_usage.cpp`** - Advanced integrator features and configurations
   - **`state_concept_usage.cpp`** - Shows how to use different state types (vectors, arrays, custom types)
   - **`std_async_integration_demo.cpp`** - Direct use of C++ standard library async facilities without unnecessary abstractions
   - **`coroutine_integration_demo.cpp`** - C++20 coroutines integration for fine-grained execution control and cooperative multitasking
   - **`timeout_integration_demo.cpp`** - Timeout-protected integration for robust applications
   - **`seamless_parallel_timeout_demo.cpp`** - Seamless integration of timeout + async + parallel execution
   
   ### Parallelism Examples
   
   - **`parallelism_usage_demo.cpp`** - Comprehensive parallelism features including:
     - Quick start parallel interface
     - Robotics control systems with real-time parallelism
     - Stochastic process research with GPU-accelerated Monte Carlo
     - Multi-hardware target benchmarking
   - **`standard_parallelism_demo.cpp`** - Standard library parallelism integration:
     - C++17/20 std::execution policies
     - OpenMP parallel loops
     - Intel TBB integration
     - Task-based async dispatchers
   - **`simple_standard_parallelism.cpp`** - Simplified parallel usage patterns
   - **`standard_parallelism_demo.cpp`** - Advanced standard parallelism features
   - **`simplified_parallel_usage.cpp`** - Easy-to-use parallel interfaces
   - **`test_advanced_parallelism.cpp`** - Testing advanced parallelism features
   
   ### Advanced Features
   
   - **`interface_usage_demo.cpp`** - Integration interface examples:
     - Financial portfolio modeling with signal processing
     - Robotics control with real-time feedback
     - Scientific simulations with parameter updates
   - **`sde_usage_demo.cpp`** - Stochastic Differential Equation examples:
     - Black-Scholes financial models
     - Heston stochastic volatility
     - Noisy oscillator control systems
     - Stochastic Lotka-Volterra ecosystem models
   - **`coroutine_integration_demo.cpp`** - C++20 Coroutines integration:
     - Fine-grained execution control with pause/resume
     - Cooperative multitasking for multiple integrations
     - Zero-overhead state preservation between yields
     - Progress monitoring with minimal overhead
     - Interruptible long-running computations
   - **`advanced_gpu_async_demo.cpp`** - GPU acceleration with async processing
   - **`realtime_signal_processing.cpp`** - Real-time signal processing integration
   - **`composable_facilities_demo.cpp`** 🎯 **NEW: Solves Combinatorial Explosion** - Composable architecture demonstration:
     - High cohesion, low coupling design principles
     - Independent facilities: Timeout, Parallel, Async, Signals, Output
     - Flexible composition using decorator pattern
     - Order-independent facility stacking
     - Linear scaling (N classes for N facilities, not 2^N)
     - Extensibility without modifying existing code
     - Real-world usage scenarios and performance analysis
   
   ### Testing and Validation
   
   - **`quick_test.cpp`** - Quick validation tests
   - **`test_dop853.cpp`** - DOP853 integrator testing
   - **`test_rk4_only.cpp`** - RK4 integrator testing
   - **`sde_demo.cpp`** - Basic SDE demonstration
   
   ## Building and Running Examples
   
   ### Prerequisites
   
   - C++17 or later compiler
   - xmake build system
   - Optional: OpenMP, Intel TBB, CUDA for advanced parallelism examples
   
   ### Building
   
   ```bash
   # Using xmake
   xmake
   ```
   
   ### Running Examples
   
   ```bash
   # Run a specific example
   ./examples/working_integrators_demo
   
   # Run parallelism examples
   ./examples/parallelism_usage_demo
   ./examples/standard_parallelism_demo
   
   # Run SDE examples
   ./examples/sde_usage_demo
   
   # Run interface examples
   ./examples/interface_usage_demo
   ```
   
   ## Example Categories
   
   ### 1. Basic Usage
   Start with these examples to understand the fundamentals:
   - `working_integrators_demo.cpp`
   - `rk4_integrator_usage.cpp`
   - `state_concept_usage.cpp`
   
   ### 2. Parallelism
   For performance-critical applications:
   - `parallelism_usage_demo.cpp` - Full-featured parallelism
   - `standard_parallelism_demo.cpp` - Standard library integration
   - `simple_standard_parallelism.cpp` - Easy parallel usage
   
   ### 3. Advanced Features
   For complex applications:
   - `interface_usage_demo.cpp` - Signal processing and real-time integration
   - `sde_usage_demo.cpp` - Stochastic differential equations
   - `advanced_gpu_async_demo.cpp` - GPU acceleration
   
   ### 4. Modern C++ Features
   - **C++20 Coroutines**: Fine-grained control and cooperative multitasking in `coroutine_integration_demo.cpp`
   - **Standard Library Async**: Direct use of std::async without abstractions in `std_async_integration_demo.cpp`
   - **Parallel Execution**: Hardware-optimized parallel processing in `parallelism_usage_demo.cpp`
   
   ### 5. Domain-Specific Examples
   - **Finance**: Black-Scholes, Heston models in `sde_usage_demo.cpp`
   - **Robotics**: Control systems in `parallelism_usage_demo.cpp`
   - **Scientific**: Chemical reactions, ecosystem models in `sde_usage_demo.cpp`
   
   ## Key Features Demonstrated
   
   ### Integration Methods
   - **ODE Solvers**: RK4, RK23, RK45, BDF, LSODA, DOP853
   - **SDE Solvers**: Euler-Maruyama, Milstein, SRA1, SOSRA, SRIW1, SOSRI
   - **Adaptive Methods**: Automatic step size control
   - **Stiff Systems**: BDF and LSODA for stiff problems
   
   ### Modern C++ Features
   - **C++20 Coroutines**: 
     - Pausable/resumable integration with `co_yield`
     - Fine-grained CPU control for real-time systems
     - Zero-overhead state preservation
     - Cooperative multitasking between multiple integrations
     - Progress monitoring without blocking the main thread
   
   ### Parallelism
   - **CPU Parallelism**: std::execution, OpenMP, Intel TBB
   - **GPU Acceleration**: CUDA, Thrust integration
   - **Async Processing**: Task-based parallel execution
   - **Real-time Control**: Low-latency parallel integration
   
   ### Advanced Features
   - **Signal Processing**: Real-time event handling
   - **Parameter Sweeps**: Parallel parameter studies
   - **Multi-physics**: Coupled system integration
   - **Hardware Optimization**: Automatic backend selection
   - **Timeout Protection**: Prevents hanging integrations with configurable timeouts
   - **Progress Monitoring**: Real-time integration progress tracking and cancellation
   - **Seamless Parallelization**: Automatic hardware utilization without configuration
   - **Execution Strategy Selection**: Auto-chooses optimal approach based on problem and hardware
   
   ## Best Practices
   
   1. **Start Simple**: Begin with `working_integrators_demo.cpp` to understand basic usage
   2. **Choose the Right Integrator**: Use RK45 for general problems, BDF for stiff systems
   3. **Leverage Auto-Optimization**: Use `diffeq::integrate_auto()` for automatic hardware utilization
   4. **Handle Real-time Requirements**: Use interface examples for systems with external signals
   5. **Use Timeout Protection**: Add timeout protection for production applications
   6. **Scale Seamlessly**: From single integration to batch processing with `seamless_parallel_timeout_demo.cpp`
   7. **Compose Facilities**: Use the composable architecture for flexible combinations of capabilities
      - Start with `make_builder(base_integrator)`
      - Add only the facilities you need: `.with_timeout()`, `.with_parallel()`, etc.
      - Avoid combinatorial explosion - compose instead of inheriting
      - Order doesn't matter - decorators work in any sequence
   8. **Validate Results**: Compare with analytical solutions when available
   
   ## Troubleshooting
   
   ### Common Issues
   - **Compilation Errors**: Ensure C++17 support and required libraries
   - **Performance Issues**: Check parallel backend availability
   - **Accuracy Problems**: Verify integrator choice and tolerances
   - **Memory Issues**: Use appropriate state types and batch sizes
   - **Hanging Integration**: Use timeout protection for robust applications
   
   ### Getting Help
   - Check the main library documentation
   - Review the test suite for usage patterns
   - Examine the source code for implementation details
   
   ## Contributing
   
   When adding new examples:
   1. Follow the existing naming convention
   2. Include comprehensive comments
   3. Demonstrate realistic use cases
   4. Add to this README if appropriate
   5. Ensure the example compiles and runs correctly