Contributing to Causal Dynamical Triangulations

Thank you for your interest in contributing to the causal-triangulations library! This document provides comprehensive guidelines for contributors, from first-time contributors to experienced developers looking to contribute significant features.

Code of Conduct
Getting Started
Development Environment Setup
Project Structure
Development Workflow
Just Command Runner
Code Style and Standards
Testing
Documentation
Performance and Benchmarking
Submitting Changes
Types of Contributions
Release Process
Getting Help

Code of Conduct

This project and everyone participating in it is governed by our commitment to creating an inclusive and welcoming environment for quantum gravity research and computational physics development.

Our community is built on the principles of:

Respectful collaboration in quantum gravity research and computational physics
Inclusive participation regardless of background or experience level
Excellence in scientific computing and algorithm implementation
Open knowledge sharing about CDT and discrete approaches to quantum gravity

Getting Started

Prerequisites

Before you begin, ensure you have:

Rust 1.94.0 (pinned via rust-toolchain.toml - automatically handled by rustup)
Git for version control
Just (command runner): cargo install just

Quick Start

Fork and clone the repository:
- Fork this repository to your GitHub account using the "Fork" button
- Clone your fork locally:
```
git clone https://github.com/yourusername/causal-triangulations.git
cd causal-triangulations
```

Setup development environment:

# Comprehensive setup (recommended)
just setup           # Installs tools and builds project

# Manual setup
cargo build

Run tests:

# Basic tests
cargo test            # Library tests
cargo test --test cli # CLI tests
cargo test --test integration_tests  # Integration tests

# Or use convenient workflows:
just fix             # Apply formatters/auto-fixes
just test-all        # All tests

Try the examples:

cargo run --example basic_cdt
./examples/scripts/basic_simulation.sh

Run benchmarks (optional):

# Compile benchmarks without running
cargo bench --no-run

# Run all benchmarks
cargo bench

Code quality checks:

cargo fmt            # Format code
cargo clippy --all-targets -- -D warnings  # Linting
just fix             # Apply formatters/auto-fixes (recommended)
just check           # Run all non-mutating checks
just lint            # Lint code, docs, and config (checks only)

Use Just for comprehensive workflows (recommended):

# See all available commands
just --list

# Common workflows
just fix             # Apply formatters/auto-fixes
just check           # Run all linters/validators
just commit-check    # Full pre-commit validation
just ci              # CI parity (mirrors .github/workflows/ci.yml)

Development Environment Setup

Automatic Toolchain Management

🔧 This project uses automatic Rust toolchain management via rust-toolchain.toml

When you enter the project directory, rustup will automatically:

Install the correct Rust version (1.94.0) if you don't have it
Switch to the pinned version for this project
Install required components (clippy, rustfmt, rust-docs, rust-src, rust-analyzer)
Add cross-compilation targets for supported platforms

What this means for contributors:

No manual setup needed - Just have rustup installed (rustup.rs)
Consistent environment - Everyone uses the same Rust version automatically
Reproducible builds - Eliminates "works on my machine" issues
CI compatibility - Your local environment matches our CI exactly

First time in the project? You'll see:

info: syncing channel updates for '1.94.0-<your-platform>'
info: downloading component 'cargo'
info: downloading component 'clippy'
...

This is normal and only happens once.

Project Structure

causal-triangulations/
├── src/                    # Core library code
│   ├── cdt/               # CDT-specific implementations
│   │   ├── action.rs      # Regge action calculations
│   │   ├── metropolis.rs  # Monte Carlo simulation
│   │   ├── ergodic_moves.rs # Pachner moves
│   │   └── triangulation.rs # CDT triangulation wrapper
│   ├── geometry/          # Geometry abstraction layer
│   │   ├── backends/      # Geometry backend implementations
│   │   ├── mesh.rs        # Mesh data structures
│   │   ├── operations.rs  # High-level operations
│   │   └── traits.rs      # Geometry traits
│   ├── config.rs          # Configuration management
│   ├── errors.rs          # Error types
│   ├── util.rs            # Utility functions
│   ├── lib.rs             # Library root
│   └── main.rs            # CLI binary
├── examples/              # Usage examples
│   ├── basic_cdt.rs       # Library usage example
│   └── scripts/           # Ready-to-use simulation scripts
├── tests/                 # Test suite
│   ├── cli.rs             # CLI integration tests
│   └── integration_tests.rs # System integration tests
├── benches/               # Performance benchmarks
├── docs/                  # Documentation
└── justfile               # Task automation

Development Workflow

Just Command Runner

This project uses Just as the primary task automation tool. Just provides better workflow organization than traditional shell scripts or cargo aliases.

Essential Just Commands:

just setup          # Complete environment setup
just fix            # Apply formatters/auto-fixes (mutating)
just check          # Run linters/validators (non-mutating)
just ci             # CI parity (mirrors .github/workflows/ci.yml)
just commit-check   # Comprehensive pre-commit validation (recommended before pushing)
just lint           # Lint code, docs, and config (checks only)
just test-all       # All test suites
just bench          # Run performance benchmarks
just clean          # Clean build artifacts

Workflow Help:

just --list          # Show all available commands
just help-workflows  # Detailed workflow guidance

Typical Development Cycle

Start working on a feature/fix:

git checkout -b feature/your-feature-name

Development cycle:

# Make changes to code
just fix             # Apply formatters/auto-fixes
just test            # Run fast tests (lib + doc)
# Repeat until satisfied

Pre-commit validation:

just commit-check    # Full validation including all tests

Submit:

git commit -m "Your descriptive commit message"
git push origin feature/your-feature-name
# Create pull request

Code Style and Standards

Rust Code Style

Edition: Rust 2024
MSRV: Rust 1.94.0 (pinned in rust-toolchain.toml)
Formatting: Use rustfmt (configured in rustfmt.toml)
Linting: Strict clippy with warnings as errors

Linting Configuration

The project uses comprehensive linting rules:

cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery -W clippy::cargo

Key areas of focus:

Performance: Zero-cost abstractions, avoid unnecessary allocations
Safety: Leverage Rust's type system for mathematical correctness
Documentation: All public APIs must be documented
Testing: Comprehensive test coverage including property-based tests

Code Organization

Separation of concerns: Geometry backends decoupled from CDT algorithms
Type safety: Use strong types for mathematical concepts (e.g., time vs space coordinates)
Error handling: Comprehensive error types with context
Performance: Profile-guided optimization for hot paths

Testing

Test Categories

Unit Tests: Test individual functions and methods
```
cargo test --lib
```
Integration Tests: Test component interactions
```
cargo test --test integration_tests
```
CLI Tests: Test command-line interface
```
cargo test --test cli
```
Documentation Tests: Ensure examples in docs compile
```
cargo test --doc
```
Benchmark Tests: Verify benchmarks compile
```
cargo bench --no-run
```

Property-Based Testing

For mathematical algorithms, use property-based testing:

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_triangulation_invariant(vertices in 3u32..100) {
        let triangulation = create_test_triangulation(vertices);
        // Test Euler characteristic invariant
        prop_assert!(triangulation.satisfies_euler_formula());
    }
}

Test Data and Fixtures

Use deterministic test data when possible
For randomized tests, use seeded generators for reproducibility
Keep test execution time reasonable (< 1 second for unit tests)

Documentation

Documentation Standards

Public APIs: All public functions, structs, and traits must have rustdoc comments
Examples: Include usage examples in documentation
Mathematical Context: Explain the physics/mathematics behind algorithms
Performance Notes: Document time/space complexity where relevant

Documentation Generation

# Generate documentation
cargo doc --no-deps --open

# Check documentation builds without warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

Contributing to Docs

Update docs/ directory for comprehensive guides
Ensure examples in documentation actually compile
Link to relevant papers in REFERENCES.md

Performance and Benchmarking

Benchmark Organization

Benchmarks are organized in benches/ directory:

Triangulation creation: triangulation_creation
Geometry operations: edge_counting, geometry_queries
Monte Carlo simulation: metropolis_simulation
Action calculations: action_calculations

Running Benchmarks

# Run all benchmarks
cargo bench

# Run specific benchmark group
cargo bench triangulation_creation

# HTML reports are automatically generated at target/criterion/report/index.html
# Open the report in your browser
open target/criterion/report/index.html

Performance Guidelines

Profile before optimizing
Use criterion for statistical analysis
Consider memory allocation patterns
Document performance characteristics

Memory Management

Prefer stack allocation for small, fixed-size data
Use arena allocation for temporary geometry data
Profile memory usage for large simulations
Consider cache-friendly data layouts

Submitting Changes

Pull Request Process

Fork and create feature branch
Make changes following coding standards
Add tests for new functionality
Run full validation: just commit-check
Update documentation if needed
Create descriptive pull request

Commit Message Guidelines

Use conventional commit format:

type(scope): description

Longer description if needed.

- List specific changes
- Reference issues: Closes #123

Types: feat, fix, docs, test, refactor, perf, ci

Pull Request Checklist

Tests pass (just test-all)
Code is formatted (cargo fmt)
No clippy warnings (cargo clippy)
Documentation updated
Benchmarks still compile (cargo bench --no-run)
Changes are described in PR

Types of Contributions

Bug Reports

Use GitHub issues
Provide minimal reproduction case
Include system information
Reference relevant physics/mathematics

Feature Requests

Discuss in GitHub issues first
Consider breaking changes carefully
Provide use case and motivation
Consider implementation complexity

Code Contributions

Start with smaller changes to understand codebase
Focus on one feature/fix per PR
Consider performance implications
Add comprehensive tests

Documentation Contributions

Fix typos and improve clarity
Add examples and tutorials
Improve API documentation
Update mathematical explanations

Research Integration

Implement new CDT algorithms
Add support for different geometries
Contribute benchmarks from literature

Release Process

Version Numbering

This project follows Semantic Versioning:

MAJOR: Breaking API changes
MINOR: New features (backward compatible)
PATCH: Bug fixes and improvements

Release Checklist

Update version in Cargo.toml
Update CHANGELOG.md
Run full test suite
Create release tag
Publish to crates.io (when ready)

Getting Help

Resources

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and community discussion
Documentation: Comprehensive guides in docs/ directory
Just workflows: Run just help-workflows for guidance

Physics and Mathematics

For questions about the underlying physics and mathematics:

See REFERENCES.md for foundational papers
Consult CDT literature for theoretical background
Ask in GitHub Discussions for concept clarification

Development Questions

Check existing issues and discussions
Ask specific, focused questions
Provide context about what you're trying to achieve
Include relevant code snippets or error messages

Thank you for contributing to advancing computational quantum gravity research! 🌌

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History