---
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)