causal-triangulations

Causal Dynamical Triangulations for quantum gravity in Rust, built on fast Delaunay triangulation primitives and composable, adaptable Metropolis-Hastings sampling.

Contents

• Introduction
• Features
• Quickstart
• Scientific Basis
• Documentation Map
• Ecosystem
• Benchmarking
• Roadmap
• Contributing
• Citation
• References
• AI-assisted Development
• License

🌌 Introduction

This library implements Causal Dynamical Triangulations (CDT) in Rust. CDT is a non-perturbative approach to quantum gravity defining the gravitational path integral over causally triangulated spacetimes and evaluating it using Markov Chain Monte Carlo. For an introduction to CDT, see Ambjørn and Loll (2001), “Non-perturbative Lorentzian quantum gravity, causality and topology change”. The library leverages high-performance Delaunay triangulation backends and provides a foundational toolkit for CDT research and exploration.

✨ Features

• Alexander/Pachner-style local move proposals with causal constraints
• Command-line interface, examples, Criterion benchmarks, and CI-aligned validation tooling
• Cross-platform compatibility: Linux, macOS, Windows
• Delaunay-built 1+1 CDT strip and periodic toroidal S¹×S¹ constructors with foliation invariants
• Focused public preludes for simulation, triangulation, geometry, action, and observables
• Foliation-aware topology, causality, and simplex-classification validation
• Notebook-first quickstart for physicists, AI/ML users, and Rust contributors
• Proposal-before-mutation Metropolis-Hastings simulation with rollback on failed accepted moves
• Regge action calculation with configurable coupling constants
• Resumable serde-backed CDT/MCMC checkpoints for durable chain continuation
• Trace CSV simulation output for external analysis workflows; JSON summary/metadata for CLI/config export
• Volume-profile, Hausdorff-dimension, and spectral-dimension observables for CDT analysis

See CHANGELOG.md for release history and docs/roadmap.md for current direction, near-term candidates, and non-goals.

🚀 Quickstart

For most users, start with the notebook-first local run:

just notebook-setup
just notebook

just notebook-setup installs the uv-managed notebook dependency group, and just notebook launches JupyterLab with notebooks/00_quickstart.ipynb loaded. The recipes are defined in the justfile; inspect that file if you want to see exactly what they run.

The notebook uses the cdt binary as the engine, then loads the trace CSV and JSON summary into plots. It also explains setup, installation expectations, parameters, outputs, and small first experiments.

Requirements

• Rust 1.96.0 or newer (pinned by Cargo.toml and rust-toolchain.toml)
• uv for the notebook environment and repository-managed Python tooling

Rust keeps the simulation engine memory-safe and fast while preserving validation tooling for tests, documentation, benchmarks, and CI parity.

For headless CI or batch execution, use:

just notebook-execute

For Slurm and Open OnDemand workflows, see docs/hpc.md.

Before committing edited notebooks, clear generated outputs and execution counts:

just notebook-clear-outputs-all

Use the binary directly when you want a scriptable run. For CLI usage, topology examples, and logging/output patterns, see docs/cli-examples.md.

🧪 Scientific Basis

CDT approximates the gravitational path integral by summing over discrete, foliated spacetime geometries and sampling them with Markov Chain Monte Carlo. This crate currently implements a validated 1+1-dimensional CDT foundation: it builds open-boundary and toroidal initial triangulations, checks foliation, topology, causality, and simplex classification invariants, and runs local CDT move proposals through a Metropolis-Hastings sampler.

The validation is computational and ensemble-specific. The crate can check that generated and simulated triangulations satisfy the implemented discrete CDT contract, that accepted moves preserve the configured topology and foliation constraints, and that proposal asymmetry is handled through the sampler's Hastings correction. It does not prove continuum-limit physics, chain mixing, finite-size scaling, or suitability of a particular parameter choice for a scientific study.

Current simulations are grand-canonical, unfixed-volume runs. Volume-changing (1,3) and (3,1) moves may grow or shrink the lattice, and the cosmological constant controls that behavior through the action. This is intentional for the 1+1 foundation release; production volume fixing, automated λ scans, and higher-dimensional CDT remain future work.

For the detailed scientific contract, ensemble scope, backend role, and parameter interpretation, see docs/scientific-basis.md. Move semantics and detailed-balance notes live in docs/moves.md and docs/metropolis.md.

🗺️ Documentation Map

• CDT Spacetime Visualization notebook — example 1+1 CDT mesh visualization generator
• CLI Examples — command-line usage and output workflows
• Code Organization — module layout, backend boundaries, and architecture notes
• Example Scripts — maintained shell workflows for simulations, sweeps, and timing checks
• Foliation — time labels, spacelike/timelike classification, causality validation, and toroidal time handling
• HPC Notebook Workflows — Slurm, Open OnDemand, and cluster cache setup
• Metropolis — proposal-before-mutation ordering, detailed balance, trace semantics, and sampler/backend boundaries
• Moves — CDT local move semantics, proposal ratios, rollback behavior, and action calibration
• Polars Analysis Caches notebook — local Parquet caches and diagnostic plots for debugging CDT CSV/JSON outputs
• Quickstart notebook — notebook-first local 1+1 CDT run, parameter meanings, output files, and troubleshooting
• References — physics, numerical, and computational-geometry citations
• Roadmap — near-term work, higher-dimensional topology tracks, and non-goals
• Scientific Basis — CDT scope, validated invariants, current ensemble, and interpretation boundaries

🧩 Ecosystem

This crate is part of a broader Rust ecosystem for computational geometry and simulation:

• delaunay — geometric primitives and triangulations
• la-stack — linear algebra utilities
• markov-chain-monte-carlo — composable MCMC traits, including plan-before-commit proposals for CDT move ordering

The design separates geometry, sampling, and CDT-specific physics. Within this crate, src/geometry/ is the backend interface layer over delaunay, src/cdt/ is the CDT domain layer, and src/cdt/metropolis/ contains the thin adapters and runner code that consume markov-chain-monte-carlo.

• Foliation‑aware data model: explicit time labels; space‑like vs time‑like edges encoded in types.
• Testing: unit, integration, and property-based tests for topology, causality, foliation, and simulation invariants.

📈 Benchmarking

Performance validation uses Criterion benchmark suites plus repository recipes for repeatable local and CI checks. Run just bench-ci for the CI benchmark contract and just perf-check for a local regression check.

See benches/README.md for benchmark details and docs/performance-testing.md for comprehensive performance testing workflow documentation.

🛣️ Roadmap

The high-level roadmap, including 1+1 maturity work, future 2+1 and 3+1 CDT topology tracks, observables, dual/Voronoi geometry, visualization, and non-goals, lives in docs/roadmap.md.

🤝 Contributing

See CONTRIBUTING.md for the full contributor guide: project layout, development workflow, code style, testing, documentation layout, performance/benchmarking, and release support. Community expectations live in CODE_OF_CONDUCT.md. AI assistants should follow AGENTS.md.

Quick local workflow: run just setup once, then run just check before opening a pull request. For the full command list, run just --list.

📚 Citation

If you use this software in academic work or downstream research software, cite the Zenodo DOI and include the software metadata from CITATION.cff.

• DOI: https://doi.org/10.5281/zenodo.20513228
• Citation metadata: CITATION.cff

@software{getchell_causal_triangulations,
  author = {Adam Getchell},
  title = {causal-triangulations: A Causal Dynamical Triangulation library for quantum gravity research},
  doi = {10.5281/zenodo.20513228},
  url = {https://github.com/acgetchell/causal-triangulations}
}

For release-specific fields such as version, release date, and ORCID, prefer CITATION.cff.

🔎 References

For a comprehensive list of academic references and bibliographic citations used throughout the library, see REFERENCES.md.

This includes foundational work on:

• Causal Dynamical Triangulations theory
• Monte Carlo methods in quantum gravity
• Computational geometry and Delaunay triangulations
• Discrete approaches to general relativity

🤖 AI-assisted Development

This repository contains an AGENTS.md file, which defines the rules and invariants for AI coding assistants and autonomous agents working on this codebase.

Portions of this library were developed with the assistance of AI tools including ChatGPT, Claude, Codex, and CodeRabbit.

All accepted code and documentation changes are reviewed, edited, and validated by the author.

For tool citation metadata, see the AI-assisted development tools section of REFERENCES.md.

📜 License

This project is licensed under the BSD 3-Clause License.

---