sundew-algorithms 0.7.1

Sundew Algorithm — bio-inspired, energy-aware selective activation for edge AI systems.

Sundew Algorithms

Bio-inspired, energy-aware adaptive gating for stream processing with proven 77-94% energy savings across domains. Features reproducible evidence, layered precision uplift, statistical validation, and hardware readiness.

🌟 Key Features

• Energy Efficiency: 77-94% energy savings with domain-optimized presets
• Statistical Rigor: Bootstrap confidence intervals and comprehensive benchmarking
• Precision Enhancement: Layered classifier achieves 90-100% precision while preserving recall
• Multi-Domain: Tested on healthcare, IoT, ECG, financial, and network security datasets
• Hardware Ready: Power capture templates and runtime telemetry for real-world deployment
• Comprehensive Analysis: Ablation studies, adversarial testing, and performance validation

📊 Performance Highlights

Dataset	Preset	Recall	Energy Savings	Precision (CI)
Heart Disease	custom_health_hd82	0.196	82.0%	0.755 (0.680-0.828)
Breast Cancer	custom_breast_probe	0.118	77.2%	0.385 (0.294-0.475)
IoT Sensors	auto_tuned	0.500	88.2%	0.670 (0.574-0.758)
Network Security	aggressive	0.233	89.2%	0.461 (0.355-0.562)
Financial	aggressive	0.164	90.1%	0.219 (0.144-0.304)
MIT-BIH ECG	auto_tuned	0.218	88.8%	0.340 (0.328-0.352)

95% confidence intervals from 1000 bootstrap samples

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/oluwafemidiakhoa/sundew_algorithms.git
cd sundew_algorithms

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

Run Complete Analysis

# Execute full evidence suite (all datasets, presets, analyses)
uv run python tools/run_full_evidence.py

This generates:

• Dataset benchmarks across 6 domains with 10+ presets
• Layered precision analysis with visualization
• Statistical validation via bootstrap sampling
• Ablation studies and adversarial testing
• Comprehensive plots and performance reports

Results land in data/results/ with main report in docs/DATASET_BENCHMARK_REPORT.md.

📈 Architecture Overview

Core Algorithm

The Sundew algorithm implements bio-inspired adaptive gating with:

1. Significance Calculation: Weighted combination of magnitude, anomaly, context, and urgency
2. PI Controller: Adaptive threshold control with error feedback
3. Energy Accounting: Consumption, regeneration, and cap-aware management
4. Probabilistic Gating: Temperature-based activation decisions with hysteresis
5. Feedback Loops: Rate control and energy management

Data Flow

The processing pipeline handles:

• Multi-dataset benchmarking with statistical rigor
• Preset optimization for different domains
• Performance analysis with confidence intervals
• Robustness testing via adversarial streams

🎯 Usage Examples

Basic Algorithm Usage

import sundew

# Load a preset configuration
config = sundew.get_preset('custom_health_hd82')

# Create and run algorithm
algorithm = sundew.SundewAlgorithm(config)
result = algorithm.process(event_data)

print(f"Activated: {result.activated}")
print(f"Energy savings: {algorithm.energy_savings_percent:.1f}%")

Dataset Benchmarking

# Run specific presets on all datasets
uv run python benchmarks/run_dataset_suite.py \
  --presets tuned_v2 auto_tuned aggressive conservative \
  --out results/benchmark.csv

# Process single dataset with telemetry
uv run python benchmarks/run_pipeline_dataset.py \
  data/raw/heart_disease.csv \
  --preset custom_health_hd82 \
  --log results/telemetry.json

Statistical Analysis

# Generate bootstrap confidence intervals
uv run python benchmarks/bootstrap_metrics.py \
  data/results/dataset_runs_full/*.json \
  --out results/confidence_intervals.json \
  --samples 1000

# Layered precision analysis
uv run python benchmarks/layer_classifier.py \
  data/results/dataset_runs_full/financial_aggressive.json \
  --out results/layered_precision.csv

🔧 Configuration Presets

General Purpose

• tuned_v2: Balanced performance, good starting point
• auto_tuned: Dataset-adaptive, general streaming baseline
• aggressive: High activation rate, moderate energy savings
• conservative: Low activation rate, maximum energy savings (>90%)

Domain-Optimized

• custom_health_hd82: Heart disease (82% savings, bootstrap validated)
• custom_breast_probe: Breast cancer with enriched features (77% savings)
• ecg_v1: ECG/cardiac monitoring optimized
• energy_saver: Ultra-low power applications

Creating Custom Presets

from sundew import SundewConfig

# Create custom configuration
config = SundewConfig(
    activation_threshold=0.6,
    target_activation_rate=0.15,
    energy_pressure=0.03,
    gate_temperature=0.08,
    # ... other parameters
)

# Validate and use
config.validate()
algorithm = sundew.SundewAlgorithm(config)

📊 Visualization and Analysis

Performance Dashboard

Generate comprehensive visualizations:

# Create all architecture diagrams
uv run python create_architecture_diagram.py

# Plot layered precision improvements
uv run python benchmarks/plot_layered_precision.py \
  --csv data/results/layered_precision_extended.csv \
  --out assets/precision_uplift.png

# Performance comparison plots
uv run python benchmarks/plot_best_tradeoffs.py \
  --csv data/results/dataset_suite_full.csv \
  --out results/tradeoff_analysis.png

🧪 Validation and Testing

Test Suite

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/sundew --cov-report=html

# Property-based testing
uv run pytest tests/test_invariants.py -v

Robustness Testing

# Ablation studies
uv run python benchmarks/run_ablation_study.py

# Adversarial stream testing
uv run python benchmarks/run_adversarial_stream.py \
  --preset custom_health_hd82 \
  --scenario drift --seed 42

# Bootstrap statistical validation
uv run python benchmarks/bootstrap_metrics.py \
  data/results/dataset_runs_full/heart_disease_custom_health_hd82.json \
  --samples 1000

🔌 Hardware Integration

Power Measurement Workflow

1. Capture Runtime Telemetry

   uv run python benchmarks/run_pipeline_dataset.py \
     data/raw/iot_sensors.csv \
     --preset auto_tuned \
     --log power_telemetry.json
   

2. Implement Power Sampling

   # In tools/power_capture_template.py
   def read_power_sample():
       # Implement your power measurement here
       return power_watts
   

3. Merge Runtime + Power Data

   uv run python tools/merge_runtime_power.py \
     --runtime power_telemetry.json \
     --power power_measurements.csv \
     --out combined_analysis.json
   

Runtime Monitoring

# Add event listeners for monitoring
def monitor_callback(event_id, context, result):
    if context.energy_level < 10:
        send_alert("Low energy warning")

runtime = sundew.PipelineRuntime(config)
runtime.add_listener(monitor_callback)

📁 Project Structure

sundew_algorithms/
├── src/sundew/                 # Core implementation
│   ├── core.py                # Main algorithm
│   ├── config.py              # Configuration management
│   ├── runtime.py             # Pipeline framework
│   └── interfaces.py          # Component contracts
├── benchmarks/                # Performance analysis
├── tools/                     # Utilities and monitoring
├── data/                      # Datasets and results
│   ├── raw/                   # Input datasets
│   └── results/               # Comprehensive outputs
├── assets/                    # Visualizations and diagrams
├── docs/                      # Detailed documentation
└── tests/                     # Test suite

📚 Documentation

• Architecture Diagrams - Visual system documentation
• docs/DATASET_BENCHMARK_REPORT.md - Comprehensive benchmarking results
• docs/HARDWARE_VALIDATION_PLAN.md - Hardware deployment guide
• docs/RUNTIME_MONITORING.md - Monitoring and alerting setup

🤝 Contributing

# Setup development environment
git clone https://github.com/oluwafemidiakhoa/sundew_algorithms.git
cd sundew_algorithms
uv pip install -e .[dev]

# Run quality checks
uv run ruff check src tests
uv run ruff format src tests
uv run mypy src
uv run pytest

See CONTRIBUTING.md for detailed contribution guidelines.

📄 License & Citation

MIT License. If you use this work, please cite:

@software{idiakhoa2025sundew,
  title={Adaptive Threshold Control for Energy-Efficient Stream Processing},
  author={Idiakhoa, Oluwafemi},
  year={2025},
  publisher={Sundew Algorithms},
  url={https://github.com/oluwafemidiakhoa/sundew_algorithms},
  doi={10.5281/zenodo.17118217}
}

🔗 Links

• Homepage: oluwafemidiakhoa.github.io
• PyPI: pypi.org/project/sundew-algorithms
• Issues: GitHub Issues
• ORCID: 0009-0008-7911-1171

---

Sundew Algorithms: Bio-inspired intelligence for energy-efficient edge computing 🌿⚡