Website · Quickstart · Features · Documentation · Methodology · Benchmarks · Examples
Forecasting tools tell you what the value will be. APDTFlow models time as continuous (Neural ODEs), so it also answers the question operations teams actually ask: when will it cross the line? The answer comes with a calibrated uncertainty window on the time itself.
One trained model answers three questions:
| Question | API |
|---|---|
| What are the next k values? | model.predict() |
| What is the value at any moment (14:37, in 3.6 days, beyond the trained horizon)? | model.predict_at(timestamps) |
| When will the value cross a threshold, with uncertainty on the time itself? | model.predict_when(threshold) |
One call, predict_when_fleet(), turns real NASA jet engines (never seen in
training) into a maintenance schedule sorted by act-by date, with what actually
happened marked. In this measured snapshot the calibrated windows covered 81% of
the actual crossings.
pip install apdtflow
from apdtflow import APDTFlowForecaster
model = APDTFlowForecaster(forecast_horizon=40, decoder_type='continuous',
use_conformal=True)
model.fit(df, target_col='capacity', feature_cols=sensor_cols)
model.predict() # classic grid forecast
model.predict_at(['2026-06-11 14:37', 3.6]) # value at ANY moment
result = model.predict_when(threshold=1.4, # WHEN it crosses the line
direction='below')
result.eta, result.act_by, result.censored
schedule = model.predict_when_fleet(assets, # whole fleet -> ranked schedule
threshold=1.4, direction='below')
| Event-timing audit (real NASA data, held-out units) | APDTFlow | Linear extrap. | Persistence |
|---|---|---|---|
| Battery end-of-life, 3 cells leave-one-battery-out (timing MAE, measured cycles) | 8.3 (2.8 on the typical cell) | 9.7 | 15.4 |
| Turbofan FD001, 40 unseen engines (timing MAE, cycles; 0.6% false alarms) | 8.3 | 8.7 | 11.5 |
| Turbofan FD002, 110 unseen engines, 6 operating regimes (timing MAE, cycles; 0.0% false alarms) | 9.2 | 8.1 | 11.3 |
APDTFlow wins the battery and FD001 audits outright and loses to linear on FD002, published as measured (it does win FD002's matched subset, 6.8 vs 7.8 cycles, and posts zero false alarms across 2,638 no-crossing windows, the property that matters most against alarm fatigue). Time-window coverage measured 96% / 40% / 54% against a 90% target across the three audits: strong within-distribution, stretched by cross-unit transfer; the trust panel below shows exactly that.
Reproduce: python experiments/battery_eol_demo.py, experiments/turbofan_when_demo.py,
experiments/fd002_robustness_demo.py. Full details: docs/experiment_results.md.
Multivariate sensor fusion (fit(..., feature_cols=sensors)) exposes
interpretable sensor weights via model.sensor_importance_, and, measured on the
same audit, trades coverage for sharpness: when the fused model commits to a
timing it is markedly more accurate (caught-event error 5.9 vs 8.3 cycles, zero
false alarms), but it commits far less often. Published as measured:
The panel reports its own miss: on cross-unit transfer the windows measured
under their 90% target, and for distant events the point estimate saturates
toward mid-horizon (the flattening scatter). That is why the operational rule
exists: schedule by act_by (the window's earliest edge), never by the point
estimate. The API returns act_by as a first-class field for exactly this
reason, and the per-lead-time error bars tell you how much to trust each horizon.
One trained model, queried at arbitrary real-valued timestamps (fractional steps,
between observations, even beyond the trained horizon), because the decoder
integrates a continuous-time ODE. Conformal intervals come interpolated across
time. (python examples/predict_at_demo.py produced this plot.)
"When will solar activity rise above 80?" The calibrated 90% window covered the
true crossing, and the act_by edge landed before it. Windows are calibrated on
crossing-time errors (time space), not value bands; that distinction is what makes
the coverage hold. (python examples/predict_when_demo.py.)
6 datasets (2 real, 4 synthetic), 12-step horizon, 30 epochs, MAE relative to
seasonal-naive (<1.0 beats it). Measured June 2026; reproduce:
python experiments/benchmark_multidomain.py.
| Dataset | APDTFlow | Linear | Holt-Winters |
|---|---|---|---|
| Daily min temperature (real) | 0.73 | 0.74 | 0.80 |
| Regime-switching nonlinear | 0.77 | 0.83 | 0.86 |
| Trend + dual seasonality | 0.85 | 0.50 | 0.38 |
| Retail-like multiplicative seasonal | 1.01 | 0.68 | 0.81 |
| Electric production (real, 397 pts) | 1.52 | 1.03 | 1.23 |
| Random walk (unpredictable) | 1.86 | 1.15 | 1.12 |
APDTFlow beats seasonal-naive on 3 of 6 domains (parity on a 4th) and beats every
baseline on two. For pure grid accuracy on regular data, tuned deep models
(NeuralForecast) or zero-shot foundation models (Chronos-2, TimesFM, Moirai-2)
may be stronger; APDTFlow's value is what grid models cannot do. We are not
aware of another forecasting library offering predict_at at arbitrary
timestamps or calibrated predict_when event timing (as of June 2026); if you
use a foundation model for grid accuracy, APDTFlow is complementary.
| Capability | APDTFlow | Grid DL libraries (NeuralForecast, Darts) | Foundation models (Chronos-2, TimesFM, Moirai-2) |
|---|---|---|---|
Grid forecasts (predict) |
✅ | ✅ | ✅ |
| Calibrated conformal intervals | ✅ | partial | partial |
Forecast at arbitrary real-valued times (predict_at) |
✅ | ✗ | ✗ |
Event timing with calibrated time windows (predict_when) |
✅ | ✗ | ✗ |
| Fleet-level act-by scheduling | ✅ | ✗ | ✗ |
| Zero-shot (no training) | ✗ | ✗ | ✅ |
- Stock prices / crypto: random-walk regime; nothing beats naive, including us (it's in our benchmark table on purpose).
- Event timing on noise-driven crossings (e.g., which exact day a noisy daily series first dips): no model has skill there; expect wide, honest windows.
- Irregularly-sampled / heavily missing data: we tested ODE-RNN encoders and missingness features; both lost to simple imputation baselines (documented).
- Very short series (< ~500 points): use ETS/ARIMA.
Each capability below, with what it's for and a usage snippet, is on the Features page (and in docs/features.md).
- Split & adaptive conformal prediction on every API; time-space calibrated windows for event timing
- Multivariate health-indicator fusion (
feature_cols=) with readablesensor_importance_; per-regime normalization (apdtflow.preprocessing.regime_normalize) for multi-condition equipment - Fleet API:
predict_when_fleet()→ act-by-sorted schedule, CSV/dict export - Exogenous & categorical features, backtesting (
historical_forecasts), MASE/sMAPE/CRPS/coverage metrics - Robust persistence (
save/loadwith scalers + calibration; pre-0.4 checkpoints are rejected with guidance), TorchScript export, FastAPI serving example, sklearn-styleget_params/set_params,score_recent()drift hook,set_seed()deterministic mode, MLflow/W&B logging hook,py.typed - Architectures: Neural ODE (default), Transformer, TCN, Ensemble
Pre-1.0 we follow SemVer pragmatically: breaking changes land only in minor releases, are flagged in CHANGELOG.md, and deprecated aliases are kept for one minor release. All checkpoints from versions ≤ 0.3.x are invalid: those versions contained a defect that made predictions independent of the input data; see the engineering history in docs/METHODOLOGY.md.
Run the audit yourself: python experiments/audit_predict_when.py benchmarks
predict_when against persistence, linear extrapolation, and seasonal baselines
on your data. If APDTFlow wins, open a PR and we will feature your domain with your
numbers. That pipeline is how every result on this page was produced, including
the ideas we tested and rejected (docs/METHODOLOGY.md).
- A Practical Approach to Time Series Forecasting with APDTFlow (Towards AI)
- APDTFlow v0.3.0: From Research to Production-Ready Time Series Forecasting (Towards AI)
Both articles cover earlier versions; the core ideas still apply, but the API has
grown since (predict_at, predict_when, fleet scheduling) and v0.4.0 fixed a
critical model defect; see the CHANGELOG before following old code
snippets.
If APDTFlow is useful in your research, please cite it:
@software{apdtflow,
author = {Braun, Yotam},
title = {APDTFlow: continuous-time forecasting with Neural ODEs},
url = {https://github.com/yotambraun/APDTFlow},
year = {2026},
version = {0.4.0}
}Methodology & references · Benchmarks · Model architectures · Documentation · Examples · Quickstart notebook · Contributing
MIT