Fractal-to-Algebraic Translation Engine (FATE)

FATE is a full toolkit for translating fractal/chaotic time series into algebraic surrogates and zeta-like analytics, expanding the pipeline described in The Fractal-to-Algebraic Translation Engine (FATE): A Constructive Framework Linking Fractal Dynamics, Algebraic Geometry, and Zeta-Like Analytic Structures.

The engine translates a univariate time series into four successive representations:

1. Takens delay embedding into a low-dimensional phase space.
2. Fractal descriptors (box-counting and correlation dimensions) that quantify geometric complexity.
3. Algebraic lift via polynomial regression (OLS, Ridge, Lasso, optional splines) that approximates the recurrence relation.
4. Analytic projection consisting of a Dirichlet-like series built from the raw sequence and an approximate Artin-Mazur zeta function derived from the fitted polynomial.

Getting Started

python -m pip install -e .[dev]
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest
fate --help

Prefer pinned dependency files? Use python -m pip install -r requirements.txt or conda env create -f environment.yml.

All dependencies live in pyproject.toml. Tests reproduce the logistic-map and prime-gap experiments from the paper.

Some Python distributions auto-install flaky pytest plugins (e.g., Dash). Setting PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 keeps the suite deterministic; omit it if your environment is clean.

Command-Line Tool

Install the editable package (or build a wheel) and use the fate CLI to run complete experiments. Built-in presets now include logistic, prime-gaps, Hénon, and Lorenz systems:

fate --dataset logistic --output artifacts/logistic.json --plot-dir artifacts
fate --dataset prime-gaps --output artifacts/prime.json --plot-dir artifacts
fate --dataset henon --no-artin --plot-dir artifacts
fate --dataset lorenz --degrees 2 3 --no-artin --poly-method ridge

Plots require matplotlib; if it is not installed the CLI still writes JSON summaries.

Bring Your Own Data

Researchers can feed arbitrary sequences (text/CSV/JSON/NumPy). Example with a CSV file containing a header row and multiple columns:

# Assume measurements.csv contains columns time,value,noise
fate --data-file measurements.csv \
     --skip-rows 1 \
     --column 1 \
     --label custom-run \
     --embedding-dim 3 \
     --degrees 2 3 4 5 \
     --poly-method ridge \
     --ridge-alpha 0.01 \
     --plot-dir artifacts/custom

Key CLI flags:

• --data-file: path to .txt, .csv, .json, .npy, or .npz.
• --column: 0-based column selector for multi-column text/CSV files.
• --array-key: key for JSON objects or .npz archives that contain multiple arrays.
• --degrees: polynomial degrees to explore; accepts multiple integers.
• --poly-method: choose ols, ridge, lasso, or spline.
• --embedding-dim, --ridge-alpha, --lasso-alpha, --artin-*, --no-artin: fine-tune each pipeline layer.

Use fate --help to see the full list of options. Internally, the CLI exposes the same functionality programmatically via fate.io.load_sequence_from_file and fate.FATEPipeline, so experiments can be scripted in notebooks as well.

Interactive Dashboard

Install the optional visualization extras:

python -m pip install -e .[viz]
streamlit run apps/fate_dashboard.py

The dashboard lets you switch between presets, tweak embedding/polynomial settings, upload arbitrary sequences, and view embeddings/residuals/zeta curves without writing code.

Launch the same experience without local installs via Binder:

• Open in Binder (examples notebook)

Research Playbook

See docs/research_playbook.md for guidance on interpreting dimensions, polynomial $R^2$, and zeta summaries when publishing results.

Example Notebook

examples/prime_gaps_experiment.ipynb walks through the full CLI-equivalent workflow inside Jupyter (Takens embedding → fractal metrics → algebraic lift) and mirrors the figures from the Binder link above.

Docker

Run FATE inside a reproducible container:

docker build -t betti-labs/fate .
docker run -it --rm -p 8501:8501 betti-labs/fate streamlit run apps/fate_dashboard.py

Dockerfile installs the package with dev/viz extras so you can run tests or launch the dashboard immediately.

Documentation Site

A lightweight docs site (MkDocs) lives under docs/. Build locally with:

python -m pip install mkdocs
mkdocs serve

and publish via GitHub Pages when ready.

Example

from fate import FATEPipeline, datasets

# Logistic map validation
dataset = datasets.logistic_map_sequence(n=1200, discard=200, r=3.9)
pipeline = FATEPipeline(
    embedding_dimension=2,
    polynomial_degrees=(2, 3),
    polynomial_method="ols",
    artin_kwargs={"max_period": 4},
)
result = pipeline.run(dataset)
print(result.polynomial_best.coefficients)  # close to [-3.9, 3.9, 0]
print(result.box_dimension.dimension)
print(result.correlation_dimension.dimension)
print(result.artin_mazur_zeta.evaluate(0.1))

# Prime gaps
prime_gaps = datasets.prime_gap_sequence(500)
complex_result = pipeline.run(prime_gaps)
print(complex_result.polynomial_best.r2)

Repository Layout

• src/fate/embedding.py – Takens delay embedding utilities.
• src/fate/fractal.py – Box-counting and correlation dimension estimators.
• src/fate/algebraic.py – Polynomial fitting (OLS/Ridge/Lasso/Spline).
• src/fate/zeta.py – Dirichlet series and Artin-Mazur zeta approximations.
• src/fate/pipeline.py – Pipeline orchestration.
• src/fate/datasets.py – Logistic map and prime gap helpers.
• tests/ – Regression tests covering fractal metrics and both canonical datasets.

Notes

• The Artin-Mazur zeta function is approximated by composing the fitted polynomial up to a configurable period and counting real fixed points within the observed domain.
• Poor fits (e.g., prime gaps) naturally yield low R^2 and degenerate zeta series, signaling inherent unpredictability as described in the paper.
• The fractal estimators sample-friendly defaults but accept kwargs in FATEPipeline for experimentation with additional embeddings or metrics.

License

Released under the MIT License (see LICENSE).

Citation

If you use FATE in academic work, please cite both the paper and the code:

@article{Betti2025FATE,
  title={The Fractal-to-Algebraic Translation Engine (FATE): A Constructive Framework Linking Fractal Dynamics, Algebraic Geometry, and Zeta-Like Analytic Structures},
  author={Gregory Betti},
  year={2025},
  journal={Preprint}
}

@software{BettiFATE,
  author = {Gregory Betti},
  title = {Fractal-to-Algebraic Translation Engine (FATE)},
  url = {https://github.com/Betti-Labs/FATE},
  version = {0.1.0},
  year = {2025}
}