jefftrull / 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++ uses the Computational Geometry Algorithms Library, Boost, TBB, and Eigen. Arbitrary-precision numbers and functions via MPFR and GMP. Uses Docopt to provide a beautiful command-line interface. Uses Melissa E. O'Neill's Permuted Congruential Generators library for high-quality RNGs that pass L'Ecuyer's TestU01 statistical tests. Uses Catch for BDD/TDD. Uses vcpkg for library management and building. Uses Doxygen for automated document generation. Uses {fmt} as a safe and fast alternative to iostream.

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 on MacOS and Linux with gcc/Clang using Travis-CI
• Continuous integration on Windows with MSVC using AppVeyor
• Continuous integration with Github Actions
• 3D Simplex
• 3D Spherical triangulation
• 2+1 foliation
• Integrate Docopt CLI
• S3 Bulk action
• 3D Ergodic moves
• High-quality Random Number Generation with M.E. O'Neill's PCG library
• Multithreading via TBB
• Automated code analysis with LGTM
• Build/debug with Visual Studio 2019
• Use {fmt} library (instead of iostream)
• Metropolis algorithm
• Output via HDF5
• A Surface mesh manifold of 3D Triangulation
• 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!

Getting Started

If you just want to run a stable version of the code, grab a versioned release.

Otherwise, you can clone the repo, including submodules, as follows:

git clone --recurse-submodules https://github.com/acgetchell/CDT-plusplus.git

(Older versions of git may require --recursive instead of --recurse-submodules.)

This will put you on the development branch. The project uses the PitchFork Layout, as follows:

• .github - GitHub specific settings
• build - Ephemeral out-of-source build directory
• cmake - Cmake configurations
• docs - Documentation
• external - Includes external projects, e.g. PCG
• include - Header files
• scripts - Build, test, and run scripts
• src - Source files
• tests - Unit tests

Setup

Install vcpkg:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install

Next, you will need to install up to date versions of CMake and Ninja. On non-Windows platforms, you will also need yasm so that vcpkg can install mpir, which is required for CGAL.

MacOS using homebrew:

brew install cmake
brew install ninja
brew install yasm

Linux using apt (you may also need to install m4):

sudo apt-get install cmake
sudo apt-get install ninja-build
sudo apt-get install yasm
sudo apt-get install m4

At minimum, you need to install prerequisites Catch, docopt, {fmt}, ms-gsl, Eigen, tbb, and CGAL (which installs boost, mpir and mpfr):

vcpkg install catch2
vcpkg install docopt
vcpkg install fmt
vcpkg install ms-gsl
vcpkg install eigen3
vcpkg install tbb
vcpkg install cgal

This builds from source, so it will take awhile. To use these successfully, you'll need to set the CMAKE_TOOLCHAIN_FILE option in your IDE or whatever invokes CMake to wherever you've installed vcpkg, (e.g. your home directory):

-DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake

(Visual Studio 2019 sets this for you by default.)

This project uses C++17 features, and successfully builds with AppleClang, gcc-9, clang-7, and Visual Studio 2019. On Ubuntu, you may need updated versions of Clang or gcc, and CMake, which is scripted in .travis.yml.

Building

If you want to get started right away, in the scripts directory run fast-build.sh or fast-build.bat, depending on your operating system. This will compile the appropriate executables in RELEASE mode with no tests.

This should result in the main program executable, cdt in build/bin or build\Debug, 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
• initialize is used by CometML to run parameter optimization

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-2019 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 https://adamgetchell.org/CDT-plusplus/ automatically generated by Travis-CI. If you have Doxygen installed you can generate the same information locally using the configuration file in docs\Doxyfile by simply typing at the top level directory (Doxygen will recursively search):

doxygen ./docs/Doxyfile

This will generate a docs/html/ directory containing 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).

Testing

In the scripts directory, run build.sh or build.bat depending on your operating system.

Unit tests are run (in build/tests or build\tests\Debug) via CDT_test, the Catch executable:

./CDT_test

or (Windows):

CDT_test.exe

You can also run both CTest integration and Catch unit tests in the build directory with:

cmake --build . --target test

or (Windows):

ctest -C Debug

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

Unit tests are turned off with -D ENABLE_TESTING:BOOL=FALSE, e.g. scripts/fast-build.sh.

Static Analysis

This project follows the CppCore Guidelines as enforced by ClangTidy, which you can install and then run using the clang-tidy.sh script:

sudo apt-get install clang-tidy
cd scripts
./clang-tidy.sh

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

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

brew install cppcheck
cd scripts
./cppcheck-build.sh

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

./scan.sh

Sanitizers

AddressSanitizer + UndefinedBehaviorSanitizer, ThreadSanitizer, and MemorySanitizer may be run with scripts/asan.sh, scripts/tsan.sh, and scripts/msan.sh. They are also checked in Travis-CI during commits.

Parameter Optimization

CometML is used to record Experiments which conduct Model Optimization. The script to do this is optimize-initialize.py. In order for this to work, you must install the following into your Python virtual environment.

pip install tensorflow
pip install comet-ml

You can then run experiments and look at results on https://www.comet.ml!

Visualization

Geomview is used to generate pictures of triangulations using the cdt-gv binary. In order for this to work, you must have Geomview installed (which doesn't work on Windows). On MacOS:

brew cask install xquartz
brew install geomview

If you get a Can't open display problem, look at the Geomview FAQ.

Contributing

Please see CONTRIBUTING.md and our CODE_OF_CONDUCT.md.

Your code should pass Continuous Integration:

• ClangTidy on all changed files

• Whitespace formatting (git diff --check HEAD^)

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

• LGTM; check to ensure you haven't introduced a security vulnerability. Look at the query console for more details.

Upstream issues

• As of 2018-11-29, the vcpkg formula for date is broken, so I removed reliance on that library. Hopefully it will be back in C++20! Until then, I use Boost.Date_Time on macOS/Linux and (unsafe) std::localtime on Windows, as Boost.Date_Time doesn't link correctly.

• As of 2019-10-16 vcpkg doesn't build on macOS 10.14 (but does on 10.15).