MarathonTS

A benchmark of long synthetic time series from window assembly and long-series generators.

Many uses of synthetic time series need a series much longer than the windows a generative model is trained on. MarathonTS compares the two ways to obtain one under a single protocol: assembly from a pool of short generated windows (which windows, in what order, how the seams are processed) and long-series generators (Diffusion-TS, Chronos, TimesFM, Timestral). Every method yields a series of the same length; the benchmark measures its fidelity to the real data, its utility for models trained on it, its memorisation of the training data and its cost. The statistics (rankings, research questions with tests and uncertainty, a pre-specified confirmatory family) are a separate stage that reads the benchmark tables.

Quick start

A smoke test runs the whole pipeline on 2 datasets (ett, bike), 2 seeds and small models (Config.quick()); both datasets are downloaded without credentials. Local run in one environment (Linux or macOS, Python 3.11 or 3.12, git on the path):

git clone https://github.com/zypl-ai/MarathonTS.git
cd MarathonTS
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
git clone https://github.com/Y-debug-sys/Diffusion-TS.git external/Diffusion-TS
git -C external/Diffusion-TS checkout 566307e6cf2d8095e58de4c6e3a6ae965b69b5b5

python -m marathonts.bench.run all --quick                            # data → pools → series → fidelity → utility → tables
python -m marathonts.hypotheses.run --artifacts-dir artifacts/quick   # reports → artifacts/quick/reports/

The benchmark is also installable as a package, pip install marathonts (the same commands; see Guide C, C0). The pretrained generators (Chronos, TimesFM, Timestral) download their weights from Hugging Face on first use. The same test with Docker: Guide A, A2; in Colab: Guide B, B4.

Ways to run

Each guide covers the smoke test, the full run of profile min and re-running only the analysis on existing tables.

Results and how to read them

Stage 7 (python -m marathonts.hypotheses.run) writes four Markdown reports to artifacts/<profile>/reports/:

Their Parquet tables are in artifacts/<profile>/overall/, leaderboard/, metric_values/ and hypotheses/; the benchmark tables they are computed from are in artifacts/<profile>/tables/. artifacts/run_h200/ holds the tables and reports of the main run and artifacts/run_l4/ those of the replication run; your own runs are written to artifacts/<profile>/. The full artifacts of both runs (pools, series, fidelity and utility records, labels) are on Hugging Face, and the rankings of both runs can be explored in the interactive leaderboard, which opens on the main run. The metrics are defined in METRICS.md, the statistical procedure and the reading of the verdicts in HYPOTHESES.md.

Published runs and the main leaderboard

Two runs of profile min are published: the main run on one NVIDIA H200 (computing infrastructure of darya.ai; 34 methods, 24 ranked: the VAE and zEDGE pools, the open long-series generators and zEDGE_TS) and a replication run on one NVIDIA L4 (the VAE pool and the open long-series generators, 13 ranked). Every result of the paper and the leaderboard below come from the main run; the replication run shows how the results reproduce on another hardware and software stack. Ranks and times are compared only within a run. Their setup, the comparison and the sources of the differences (retrained generators, sampling, downstream models, a slightly different ETT series in the main run) are in BENCHMARK.md.

Overall leaderboard of the main run, in full (24 ranked methods; * proprietary, evaluated as a black box). Read it by tier, not by place: the tests do not separate the places within the top tier, and these places change between runs on different hardware (HYPOTHESES.md).

Change the configuration

Every setting is a field of Config (marathonts/bench/config.py); three profiles (min, mid, max) are ready-made sets of values. Settings are changed by command-line flags, in the cfg cell of the notebooks, in Python, or by a JSON file — CONFIGURATION.md, which also lists every field with its default and which stages a change recomputes.

Add your own component

Datasets, tasks, pool generators, long-series generators, assemblers, seam processing, ML models, fidelity and utility metrics, statistical tests and hypotheses are registered by name in a plugin file and switched on by one line of configuration — EXTENDING.md.

Documentation

The same documentation, with an API reference built from the docstrings (docs/api/), is a site (mkdocs.yml, published from the repository by .github/workflows/docs.yml); locally:

pip install -r docs/requirements.txt
mkdocs serve                        # http://127.0.0.1:8000

Project structure

MarathonTS/
├── marathonts/               # the Python package (pip install marathonts)
│   ├── bench/                #   benchmark: data, generators, assemblers, models, metrics → artifacts/<profile>/
│   │   ├── config.py         #     Config: every setting; the profiles min / mid / max
│   │   ├── run.py            #     the stages: python -m marathonts.bench.run <stage>
│   │   ├── registry.py       #     registries of the pluggable components
│   │   ├── model_configs.json  #   hyperparameters and search grids of the ML models
│   │   └── target_params*.json #   exogenous task thresholds per dataset
│   └── hypotheses/           #   leaderboard, rankings, metric values, research questions → artifacts/<profile>/reports/
├── pyproject.toml            # package metadata and dependencies
├── colab/                    # Colab notebooks 01–07 (one per stage) + colab_setup.py
├── envs/                     # dependencies per environment: base, core, tsgm, diffusion_ts, chronos, timesfm, timestral, sdv;
│                             #   lock/: exact versions of the main run
├── docs/                     # documentation; design figures in docs/figures/ (source: docs/figures/src/);
│                             #   API reference pages docs/api/, site build docs/requirements.txt
├── artifacts/run_h200/       # main run (NVIDIA H200): tables and reports
├── artifacts/run_l4/         # replication run (NVIDIA L4): tables and reports
├── Dockerfile                # two images: tsgm (TensorFlow) and bench (PyTorch, CUDA or CPU)
├── docker-compose.yml        # the stages in the two images with shared data/ and artifacts/
├── mkdocs.yml                # the documentation site
├── requirements.txt          # every environment in one (Python ≤ 3.12)
├── CITATION.cff, CHANGELOG.md, CONTRIBUTING.md
└── LICENSE, NOTICE           # Apache 2.0 for the code

Data (data/) and the Diffusion-TS code (external/) are not in the repository: the data are downloaded by the raw stage, Diffusion-TS is cloned at install time.

Proprietary methods

Three components are proprietary methods of zypl.ai under development: the assembler zseries (vae_zseries and its seam-processing variants) and, in the main run of the paper, two generators of the zEDGE family:

• zEDGE — a pool generator: it generates the window pool that the assemblers turn into a long series (pool prefix zedge, methods zedge_zseries, zedge_greedy, …);

• zEDGE_TS — a long-series generator: it generates the long series directly, without a pool. One sequence model over the latent vectors of zEDGE is trained per dataset and shared by the seeds; it is sampled in two modes:

  • zedge_ts_long — block inpainting: the latent sequence is built in blocks of 12 latent vectors, each next block conditioned on the last three latent vectors of the previous one;
  • zedge_ts_ar — autoregressive: one latent vector at a time, conditioned on the preceding 11; slower, but every step agrees with a longer context.

  In both modes every latent vector is decoded into a window, and neighbouring windows (overlap T/2) are joined by a cosine crossfade.

They are evaluated as black boxes under the same protocol as every other method: their results are published in the tables (Config.frozen_methods) and enter the rankings and the analysis, their code is not part of the repository, and their results cannot be reproduced from it. No open method uses any of their components. Every ranking can be recomputed with any set of methods excluded (--rank-exclude). The paper states the competing interests of the authors.

Citation

If you use MarathonTS, please cite the paper (the arXiv identifier is filled in at submission, before the release) and the original source of every dataset you use (DATASETS.md):

@misc{varshavskiy2026marathonts,
  title         = {{MarathonTS}: A Benchmark of Long Synthetic Time Series from Window Assembly and
                   Long-Series Generators},
  author        = {Varshavskiy, Ilyas and Shulgin, Sergey and Khalilbekov, Shuhrat and Boboeva, Bonu and
                   Azimi, Azizjon},
  year          = {2026},
  eprint        = {XXXX.XXXXX},
  archivePrefix = {arXiv}
}

Machine-readable citation metadata: CITATION.cff.

Authors

Ilyas Varshavskiy (ORCID 0000-0003-4924-2097), Sergey Shulgin, Shuhrat Khalilbekov, Bonu Boboeva, Azizjon Azimi — zypl.ai. Contact: Ilyas Varshavskiy, ilyas.varshavskiy@zypl.ai. Questions and bug reports: GitHub issues; contributions: CONTRIBUTING.md; changes between versions: CHANGELOG.md.

Licence

The code (marathonts/, colab/, docs/figures/src/) is licensed under the Apache License 2.0, copyright 2026 zypl Holding Ltd (NOTICE).

Datasets and benchmark artifacts (synthetic series, pools, model weights, labels) are not covered by it: each dataset keeps its own licence, and what is published for each one is listed in DATASET_LICENSES.md.

Third-party components keep their own licences. Diffusion-TS is cloned at install time and is not part of this repository. The vae_atsp assembler uses elkai, which bundles the LKH solver: LKH is free for academic and non-commercial use only, so commercial use of vae_atsp requires a licence for LKH. The weights of TimesFM 3.0 are under the TimesFM Non-Commercial License v1.0, those of Timestral under a Modified MIT licence; both are downloaded from Hugging Face, not distributed here. The optional pool generator sdv_par uses SDV, licensed under the Business Source License 1.1: it may not be used for a Synthetic Data Service (as defined by that licence); each SDV version converts to the MIT licence four years after its release.