Metadata-Version: 2.4
Name: tsfast
Version: 0.5.0
Summary: Deep learning library for time series analysis and system identification
Project-URL: Repository, https://github.com/daniel-om-weber/tsfast
Project-URL: Documentation, https://daniel-om-weber.github.io/tsfast
Author-email: Daniel Oliver Martin Weber <daniel.om.weber@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: deep-learning,fransys,pytorch,system-identification,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: h5py
Requires-Dist: identibench<0.5,>=0.4.0
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: torch>=2.1
Requires-Dist: tqdm
Provides-Extra: cpp
Requires-Dist: ninja; extra == 'cpp'
Provides-Extra: dev
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: jupytext; extra == 'dev'
Requires-Dist: nbmake; extra == 'dev'
Requires-Dist: ninja; extra == 'dev'
Requires-Dist: nvidia-ml-py; extra == 'dev'
Requires-Dist: onnx>=1.14; extra == 'dev'
Requires-Dist: onnxruntime<1.24,>=1.16; (python_version == '3.10') and extra == 'dev'
Requires-Dist: onnxruntime>=1.16; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: onnxscript>=0.1; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ray[tune]; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter>=0.25; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: onnx
Requires-Dist: onnx>=1.14; extra == 'onnx'
Requires-Dist: onnxruntime<1.24,>=1.16; (python_version == '3.10') and extra == 'onnx'
Requires-Dist: onnxruntime>=1.16; (python_version >= '3.11') and extra == 'onnx'
Requires-Dist: onnxscript>=0.1; extra == 'onnx'
Provides-Extra: tune
Requires-Dist: nvidia-ml-py; extra == 'tune'
Requires-Dist: ray[tune]; extra == 'tune'
Description-Content-Type: text/markdown



<img src="https://raw.githubusercontent.com/daniel-om-weber/tsfast/refs/heads/master/assets/logo.svg" width="200" align="left" alt="tsfast logo">

## TSFast

[![PyPI
version](https://badge.fury.io/py/tsfast.svg)](https://badge.fury.io/py/tsfast)
[![License: Apache
2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python
Versions](https://img.shields.io/pypi/pyversions/tsfast.png)](https://pypi.org/project/tsfast/)

## Description

> `tsfast` is an open-source deep learning library for time series
> analysis and system identification tasks. Built on PyTorch,
> it offers efficient deep learning models and utilities.

`tsfast` is an open-source deep learning package that focuses on system
identification and time series analysis tasks. Built on PyTorch, it
provides efficient implementations of various deep learning models and
utilities.

## Key Features

- **Specialized Data Handling** — HDF5-backed data pipeline with
  sequence transforms, noise injection, normalization, and TBPTT
  (Truncated Backpropagation Through Time) support.
- **Benchmark Datasets** — One-line access to Silverbox,
  Wiener-Hammerstein, Cascaded Tanks, and more via `identibench`.
- **Time Series Models** — RNNs (DenseNet, Residual), TCNs, CRNNs,
  transformers, NARX, state-space models (NeuralStateSpace, S5, LRU,
  Mamba), dynoNet, port-Hamiltonian networks (PHNN), and
  certified-by-construction REN/R2DN models, with fused Triton/C++
  kernels for the recurrent architectures.
- **Integrated Training** — `RNNLearner`, `TCNLearner`, `CRNNLearner`
  with custom losses (`nrmse`, `cut_loss`) and composable transforms.
- **System Identification** — Simulation, N-step prediction, FranSys,
  and autoregressive models with `InferenceWrapper` for deployment.
- **Physics-Informed NNs** — Embed governing equations into training
  via `CollocationLoss`, `PhysicsLoss`, and `PIRNN`, or train
  physics-only surrogates without measured data (DD-PINN, PINC).
- **Hyperparameter Optimization** — Ray Tune integration via
  `HPOptimizer`.
- **Deployment** — Model save/load, `InferenceWrapper` for
  NumPy-in/NumPy-out inference, and ONNX export.
- **Performance** — CUDA graph acceleration via `GraphedStatefulModel`
  for low-overhead GPU training.

## Installation

You can install the **latest stable** version using:

``` bash
pip install tsfast
```

For development installation:

``` bash
git clone https://github.com/daniel-om-weber/tsfast
cd tsfast
pip install -e '.[dev]'
# or using uv:
uv sync --extra dev
```

## Quick Start

Here is a quick example using a benchmark dataloader. It demonstrates
loading and visualizing data, training a RNN, and visualizing the
results.

``` python
from tsfast.basics import *

# Load benchmark dataset
dls = create_dls_silverbox()

# Train an RNN and visualize results
lrn = RNNLearner(dls)
lrn.fit_flat_cos(1)
lrn.show_results(max_n=1)
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
For major changes, please open an issue first to discuss what you would
like to change.

## Citation

If you use tsfast in your research, please cite:

``` text
@Misc{tsfast,
author = {Daniel O.M. Weber},
title = {tsfast - A deep learning library for time series analysis and system identification},
howpublished = {Github},
year = {2024},
url = {https://github.com/daniel-om-weber/tsfast}
}
```
