causal-triangulations

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

• 2D Causal Dynamical Triangulations with time-foliation (early implementation)
• Initial Metropolis–Hastings Monte Carlo prototype (subject to extraction into a standalone crate)
• Regge action calculation with configurable coupling constants (experimental)
• Ergodic moves (Alexander/Pachner moves) with causal constraints (experimental)
• Command-line interface for simulation workflows (early)
• Benchmarking and performance analysis infrastructure (in progress)
• Cross-platform compatibility (Linux, macOS, Windows)

See CHANGELOG.md for release history.

🚧 Project Status

🚧 Pre-release (0.0.x) — This crate is under active development and not yet ready for production use. APIs, data structures, and module boundaries may change without notice.

The library currently supports an initial 2D CDT implementation, with planned extensions to 3D and 4D.

⚙️ Requirements

• Rust 1.94 or newer (required by dependencies such as delaunay and la-stack)

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

🧩 Ecosystem (Planned)

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 (planned) — a composable MCMC engine to which the current Metropolis–Hastings implementation will migrate

The long-term design separates:

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

This crate focuses on the CDT (physics + domain) layer.

🤝 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 fix             # Apply formatters/auto-fixes
just check           # Run all linters/validators
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 fix - Apply formatters/auto-fixes (mutating)
• just check - Run linters/validators (non-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-tag v0.1.0 - Create an annotated git tag from changelog content
• just perf-help - Show performance analysis commands (perf-baseline, perf-check, etc.)

📋 Examples

Library Usage

See examples/basic_cdt.rs for a complete working example:

use causal_triangulations::{
    CdtConfig, MetropolisConfig, ActionConfig, MetropolisAlgorithm,
    geometry::CdtTriangulation2D,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create triangulation from random points
    let triangulation = CdtTriangulation2D::from_random_points(20, 1, 2)?;
    
    // Configure Monte Carlo simulation
    let metropolis_config = MetropolisConfig::new(1.0, 1000, 100, 10);
    let action_config = ActionConfig::default();
    let mut algorithm = MetropolisAlgorithm::new(metropolis_config, action_config);
    
    // Run simulation
    let results = algorithm.run(triangulation);
    
    println!("Acceptance rate: {:.3}", results.acceptance_rate());
    println!("Average action: {:.3}", results.average_action());
    Ok(())
}

Command Line Interface

# Build the binary
cargo build --release

# Run a basic simulation
./target/release/cdt --vertices 20 --timeslices 10 --steps 2000 --simulate

# Parameter sweep for phase transition studies
./target/release/cdt \
  --vertices 50 --timeslices 12 \
  --temperature 1.5 --coupling-0 0.8 \
  --steps 5000 --simulate

Ready-to-Use Scripts

The examples/scripts/ directory contains research workflows:

• basic_simulation.sh - Simple test run and validation
• parameter_sweep.sh - Temperature sweep for phase transition analysis
• performance_test.sh - Performance benchmarking 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.

📋 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

# 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

• Integrate an existing Rust Delaunay triangulation library (e.g., delaunay)
• 2D Delaunay triangulation scaffold
• 1+1 foliation (causal time‑slicing)
• 2D ergodic moves (Alexander/Pachner moves with causal constraints, fully validated)
• 2D Metropolis–Hastings (stabilized and moved to markov-chain-monte-carlo)
• Diffusion‑accelerated MCMC (exploration)
• Basic visualization hooks (export to common mesh formats)
• 3D Delaunay + 2+1 foliation + moves + M–H
• 4D Delaunay + 3+1 foliation + moves + M–H
• Mass initialization via Constrained Delaunay in 3D/4D
• Shortest paths & geodesic distance
• Curvature estimates / Einstein tensor (discrete Regge‑like observables)

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).

For comprehensive guidelines on contributing, development environment setup, testing, and project structure, 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
• Project structure 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

📝 License

This project's license is specified in LICENSE.