File size: 5,318 Bytes
14ce12d 3236930 14ce12d ce975ec 14ce12d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | ---
license: mit
library_name: waveguard
pipeline_tag: tabular-classification
tags:
- anomaly-detection
- time-series
- time-series-classification
- physics
- waveguard
- zero-training
- tabular
- cybersecurity
- monitoring
- iot
- financial-data
- server-monitoring
language: en
datasets:
- emergentphysicslab/waveguard-benchmarks
---
# WaveGuard: Physics-Based Time-Series Anomaly Detection
**Zero-training anomaly detection using Klein-Gordon wave equation dynamics on a 3D lattice.**
No neural networks. No gradient descent. No hyperparameter tuning.
Deterministic, interpretable, and instantly deployable.
## How It Works
WaveGuard encodes your data onto a 3D lattice and evolves it under two coupled wave equations:
1. **Plastic Phase**: Normal data sculpts the lattice's `chi` field (mass landscape)
2. **Frozen Phase**: Test data propagates through the learned landscape. Normal data resonates; anomalies scatter.
The physics fingerprint (52-dimensional) captures the wave response, and Mahalanobis distance gives the anomaly score.
### The Equations
```
GOV-01: E(n+1) = 2E(n) - E(n-1) + dt^2 * [Laplacian(E) - chi^2 * E]
GOV-02: chi(n+1) = 2chi(n) - chi(n-1) + dt^2 * [Laplacian(chi) - kappa * E^2]
```
Where `chi_0 = 19` (vacuum stiffness) and `kappa = 1/63` (coupling constant).
## Quick Start
### Install
```bash
pip install WaveGuardClient
```
### Python SDK
```python
from waveguard_client import WaveGuardClient
client = WaveGuardClient()
# Create baseline from normal data
client.create_baseline("my_service", [
{"cpu": 45, "memory": 62, "latency_ms": 120},
{"cpu": 48, "memory": 65, "latency_ms": 115},
# ... more normal samples
])
# Detect anomalies
result = client.detect({"cpu": 95, "memory": 92, "latency_ms": 850}, "my_service")
print(result)
# {'is_anomaly': True, 'score': 312.5, 'confidence': 0.999, ...}
```
### One-Shot Detection (No Setup)
```python
training_data = [normal_sample_1, normal_sample_2, ...]
test_data = [sample_to_check_1, sample_to_check_2, ...]
results = client.scan(training_data, test_data)
for r in results:
print(f"Score: {r['score']:.2f} Anomaly: {r['is_anomaly']}")
```
## Benchmarks
| Dataset | Precision | Recall | F1 | Latency/sample |
|---------|-----------|--------|-----|----------------|
| Server Metrics (5 features, 50 train) | 0.789 | 1.000 | 0.882 | 8ms |
| Synthetic TS - Sinusoidal | 0.625 | 0.500 | 0.556 | 9ms |
| Synthetic TS - Seasonal | 0.400 | 0.600 | 0.480 | 8ms |
| Synthetic TS - Random Walk | 0.545 | 0.600 | 0.571 | 8ms |
| Synthetic TS - Trend | 0.400 | 0.200 | 0.267 | 8ms |
*CPU-only, N=24 grid, 30-50 training samples. Larger grids and more training data improve results. GPU (CuPy) gives 10-50x speedup.*
## Supported Data Types
| Type | Encoder | Example |
|------|---------|---------|
| JSON/Dict | `json` | `{"cpu": 45, "mem": 62}` |
| Time Series | `timeseries` | `[1.2, 3.4, 5.6, ...]` |
| Numeric Array | `numeric_array` | `[0.1, 0.2, 0.3]` |
| Tabular (CSV) | `tabular` | Pandas DataFrame rows |
| Text | `text` | Any string (hashed) |
| Image | `image` | 2D/3D numpy arrays |
## Key Advantages
| Feature | WaveGuard | IsolationForest | LOF | AutoEncoder |
|---------|-----------|-----------------|-----|-------------|
| Training needed | None (physics) | Yes (trees) | Yes (neighbors) | Yes (epochs) |
| Hyperparameters | 1 (sensitivity) | 5+ | 3+ | 10+ |
| Deterministic | Yes | No (random) | Yes | No (init) |
| Streaming | Yes | No | No | No |
| GPU acceleration | Optional | No | No | Required |
| Interpretable | Yes (chi landscape) | Partial | No | No |
## Architecture
```
Input Data --> Encoder --> 3D Lattice (N^3)
|
GOV-01 + GOV-02 Evolution
|
52-dim Physics Fingerprint
|
Mahalanobis Distance Score
|
Anomaly Decision + Confidence
```
## Model Details
- **Type**: Physics-based (no learned parameters beyond chi landscape)
- **Grid size**: Adaptive (16-256 based on input dimensionality)
- **Fingerprint**: 52 dimensions (chi statistics + E-field response + histogram)
- **Scoring**: Multi-resolution (global Mahalanobis + per-feature z-scores)
- **Threshold**: Adaptive (baseline mean + 2/sensitivity * baseline std)
## Limitations
- Best for structured/semi-structured data (JSON, time-series, tabular)
- CPU-only mode is slower for large grids (N>64)
- Requires at least 5 normal samples for stable baseline
- Not designed for image anomaly detection (use Anomalib instead)
## Citation
```bibtex
@software{waveguard2025,
title={WaveGuard: Physics-Based Anomaly Detection},
author={Partin, Greg},
year={2025},
url={https://huggingface.co/gpartin/waveguard-timeseries-ad}
}
```
## Links
- [Live Demo (HF Space)](https://huggingface.co/spaces/emergentphysicslab/waveguard-demo)
- [API Documentation](https://gpartin--waveguard-api-fastapi-app.modal.run/docs)
- [Python SDK (PyPI)](https://pypi.org/project/WaveGuardClient/)
- [GitHub](https://github.com/gpartin)
|