causal-triangulations 0.1.0

Causal Dynamical Triangulations in d-dimensions
Documentation

causal-triangulations

Crates.io Downloads Docs.rs CI rust-clippy analyze Codecov Audit dependencies

Causal Dynamical Triangulations for quantum gravity in Rust, built on fast Delaunay triangulation primitives.

🌌 Introduction

This library implements Causal Dynamical Triangulations (CDT) in Rust. CDT is a non-perturbative approach to quantum gravity that constructs discrete spacetime as triangulated manifolds with causal structure, providing a computational framework for studying quantum gravity phenomenology.

For an introduction to Causal Dynamical Triangulations, see this paper.

The library leverages high-performance Delaunay triangulation backends and provides a foundational toolkit for CDT research and exploration.

✨ Features

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

See CHANGELOG.md for release history.

🚧 Project Status

v0.1.0 foundation release — The validated 1+1 CDT foundation is in place, including toroidal volume-changing moves, nonuniform initial volume profiles, upstream-backed MCMC sampler mechanics, trace/summary exports, resumable checkpoints, and CI-aligned validation tooling.

The library currently supports validated 1+1 CDT construction, foliation checks, Metropolis sampling, resumable checkpoints, and core observables. Higher-dimensional CDT support, visualization/export workflows, and advanced ensemble-analysis helpers remain roadmap work.

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

⚙️ Requirements

  • Rust 1.96.0 or newer (pinned by Cargo.toml and rust-toolchain.toml)

Why Rust for CDT?

  • Memory safety for large-scale simulations
  • Zero-cost abstractions for performance-critical geometry operations
  • Rich ecosystem for scientific computing and parallel processing

📋 Running The Binary

The crate installs a cdt binary. Use it to construct an initial 1+1 CDT triangulation, optionally run the Metropolis move loop, and write analysis-friendly trace CSV output plus JSON summary/metadata.

# Build the binary
cargo build --release

# Show all supported options
./target/release/cdt --help

# Build an open-boundary triangulation and record the initial measurement
./target/release/cdt --vertices-per-slice 4 --timeslices 5 --output-json open-boundary-summary.json

# Build nonuniform open-boundary initial data from an explicit spatial volume profile
./target/release/cdt --volume-profile 4,6,5 --output-json open-profile-summary.json

# Run a periodic toroidal simulation and write both output formats
./target/release/cdt \
  --vertices-per-slice 8 \
  --timeslices 6 \
  --topology toroidal \
  --steps 200 \
  --thermalization-steps 20 \
  --measurement-frequency 10 \
  --temperature 1.5 \
  --seed 105 \
  --simulate \
  --output-csv toroidal-trace.csv \
  --output-json toroidal-summary.json

Prefer --vertices-per-slice for regular equal-slice initial data; the binary computes the total initial vertex count as vertices_per_slice × timeslices. Use --volume-profile N0,N1,... for explicit nonuniform spatial slice volumes; when supplied without --timeslices, the number of profile entries defines the time-slice count. --vertices is still accepted when you already know the total for regular data, but it must divide evenly by --timeslices. Open-boundary runs require at least 4 vertices per slice and toroidal runs require at least 3 vertices per slice. Without --simulate, the binary only builds the initial triangulation and writes the step-0 measurement.

Ensemble And Volume Behavior

Current simulations do not apply volume fixing. Volume-changing moves may change the total number of vertices and simplices during a run, so the sampled ensemble is the unfixed-volume ensemble defined by the configured CDT action and Metropolis-Hastings proposal rules. This is intentional for now: in 1+1 CDT, unfixed-volume simulations controlled by the cosmological constant are a standard toy-model setting, as in Israel and Lindner, Quantum gravity on a laptop: 1+1 Dimensional Causal Dynamical Triangulation simulation.

In an unfixed-volume ensemble, the cosmological constant is the coupling that controls volume growth or shrinkage because it is conjugate to the lattice volume term in the action. Use --cosmological-constant to tune that behavior. Values too far from the useful finite-volume regime can drive runs toward minimum-volume configurations or toward rapid growth; this is expected physics for the unfixed ensemble, not volume fixing. Automated λ-scan utilities for finding practical finite-volume windows are planned as #143; for v0.1.0, tune --cosmological-constant manually and inspect the reported volume and acceptance diagnostics.

The default 1+1 action constants use κ0 = 0, κ2 = 0, and an edge-count cosmological constant (2 / 3) ln 2, mapping the crate's λ N1 convention to the standard 2D CDT critical triangle-volume coupling λc = ln 2 for closed toroidal triangulations. The Delaunay backend supplies construction and validation infrastructure for a well-formed initial PL triangulation; the simulation ensemble is defined by CDT moves, constraints, action, and Metropolis-Hastings acceptance, not by maintaining Delaunayhood after every move.

Higher-dimensional CDT studies often use explicit approximate volume fixing for finite-size numerical work. For example, Ambjørn et al. discuss quadratic volume fixing in The Semiclassical Limit of Causal Dynamical Triangulations, and the toroidal phase-structure study uses quadratic volume fixing in The phase structure of Causal Dynamical Triangulations with toroidal spatial topology. This crate may add such a mode later, but it should be opt-in because it samples a modified action rather than the current bare unfixed-volume ensemble.

Ready-to-Use Scripts

The examples/scripts/ directory contains research workflows:

  • basic_simulation.sh - Simple simulation command
  • parameter_sweep.sh - Temperature sweep setup
  • performance_test.sh - Construction and simulation timing across system sizes

For detailed documentation, sample output, and usage instructions for each script, see examples/scripts/README.md.

For comprehensive CLI documentation and advanced usage patterns, see docs/CLI_EXAMPLES.md.

🧩 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 long-term design separates:

  • Geometry (triangulations and invariants)
  • Sampling (MCMC algorithms)
  • Physics (CDT-specific dynamics and observables)

Within this crate, src/geometry/ is the backend interface layer over delaunay, while src/cdt/ is the CDT domain layer.

📋 Benchmarking

Comprehensive performance benchmarks using Criterion:

# Run all benchmarks
cargo bench

# Specific benchmark categories
cargo bench triangulation_creation
cargo bench metropolis_simulation
cargo bench action_calculations

# CI regression benchmark contract
just bench-ci

# Performance regression testing
just perf-check          # Check for performance regressions
just perf-baseline       # Save performance baseline
just perf-report         # Generate detailed performance report
just perf-trends 7       # Analyze performance trends over 7 days

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.

Design notes

  • Separation of concerns: geometry primitives (Delaunay/Voronoi) are decoupled from CDT dynamics.
  • Foliation‑aware data model: explicit time labels; space‑like vs time‑like edges encoded in types.
  • Testing: unit + property tests for invariants (e.g., move reversibility, manifoldness).

🤝 How to Contribute

We welcome contributions! Here's a 30-second quickstart:

# Clone and setup
git clone https://github.com/acgetchell/causal-triangulations.git
cd causal-triangulations

# Traditional approach
cargo build && cargo test

# Modern approach (recommended) - install just command runner
cargo install just
just setup           # Complete environment setup
just check           # Run all linters/validators
just fix             # Apply formatters/auto-fixes
just --list          # See all available development commands

# Run examples
just run-example     # Basic simulation
./examples/scripts/basic_simulation.sh      # Shell script example
./examples/scripts/parameter_sweep.sh       # Temperature sweep study
./examples/scripts/performance_test.sh      # Performance benchmarking across system sizes

just setup prints a checklist of external tools used by repository workflows (for example: uv, taplo, actionlint, shfmt, shellcheck, jq) and how to install them.

Just Workflows:

  • just check - Run linters/validators (non-mutating)
  • just fix - Apply formatters/auto-fixes (mutating)
  • just ci - CI parity (mirrors GitHub Actions workflow ci.yml)
  • just commit-check - Comprehensive pre-commit validation

Repository tooling (via just):

  • just changelog - Regenerate CHANGELOG.md
  • just changelog-unreleased v0.1.0 - Generate a release changelog before the final tag exists
  • just tag v0.1.0 - Create an annotated git tag from changelog content
  • just perf-help - Show performance analysis commands (perf-baseline, perf-check, etc.)

For comprehensive guidelines on contributing, development environment setup, testing, and code organization, please see CONTRIBUTING.md.

This includes information about:

  • Building and testing the library
  • Running benchmarks and performance analysis
  • Code style and standards
  • Submitting changes and pull requests
  • Code organization and development tools

📚 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 Agents

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

AI tools (including ChatGPT, Claude, CodeRabbit, Codex, and WARP) are expected to read and follow AGENTS.md when proposing or applying changes.

Portions of this library were developed with the assistance of these AI tools:

All code was written and/or reviewed and validated by the author.

📝 License

This project's license is specified in LICENSE.