Library API

diffeq Examples

page 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

# Using xmake
xmake

Running Examples

# 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

Full API

Namespaces

Classes and Structs

Enums

Functions

Variables

Defines

Typedefs