CDT-plusplus

KO | EN

gitlite — search

#android #python #css #javascript #php #react #nodejs #kotlin #html #machine-learning #ai #vue

★ 70 Open GitHub ↗

Causal Dynamical Triangulations in C++ using CGAL

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CDT-plusplus

**Quantize spacetime on your laptop.**

[![DOI](https://badgen.net/badge/DOI/10.5281%2Fzenodo.21487043/blue)](https://doi.org/10.5281/zenodo.21487043)
[![GitHub stars](https://badgen.net/github/stars/acgetchell/CDT-plusplus)](https://github.com/acgetchell/CDT-plusplus/stargazers)
[![License](https://badgen.net/github/license/acgetchell/CDT-plusplus)](https://github.com/acgetchell/CDT-plusplus/blob/main/LICENSE.md)
[![CI](https://github.com/acgetchell/CDT-plusplus/actions/workflows/ci.yml/badge.svg)](https://github.com/acgetchell/CDT-plusplus/actions/workflows/ci.yml)
[![Documentation](https://github.com/acgetchell/CDT-plusplus/actions/workflows/doxygen.yml/badge.svg)](https://www.adamgetchell.org/CDT-plusplus/)
[![codecov](https://codecov.io/gh/acgetchell/CDT-plusplus/branch/main/graph/badge.svg)](https://codecov.io/gh/acgetchell/CDT-plusplus)

![Small foliated Delaunay triangulation](https://raw.githubusercontent.com/acgetchell/CDT-plusplus/main/docs/images/S3-7-27528-I1-R1.png "7 timeslices 27528 simplices")

## Maintenance status

CDT++ v1.0.0-rc3 is the current C++23 release candidate. The repository remains maintained as an independent
scientific reference and regression oracle for
[causal-triangulations](https://github.com/acgetchell/causal-triangulations), the supported Rust successor. New C++
work is limited to correctness, reproducibility, cross-implementation validation, the complete supported 2+1D move
set, and work approved in project issues. The v1.0.0 release contract remains tracked by
[issue #90](https://github.com/acgetchell/CDT-plusplus/issues/90); making the GitHub repository read-only is a
separate future lifecycle decision rather than an automatic consequence of that release. The local Python
comparison harness orchestrates independent C++ and Rust executables and analyzes their declared outputs; it is not a
second scientific implementation.

## Table of contents

- [CDT-plusplus](README.md)
  - [Maintenance status](#maintenance-status)
  - [Introduction](#introduction)
    - [Regression-oracle scope](#regression-oracle-scope)
  - [Usage](#usage)
  - [Roadmap](#roadmap)
  - [Quickstart](#quickstart)
    - [Current reference-suite status](#current-reference-suite-status)
  - [Setup](#setup)
    - [Prerequisites](#prerequisites)
    - [Developer workflow](#developer-workflow)
    - [vcpkg maintenance](#vcpkg-maintenance)
  - [Build](#build)
    - [Project Layout](#project-layout)
  - [Command-line reference](#command-line-reference)
  - [Documentation](#documentation)
  - [Citing CDT++](#citing-cdt)
  - [Testing](#testing)
    - [Static Analysis](#static-analysis)
    - [Sanitizers](#sanitizers)
  - [Offline Comparison](#offline-comparison)
  - [Visualization](#visualization)
  - [Contributing](#contributing)
  - [Issues](#issues)

## Introduction

For an introduction to [Causal Dynamical Triangulations](https://github.com/acgetchell/CDT-plusplus/wiki),
including the foundations and recent results, please see the [wiki](https://github.com/acgetchell/CDT-plusplus/wiki).

[Causal Dynamical Triangulations][CDT] in [C++] uses the
[Computational Geometry Algorithms Library][CGAL], [Boost], and [TBB].
Arbitrary-precision numbers and functions are by [MPFR] and [GMP].
[Melissa E. O'Neill's Permuted Congruential Generators][PCG] library provides high-quality RNGs that pass L'Ecuyer's
[TestU01] statistical tests.
[doctest] provides [BDD]/[TDD].
[vcpkg] provides library management and building.
[Doxygen] provides automated document generation.
The supported C++ namespace and per-header contract are recorded in the
[C++ API boundary](docs/api-boundary.md).
The exact CGAL version, kernel, TDS, metadata, lifetime, TBB, benchmark, and
upgrade policies are recorded in the
[CGAL 6.2 integration contract](docs/cgal-integration.md).
The opt-in operations, ownership and synchronization rules, replayable stress
inputs, sanitizer boundary, and matched scaling protocol are recorded in the
[multithreaded CGAL contract](docs/multithreading.md).
[{fmt}] provides a safe and fast alternative to `iostream`.
[spdlog] provides fast, multithreaded logging.
Python and JSON Schema provide the local, offline cross-implementation comparison boundary.

### Regression-oracle scope

The principal reason to preserve this implementation is its causality-filtering Delaunay construction path in
[`include/Foliated_triangulation.hpp`](include/Foliated_triangulation.hpp). `find_invalid_timevalue_cells` classifies
cells from stored vertex time labels, `has_valid_timevalues` provides the predicate, `find_bad_vertex` selects a vertex
responsible for an acausal local configuration, and `fix_timevalues` removes offending vertices through CGAL so the
cavity is retriangulated until the foliation contract is satisfied.

The deterministic doctest scenario **"Detecting and fixing problems with vertices and cells"** in
[`tests/Foliated_triangulation_test.cpp`](tests/Foliated_triangulation_test.cpp) exercises this path with fixed points
and time labels. Its inputs, detected bad vertex, final initialization state, cell counts, and causal classification
are the first comparison fixture for `causal-triangulations`; exact Monte Carlo trajectories are not required to
match.

The versioned, language-neutral fixtures, canonical C++ results, run
manifests, raw outputs, and Rust consumption rules are published in the
[`reference/`](reference/README.md) package.

After building, run that fixture directly with:

```bash
./out/build/reference/tests/CDT_unit_tests \
  --test-case='*Detecting and fixing problems with vertices and cells*'
```

## Usage

The supported build produces `cdt` and `initialize` in
`out/build/reference/src`. Run the primary simulation through Just and pass its
arguments after the recipe name:

```bash
just run --help
```

For troubleshooting, the equivalent direct command is
`./out/build/reference/src/cdt --help`.

Use `--no-output` for batch, debugging, or scripted runs that should print
results without writing checkpoint or final triangulation files:

```bash
just run -s -n256 -t4 -a0.6 -k1.1 -l0.1 -p10 -c10 --seed 92 --no-output
```

With output enabled, every generated `.off` triangulation is accompanied by a
`.off.meta` provenance manifest containing the effective seed, configuration,
version/toolchain identity, transition-trace fingerprint, and payload checksum.
Checkpoint files are validated snapshots, not resumable simulation states; see
[`docs/reproducibility.md`](docs/reproducibility.md) for the replay and
persistence contract. Same-seed generation replays the random inputs, while
exact transition replay requires an identical starting manifold; CDT++ does
not alter its spherical construction to force CGAL to reproduce one of several
valid cospherical tetrahedralizations.

- `cdt-viewer` is currently disabled and will be restored as an opt-in v1.0.0
  target by [#98](https://github.com/acgetchell/CDT-plusplus/issues/98).
- `initialize` is also used by the dependency-free local parameter sweep described under
  [offline comparison](#offline-comparison).

See the [command-line reference](#command-line-reference) for every option.
Build and dependency instructions begin at [Quickstart](#quickstart).

## Roadmap

- [x] Cross-platform support on Linux, macOS (x64 & arm64), and Windows
- [x] Cross-compiler support on gcc, clang, and MSVC
- [x] Develop with [literate programming] using [Doxygen]
- [x] [Efficient Pure Functional Programming in C++ Using Move Semantics][functional]
- [x] Test using [CTest]
- [x] Develop using Behavior-driven development ([BDD]) with [doctest]
- [x] Continuous integration by [GitHub Actions] on the leading edge
- [x] 3D Simplex
- [x] 3D Spherical triangulation
- [x] 2+1 foliation
- [x] S3 Bulk action
- [x] 3D Ergodic moves
- [x] High-quality Random Number Generation with M.E. O'Neill's [PCG] library
- [x] Restore optional parallel triangulation with [TBB] ([#74](https://github.com/acgetchell/CDT-plusplus/issues/74))
- [x] Automated code analysis with [CodeQL]
- [x] Build/debug with [Visual Studio 2022]
- [x] Use [{fmt}] library (instead of `iostream`)
- [x] 3D Metropolis algorithm
- [x] Multithreaded logging with [spdlog]
- [ ] Restore optional visualization with [Qt] ([#98](https://github.com/acgetchell/CDT-plusplus/issues/98))
- [ ] Initialize two masses
- [ ] The shortest path algorithm
- [ ] Einstein tensor
- [ ] Complete test coverage
- [ ] Complete documentation
- [ ] Quantize Spacetime!

## Quickstart

From a fresh checkout, the primary supported headless build, dependency bootstrap, and test path is:

```bash
just build
```

The `build` recipe uses the Release configuration and the pkgx launcher on Unix when pkgx is available, then delegates
to `scripts/build.sh` on Unix or `scripts/build.bat` on Windows. Its
first run creates an ignored `.cache/vcpkg` checkout at the exact `builtin-baseline` recorded in `vcpkg.json`,
bootstraps vcpkg, installs the manifest dependencies, builds in `out/build/reference`, and runs the supported CTest
smoke suite. The first dependency build can take several minutes; subsequent runs reuse both vcpkg dependencies and
CMake/Ninja outputs, so an unchanged build is a no-op apart from configuration and tests.

For a production build with CDT++ assertions enabled, use the focused Debug
workflow:

```bash
just build-debug
```

The Debug build preset compiles the `cdt` and `initialize` production targets,
then the `debug-cli` test preset runs the 21 Debug-compatible CTest entries
labeled `integration`. It defines `CGAL_NDEBUG` because supported move paths
deliberately traverse invalid intermediate triangulations, while leaving
CDT++'s own assertions enabled. The `cdt` and `cdt-no-output` simulation tests
and the doctest unit suite are excluded because those paths trip project
invariant assertions on the intermediate state. Release remains the canonical
complete test configuration.

On Unix, compiler caching is optional. The pkgx launcher supplies the repository-pinned ccache binary when
`CDT_COMPILER_CACHE=ccache`; leaving the variable unset or setting it to `off` preserves the uncached build:

```bash
CDT_COMPILER_CACHE=ccache just build
```

Compiler caching covers project compilation; vcpkg binary caching remains responsible for reusing compiled
third-party packages.

The optional [pkgx](https://pkgx.sh/) entry point supplies the complete Unix developer-tool environment ephemerally
and invokes the same build contract directly:

```bash
./scripts/pkgx-build.sh
```

To expose the same dependency-build tools to an interactive shell, source the
reusable environment script:

```bash
source scripts/pkgx-env.sh
```

In CLion, open **Settings | Build, Execution, Deployment | Toolchains**, select
the local toolchain, choose **Add environment | From file**, and select
`scripts/pkgx-env.sh`. The script supplies the pkgx tool environment and points
`VCPKG_ROOT` at the repository-owned `.cache/vcpkg` checkout while keeping CGAL
and the other project libraries under vcpkg control.

pkgx does not install CGAL or any other project library; those remain owned by the pinned vcpkg manifest. The
underlying `./scripts/build.sh` and `scripts\build.bat` entry points remain available for troubleshooting and native
Windows development.

### Current reference-suite status

With the pinned baseline, the reference configuration and build succeed on macOS with AppleClang. The cross-platform
`just build` command runs all 127 CTest registrations through `scripts/build.sh` on Unix and `scripts/build.bat` on
Windows: 104 doctest scenarios from the unit-test executable and 23 CLI integration tests. The same `reference-smoke`
preset is the supported local and CI contract; there are no overlapping focused registrations that can pass while
omitting another doctest suite. The current `parallel` preset also registers 127 tests: 103 ordinary doctest scenarios,
one parallel launcher containing five scenarios, and the same 23 CLI integration tests. The parallel-enabled
AddressSanitizer configuration exercises the same replayable stress contract.

## Setup

This project uses [CMake]+[Ninja] to build C++23 sources and [vcpkg] manifest mode to manage C++ libraries. macOS with
AppleClang is the primary v1.0.0-rc3 validation target; the remaining compiler and platform matrix will be recorded as
it is verified.

### Prerequisites

The smallest pkgx-assisted host setup is:

- Xcode Command Line Tools on macOS, or a C++23 compiler and base build environment on Linux
- pkgx
- Just, used by the recipes and `scripts/pkgx-build.sh` to resolve the repository's tool-version pins
- Python 3.14 for native dependency bootstrap, and uv when checking or running the Python support scripts
- Doxygen 1.17.0 and Graphviz 15.1.0 when checking or generating API documentation; pkgx can supply both

The pkgx build and documentation launchers supply their required tools ephemerally, including Git, Bash, CMake,
Ninja, Python, Doxygen, Graphviz, M4, Autoconf, Autoconf Archive, Automake, GNU Libtool, Texinfo, and pkg-config. If
pkgx is not installed, provide these tools conventionally through a package manager such as [Homebrew] or apt:

- Git
- Bash
- build-essential (Linux only)
- m4
- automake
- autoconf
- autoconf-archive
- libtool (macOS) or libtool-bin (Linux)
- pkg-config
- texinfo
- ninja (macOS) or ninja-build (Linux)

The build does not require a pre-existing personal vcpkg checkout, a fork, a submodule, Docker, or a hosted
development environment.

### Developer workflow

The repository-root [Justfile](Justfile) provides the same small command vocabulary used by the related projects:

```bash
just check                 # Fast, non-mutating local checks
just build-debug           # Build Debug targets and run compatible CLI integration tests
just build-parallel        # Build and test the opt-in CGAL/oneTBB configuration
just codeql-prepare        # Configure dependencies before CodeQL tracing
just codeql-build          # Build production targets for CodeQL extraction
just fix                   # Format C++/Python source and the Justfile
just clang-tidy            # Analyze C++ with LLVM 22
just sanitize asan         # Build and exercise one Linux sanitizer preset
just build                 # Bootstrap, configure, build, and smoke-test
just run --help            # Build as needed and run cdt with forwarded arguments
just ci                    # Comprehensive pre-commit/pre-push validation
just docs-check            # Validate Doxygen output without changing the worktree
just docs                  # Generate publishable documentation in docs/html
just coverage              # Generate Linux GCC LCOV and HTML coverage reports
just release-check         # Validate release metadata and citation fields
just changelog-unreleased vX.Y.Z # Generate a pending release changelog
just tag-check vX.Y.Z      # Preview and validate an annotated release tag
just update-actions        # Update and repin Actions with pinact, then validate
just sync-vcpkg-tool-pins  # Sync the vcpkg tool release and Windows hashes
just python-sync           # Install the locked Python development environment
just python-check          # Check Python formatting, lint, and types
just python-fix            # Apply safe Ruff fixes and formatting
just comparison-run /path/to/rust-fixture out/comparisons/run-1 # Run and retain one comparison
just comparison-analyze out/comparisons/run-1 # Reanalyze without executing C++ or Rust
just spell-check           # Check repository text and identifiers for typos
```

`check` covers repository-wide C++ formatting, Python formatting/lint/type checks, spelling, release metadata and
citation fields, YAML, GitHub Actions syntax and security, whitespace, and CMake preset parsing. `ci` adds the pinact policy
check and the supported build/test contract. Documentation validation remains available separately through
`just docs-check`. The GitHub Actions Ubuntu GCC, Ubuntu Clang, macOS
AppleClang, and Windows MSVC jobs all run `just ci`; the two Ubuntu jobs also
run `just build-parallel`. The Ubuntu compiler jobs use the pinned pkgx ccache
package with a compiler-specific persistent cache. Sanitizer builds use Release
semantics with sanitizer-provided `-O1 -g` flags, while coverage uses Release
semantics with coverage-provided `-O0 -g` flags; no duplicate full-suite Debug
job is needed. Windows continues to compile with native MSVC; the
locked Python environment supplies `clang-format` only as a source formatter.
Install the developer tools with Homebrew, use equivalent system packages, or
let pkgx supply the Unix environment ephemerally; pkgx remains optional. For
example:

```bash
just python-sync
pkgx +just.systems@1.58.0 +git-scm.org +cmake.org@4.4.1 +ninja-build.org +python.org just check
```

All configure paths require CMake 4.4.0 or newer. The Justfile owns the tested
4.4.1 toolchain pin: pkgx-backed recipes remain reproducible at that version,
while direct configure paths accept newer compatible CMake releases. CI is
pkgx-first; because pkgx does not currently publish its CMake and Ninja packages
for Windows, that job uses the exact Justfile pins available as PyPI wheels
through `uv tool install --no-build`.

[pinact](https://github.com/suzuki-shunsuke/pinact) uses [`.pinact.yaml`](.pinact.yaml) to retain immutable action
SHAs, readable release comments, and a seven-day release cooldown. `just update-actions` uses an installed pinact,
Go, or a pkgx-provided Go fallback, then requires `yamllint`, `actionlint`, and `zizmor` to pass. Direct third-party
Python dependencies install only from locked wheels. The uv environment provides `clang-format` and `yamllint`;
actionlint uses its pinned upstream version, and zizmor uses its pinned PyPI wheel through `uvx`.

### vcpkg maintenance

`vcpkg.json` is the dependency source of truth. Its `builtin-baseline` pins the official
[`microsoft/vcpkg`](https://github.com/microsoft/vcpkg) registry commit used locally and in CI. The repository-local
`.cache/vcpkg` checkout is disposable tool/cache infrastructure and must not be edited or committed.
The native build entry points delegate checkout provenance, baseline, and executable-integrity validation directly
to `scripts/bootstrap_vcpkg.py`, whose cross-platform fixtures run under `just check`.

To update dependencies intentionally, bootstrap the current checkout, run the vcpkg baseline updater, synchronize
the independently reviewed tool pins, review both diffs, and then rerun the complete build:

```bash
python3 scripts/bootstrap_vcpkg.py
export VCPKG_ROOT="$PWD/.cache/vcpkg"
"$VCPKG_ROOT/vcpkg" x-update-baseline
just sync-vcpkg-tool-pins
./scripts/build.sh
```

`just sync-vcpkg-tool-pins` reads the new manifest baseline, fetches that exact upstream commit's tool metadata,
downloads the official Windows amd64 and arm64 release assets, and atomically updates the release and SHA-256 pins in
`scripts/bootstrap_vcpkg.py`. It leaves the existing pins unchanged if any input cannot be fetched or validated, and
only writes when the rendered release and hash assignments differ from the bootstrap source.

On Windows, invoke the synchronizer with `python.exe scripts\sync_vcpkg_tool_pins.py`; `scripts\build.bat` and
`scripts\fast-build.bat` already invoke the bootstrap implementation directly.

CI uses `lukka/run-vcpkg`, which derives the vcpkg checkout commit from the same manifest baseline and supplies a
binary cache. No separately maintained checkout SHA is required; the bootstrap script retains an independent tool
release and Windows executable hashes as a supply-chain review gate.

CodeQL keeps third-party implementation findings out of CDT++ results through a two-phase manual build.
`just codeql-prepare` configures the project, installs manifest dependencies before CodeQL starts tracing, and uses a
build directory under the host temporary directory so installed headers are outside the checkout. After CodeQL
initialization, `just codeql-build` compiles only the `cdt` and `initialize` production targets with tests disabled.
The regular `just build` and `just ci` contracts continue to build and run the complete test suite.

## Build

Run `just build` from the repository root. It delegates to `./scripts/build.sh` on Unix and `scripts\build.bat` on
Windows; either platform-specific script can itself be run from any working directory for troubleshooting. If
`VCPKG_ROOT` already names the clean official checkout at the manifest baseline, the script respects it; otherwise it
uses the pinned disposable checkout described above. Both scripts invoke the `reference` configure and build presets
followed by the `reference-smoke` test preset; products and tests are isolated under `out/build/reference`, while
`scripts\fast-build.bat` configures the same reference tree and builds only the primary `cdt` target. All entry points
preserve a compatible CMake cache and refresh it only when the selected vcpkg toolchain path changes. Direct script
invocations must expose CMake 4.4.0 or newer on `PATH`; the canonical pkgx-backed `just` recipes select the tested
4.4.1 toolchain automatically.

### Project Layout

The project is similar to [PitchFork Layout], as follows:

- .github - GitHub specific settings
- out/build/reference - Ephemeral supported headless build directory
- cmake - Cmake configurations
- docs - Documentation
- external - Includes submodules of external projects (none so far, all using [vcpkg])
- include - Header files
- scripts - Build, test, and run scripts
- src - Source files
- tests - Unit tests

## Command-line reference

CDT-plusplus uses [program_options] to parse options from the help message, and so
understands long or short argument formats, provided the short argument given
is an unambiguous match to a longer one. The help message should be instructive:

```text
./out/build/reference/src/cdt --help
Causal Dynamical Triangulations in C++ using CGAL.

A program that generates d-dimensional triangulated spacetimes
with a defined causal structure and evolves them according
to the Metropolis algorithm. Specify the number of passes to control
how much evolution is desired. Each pass attempts a number of ergodic
moves equal to the number of simplices in the simulation.

Usage:./cdt (--spherical | --toroidal) -n SIMPLICES -t TIMESLICES
            [-d DIM]
            [--init INITIAL RADIUS]
            [--foliate FOLIATION SPACING]
            [--no-output]
            [--seed SEED]
            [--threads THREADS]
            -k K
            --alpha ALPHA
            --lambda LAMBDA
            [-p PASSES]
            [-c CHECKPOINT]

Optional arguments are in square brackets.

Examples:
./cdt --spherical -n 32000 -t 11 --alpha 0.6 -k 1.1 --lambda 0.1 --passes 1000
./cdt -s -n32000 -t11 -a.6 -k1.1 -l.1 -p1000 --seed 92

Options:
  -h [ --help ]                 Show this message
  -v [ --version ]              Show program version
  -s [ --spherical ]            Spherical topology
  -e [ --toroidal ]             Toroidal topology
  -n [ --simplices ] arg        Approximate number of simplices
  -t [ --timeslices ] arg       Number of timeslices
  -d [ --dimensions ] arg (=3)  Dimensionality
  -i [ --init ] arg (=1)        Initial radius
  -f [ --foliate ] arg (=1)     Foliation spacing
  --no-output                   Do not write checkpoint or final triangulation
                                files
  --seed arg                    Root random seed (default: operating-system
                                entropy)
  --threads arg (=1)            Maximum worker threads for supported Delaunay
                                operations
  -a [ --alpha ] arg            Negative squared geodesic length of 1-d
                                timelike edges
  -k [ --k ] arg                K = 1/(8*pi*G_newton)
  -l [ --lambda ] arg           K * Cosmological constant
  -p [ --passes ] arg (=100)    Number of passes
  -c [ --checkpoint ] arg (=10) Checkpoint every n passes
```

`--threads` is a maximum concurrency limit for CGAL/oneTBB bulk Delaunay
operations. It defaults to 1. Zero and negative values are rejected. The
canonical reference build accepts only 1; values greater than 1 require the
`parallel` preset. This option does not parallelize Metropolis-Hastings,
Pachner moves, persistence, or concurrent access to one manifold.

The dimensionality of the spacetime is such that each slice of spacetime is
`d-1`-dimensional, so setting `d=3` generates two spacelike dimensions and one
timelike dimension, with a defined global time foliation. A
`d`-dimensional simplex will have some `d-1` sub-simplices that are purely
spacelike (all on the same timeslice) as well as some that are timelike
(span two timeslices). In [CDT] we actually care more about the timelike
links (in 2+1 spacetime), and the timelike faces (in 3+1 spacetime).

## Documentation

Online documentation is at <https://adamgetchell.org/CDT-plusplus/>.

The scientific transition, proposal-ratio, geometry-delta, counter, and
precision contracts are recorded in
[`docs/metropolis-hastings.md`](docs/metropolis-hastings.md).
The cross-language schema, exact-versus-numerical comparison policy, and raw
archival records are documented in
[`reference/README.md`](reference/README.md).
The literature-backed contracts, exact deltas, inverse relationships, and
failure-atomicity rules for the complete 2+1D move set are recorded in
[`docs/ergodic-moves.md`](docs/ergodic-moves.md).
Seed replay, PCG stream ownership, checkpoint metadata, and the parallel stream
policy are recorded in [`docs/reproducibility.md`](docs/reproducibility.md).
The repository-wide scientific bibliography is maintained in
[`REFERENCES.md`](REFERENCES.md).

Validate the generated API documentation without modifying the worktree:

```bash
just docs-check
```

To generate the same publishable output used by the documentation workflow, run `just docs`; it writes `docs/html/`
only after strict generation succeeds. Both recipes require the pinned Doxygen and Graphviz versions and use pkgx
ephemerally when matching local tools are unavailable. `USE_MATHJAX` allows [MathJax] to render LaTeX formulae, and
`HAVE_DOT` enables [GraphViz] diagrams. Documentation validation is intentionally separate from the cross-platform
`just ci` contract. The documentation workflow runs `just docs` on Ubuntu and publishes its output to the `gh-pages`
branch.

## Citing CDT++

If CDT++ contributes to published work, cite the software using
[`CITATION.cff`](CITATION.cff) and cite the scientific methods relevant to the
work from [`REFERENCES.md`](REFERENCES.md). The software citation records the
current declared release, `1.0.0-rc3`. Advance its version and release date
together with the CMake, vcpkg, Python-tooling, Doxygen, and CLI metadata for
subsequent releases.

## Testing

Run `just build`; it selects `scripts/build.sh` on Unix or `scripts\build.bat` on Windows, builds the test target, and
executes all 127 CTest entries: 104 doctest scenarios and 23 executable integration tests covering normal CLI use and
invalid-boundary rejection. The parallel-enabled AddressSanitizer and `parallel` configurations register 103 ordinary
doctest scenarios, one launcher containing five scenarios labeled `unit`, `parallel`, and `configuration`, and the same
23 integration tests, for 127 CTest entries. Every process-level test is labeled
`integration`, and invalid-input tests also carry the `cli-boundary`
subcategory. Run `just ci` for the complete
local validation gate.

`just check` also runs the repository-owned Semgrep policy and its annotated
fixtures. Use `just semgrep-test` while changing the rules and `just semgrep` to
scan the real source tree for false positives.

The doctest executable can also be run directly:

```bash
./out/build/reference/tests/CDT_unit_tests
```

To rerun the complete suite without rebuilding:

```bash
ctest --preset reference-smoke
```

To run a specific test category, use:

```bash
ctest --preset reference-smoke -L unit
ctest --preset reference-smoke -L integration
```

In addition to the command line output, you can see detailed results in the
`out/build/reference/Testing` directory generated by CTest.

### Coverage

Coverage reporting is supported on Linux with GNU GCC and its matching gcov,
CMake, Ninja, LCOV 2.5 or newer, and `genhtml`. Distribution packages may
provide an older LCOV that cannot parse coverage from current GCC releases; use
the [upstream LCOV release](https://github.com/linux-test-project/lcov/releases/tag/v2.5)
when necessary. Generate the same reports used by Codecov with:

```bash
CXX=g++ GCOV=gcov just coverage
```

The command uses an isolated `build/coverage` CMake tree and writes the filtered
LCOV tracefile to `build/coverage.info` and the browsable report to
`build/coverage-html/index.html`. Only project-owned `include/` and `src/`
paths are retained, consistently excluding tests, generated files, system
headers, and vcpkg dependencies. Reports include line and branch coverage;
function coverage is disabled because GCC can emit inconsistent function and
line records for generated lambda bodies. The raw LCOV capture temporarily
retains function records because LCOV 2.5 requires them while filtering GCC 16
data; the project-only extraction removes them from both published reports. If
coverage collection fails, verify that `g++ -dumpfullversion -dumpversion` and
`gcov --version` report the same major version.

GCC 16 also emits three known line-hit/branch-unhit records for templated
assignments in `Utilities.hpp`. The coverage recipe keeps LCOV's warnings
visible and requires that exact count during extraction and report generation;
new or removed inconsistencies therefore fail the command for review.

The Codecov workflow runs this recipe, uploads only `build/coverage.info` with
OIDC, and preserves both reports as a 14-day GitHub Actions artifact for local
diagnosis. If report generation fails, the workflow also preserves the gcov
inputs and CTest diagnostics for seven days. It does not rely on Codecov's
automatic gcov discovery. Codecov retains the LCOV branch detail but counts an
executed line with an uncovered branch as a line hit, keeping its project
percentage comparable to LCOV's line rate; use the LCOV artifact for the
separate branch-coverage rate.

### Static Analysis

Python 3.14 is selected by [`.python-version`](.python-version), uv locks the environment in `uv.lock`, Ruff owns
Python formatting and linting, and ty owns static type checking. Run `just python-sync` once and then use
`just python-check` or `just python-fix`; both commands are also part of the repository-wide validation recipes.

This project follows the [CppCore Guidelines][guidelines] as enforced by [ClangTidy]. The repository pins LLVM 22;
run Clang-Tidy through its Just recipe:

```bash
just clang-tidy
```

(Or use your favorite linter plugin for your editor/IDE.)

### Sanitizers

[AddressSanitizer] + [UndefinedBehaviorSanitizer], [LeakSanitizer], [MemorySanitizer], and [ThreadSanitizer] share the
repository-owned Linux driver and CMake presets. Run one locally with `just sanitize asan`, `just sanitize lsan`,
`just sanitize msan`, or `just sanitize tsan`; the GitHub Actions workflows invoke the same commands. MemorySanitizer
remains experimental because third-party dependencies are not instrumented. AddressSanitizer enables the optional
CGAL/TBB path and its parallel contract; ThreadSanitizer exercises the default sequential configuration.

## Offline Comparison

The [`cdt-compare`](docs/comparison-harness.md) command launches explicit CDT++ and `causal-triangulations`
commands without a shell. Both receive copied versions of the #94 protocol, result schema, and reference manifest.
The harness retains exact stdout, stderr, exit status, executable digest, command, working directory, process time,
and host provenance. It first anchors the live C++ output to #94's committed canonical result, then compares exact
fields and named tolerance-based fields with Rust. Any live C++ transition observations are independently anchored
to the committed #94 protocol before becoming the Rust reference. It classifies
implementation-specific and unsupported fields without interpreting either implementation as ground truth.

After building CDT++ and a compatible Rust fixture producer, run one bounded comparison and retain it locally:

```bash
just comparison-run /absolute/path/to/causal-triangulations-fixture out/comparisons/run-1
```

Reproduce `summary.json` entirely from the stored raw artifacts, without running either executable:

```bash
just comparison-analyze out/comparisons/run-1
```

The bundle under `out/comparisons/run-1` is canonical and is published atomically only after analysis and manifest
creation finish. Preserve its `inputs/`, `raw/`, `manifest.json`, and `summary.json` together. Python validates the
complete artifact inventory and its digests, validates schemas, constructs commands, classifies comparisons, and
renders a small text table; it does not implement topology, action, move-legality, or acceptance rules. See the
[comparison-harness contract](docs/comparison-harness.md) for producer configuration, placeholders, artifact layout,
failure records, and the C++ reference/Rust result boundary.

The retained `cdt-optimize-initialize` command is also entirely local and dependency-free. It writes one directory
per parameter pair under `out/experiments/initialize`, including configuration JSON, raw stdout, a tab-separated
volume profile, metrics, artifact digests, and source/executable provenance. Each invocation requires a nonexistent
output path. Seed `92` is the default; use `--seed` and `--output-directory` for another replayable record. Fresh CGAL
triangulations remain subject to the [reproducibility contract](docs/reproducibility.md).

## Visualization

The Qt-based `cdt-viewer` target is currently disabled. Its opt-in dependency feature, deterministic smoke fixture,
supported desktop matrix, and v1.0.0 restoration are tracked by
[#98](https://github.com/acgetchell/CDT-plusplus/issues/98); Qt and Eigen are intentionally absent from the default
headless build until that work is complete.

## Contributing

Please see [CONTRIBUTING.md] and our [CODE_OF_CONDUCT.md].

Your code should pass Continuous Integration:

- `just fix` for safe automatic formatting with the repository's [.clang-format]

- `just clang-tidy` to analyze C++ with the pinned LLVM 22 toolchain

- `just check` for fast, non-mutating source, documentation, YAML, workflow, and CMake validation

- `just ci` for the supported build and complete validation contract before pushing

The slower sanitizer workflows remain available through [GitHub Actions] and repository commands when relevant to a
change:

- [AddressSanitizer], [UndefinedBehaviorSanitizer], [LeakSanitizer], [MemorySanitizer], and [ThreadSanitizer]

Valgrind is intentionally unsupported: on x86/AMD64 its floating-point emulation does not honor the directed
rounding required by CGAL's interval predicates. Disabling CGAL's rounding check would make geometric results
untrustworthy, so memory diagnostics use the supported sanitizer workflows instead.

Optional:

- [ClangTidy] on all changed files

## Issues

- [vcpkg]'s version of [date] has an unfixed bug [#23637] which produces `use-of-uninitialized-value` in [MemorySanitizer].
- [vcpkg] has issues with `fontconfig:arm64-osx` [#40623].
- [vcpkg] fails to build [gmp] on Linux (which breaks CI) [#45336]

[#45336]: https://github.com/microsoft/vcpkg/issues/45336
[#40623]: https://github.com/microsoft/vcpkg/issues/40623
[#23637]: https://github.com/microsoft/vcpkg/issues/23637
[CDT]: REFERENCES.md#cdt-framework-2001
[CGAL]: REFERENCES.md#cgal-triangulations
[CMake]: https://www.cmake.org
[doctest]: https://github.com/doctest/doctest
[guidelines]: https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
[CTest]: https://gitlab.kitware.com/cmake/community/wikis/doc/ctest/Testing-With-CTest
[literate programming]: http://www.literateprogramming.com
[Doxygen]: http://www.doxygen.org
[Homebrew]: https://brew.sh
[Ninja]: https://ninja-build.org
[program_options]: https://www.boost.org/doc/libs/1_85_0/doc/html/program_options/tutorial.html
[Mathjax]: https://www.mathjax.org
[GraphViz]: https://www.graphviz.org
[MPFR]: https://www.mpfr.org
[GMP]: https://gmplib.org
[functional]: https://blog.knatten.org/2012/11/02/efficient-pure-functional-programming-in-c-using-move-semantics/
[TBB]: https://www.threadingbuildingblocks.org
[Doxyfile]: https://github.com/acgetchell/CDT-plusplus/blob/main/docs/Doxyfile
[Boost]: https://www.boost.org
[ClangTidy]: https://clang.llvm.org/extra/clang-tidy/
[date]: https://howardhinnant.github.io/date/date.html
[BDD]: https://en.wikipedia.org/wiki/Behavior-driven_development
[TDD]: https://en.wikipedia.org/wiki/Test-driven_development
[vcpkg]: https://github.com/Microsoft/vcpkg
[C++]: https://isocpp.org/
[Pitchfork Layout]: https://api.csswg.org/bikeshed/?force=1&url=https://raw.githubusercontent.com/vector-of-bool/pitchfork/develop/data/spec.bs#tld.docs
[PCG]: REFERENCES.md#pcg-random-number-generators
[TestU01]: http://simul.iro.umontreal.ca/testu01/tu01.html
[CONTRIBUTING.md]: https://github.com/acgetchell/CDT-plusplus/blob/main/.github/CONTRIBUTING.md
[CODE_OF_CONDUCT.md]: https://github.com/acgetchell/CDT-plusplus/blob/main/.github/CODE_OF_CONDUCT.md
[GitHub Actions]: https://github.com/features/actions
[CodeQL]: https://codeql.github.com/
[Visual Studio 2022]: https://visualstudio.microsoft.com/vs/
[{fmt}]: https://github.com/fmtlib/fmt
[AddressSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizer
[LeakSanitizer]: https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer
[ThreadSanitizer]: https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual
[MemorySanitizer]: https://github.com/google/sanitizers/wiki/MemorySanitizer
[UndefinedBehaviorSanitizer]: https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html
[.clang-format]: https://github.com/acgetchell/CDT-plusplus/blob/main/.clang-format
[spdlog]: https://github.com/gabime/spdlog
[Qt]: https://www.qt.io

CDT-plusplus

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README