claremacrae/CDT-plusplus

Causal Dynamical Triangulations in C++ using CGAL

CDT-plusplus

Quantize spacetime on your laptop.

For an introduction to Causal Dynamical Triangulations, including the foundations and recent results, please see the wiki.

Causal Dynamical Triangulations in C++ using the Computational Geometry Algorithms Library and Eigen>3.1.0, compiled with CMake using Clang/LLVM. Arbitrary-precision numbers and functions by MPFR and GMP. Option-types via Boost >= 1.64.0. Uses Docopt to provide a beautiful command-line interface, and Howard Hinnant's date and timezone library for accurate time (both as [subrepos]). Catch is included as a single header in order to build/run unit tests. Ninja is a nice (but optional) replacement for make. Intel's TBB provides significantly better performance if present (3x+). Follows the CppCore Guidelines as enforced by ClangTidy, which you can run using the clang-tidy.sh script:

./clang-tidy.sh

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

The goals and targets of this project are:

• Developed with literate programming using Doxygen
• Efficient Pure Functional Programming in C++ Using Move Semantics
• Validation tests using CTest
• Behavior-driven development (BDD) with Catch
• Continuous integration with MacOS and Linux on Travis-CI and Windows on AppVeyor
• Code coverage measurements with Codecov
• 3D Simplex
• 3D Spherical triangulation
• 2+1 foliation
• Integrate Docopt CLI
• S3 Bulk action
• 3D Ergodic moves
• Multithreading via TBB
• Metropolis algorithm
• Output via HDF5
• 4D Simplex
• 4D Spherical triangulation
• 3+1 foliation
• S4 Bulk action
• 4D Ergodic moves
• Initialize two masses
• Shortest path algorithm
• Einstein tensor
• Complete test coverage
• Complete documentation
• Quantize Spacetime!

Prerequisites

CDT++ should build on any system (e.g. Linux, MacOS, Windows) with CMake, CGAL, Boost, MPFR, Eigen, and curl installed. TBB provides an optional (but significant) speed boost. Catch is optional (but recommended) for running the unit tests, and Ninja is an optional replacement for make which provides quick parallel builds of the unit tests.

On MacOS, the easiest way to do this is with Homebrew:

brew upgrade cmake
brew install ninja
brew upgrade boost
brew install eigen
brew install tbb
brew install cgal --with-eigen3 --with-lapack

On Ubuntu, you will need an updated versions of Clang or gcc, CMake, and Boost, which is scripted in .travis.yml. With Howard Hinnant's date library, you may also need to install libcurl-dev, which is a virtual package with many flavors, OpenSSL being the most tried and tested.

Build

This project uses a separate build/ directory, which allows you to rebuild the project without cluttering the source code. Thus, download this source code (clone this repo from GitHub or grab a release) and run the following commands in the top-level directory:

mkdir build && cd build
cmake -DTESTS:BOOL=OFF -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

(Or run build.sh if you have Ninja installed.)

This should result in the main program executable, cdt in the build/ directory, along with several others.

• cdt-gv converts output files to GeomView format for visualization
• cdt-opt is a simplified version with hard-coded inputs, mainly useful for debugging and scripting

If you build Catch unit tests (-DTESTS:BOOL=ON), the executable /test/CDT_test will also be present. See Tests for details.

For some versions of Linux, you may have to build CGAL from source. Follow the instructions (or their equivalent) given in the install section of the .travis.yml build file.

There are enough unit tests that it's worthwhile doing fast parallel builds. Ninja is just the ticket. It's effectively a drop-in replacement for make, and works nicely because CMake generates the build files. There's quite a difference in speed. CMake also abstracts away the build tool nicely. Again, see build.sh for an example.

Usage

CDT-plusplus uses Docopt 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:

./build/cdt --help
Causal Dynamical Triangulations in C++ using CGAL.

Copyright (c) 2014-2018 Adam Getchell

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] -k K --alpha ALPHA --lambda LAMBDA [-p PASSES] [-c CHECKPOINT]

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

Options:
  -h --help                   Show this message
  --version                   Show program version
  -n SIMPLICES                Approximate number of simplices
  -t TIMESLICES               Number of timeslices
  -d DIM                      Dimensionality [default: 3]
  -a --alpha ALPHA            Negative squared geodesic length of 1-d
                              timelike edges
  -k K                        K = 1/(8*pi*G_newton)
  -l --lambda LAMBDA          K * Cosmological constant
  -p --passes PASSES          Number of passes [default: 100]
  -c --checkpoint CHECKPOINT  Checkpoint every n passes [default: 10]

The dimensionality of the spacetime is such that each slice of spacetime is d-1-dimensional, so setting d=3 generates 2 spacelike dimensions and one timelike dimension, with a defined global time foliation. Thus 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 may be found at http://www.adamgetchell.org/CDT-plusplus/

If you have Doxygen installed you can generate the same information locally by simply typing at the top level directory (Doxygen will recursively search):

doxygen

This will generate the html/ directory which will contain documentation generated from CDT++ source files. USE_MATHJAX has been enabled in Doxyfile so that the LaTeX formulae can be rendered in the html documentation using MathJax. HAVE_DOT is set to YES which allows various graphs to be autogenerated by Doxygen using GraphViz. If you do not have GraphViz installed, set this option to NO (along with UML_LOOK).

Tests

Catch is optional, but strongly recommended if you want to make changes to or understand the source code in detail. It's easily deployable as a single header file obtained from GitHub. Building the Catch CDT_test executable is set by the TESTS variable in CMakeLists.txt, or at the command line (first cd into build) using:

cmake -DTESTS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug ..

Unit tests using Catch are then run (in the build/test directory) via:

./CDT_test

You can also run both CTest and Catch via:

cmake --build . --target test

In addition to the command line output, you can see detailed results in the build/Testing directory which is generated thereby.

Static Analysis

Manual

The cppcheck-build.sh script runs a quick static analysis using cppcheck.

Clang comes with scan-build which can run a much more thorough, but slower static analysis integrated with CMake and Ninja. Simply run the scan.sh script.

Continuous Integration

One of the Travis-CI jobs runs ClangTidy on all changed files.

Another runs Valgrind; be sure to look at the results to ensure you're not leaking memory.

Contributing

Please see CONTRIBUTING.md and our CODE_OF_CONDUCT.md.