tudat-bundle

This repository facilitates parallel development between the tudat (C++) and the tudatpy (Python) library. Specific indications for documenting tudat or tudapy are reported in the tudat-multidoc/README.md file.

For more details on the project, we refer to the project website and our project Github page.

Structure of the tudat-bundle

The tudat-bundle comprises the following repositories:

• tudat, where the tudat source code is located (this is a separate git repository);
• tudatpy, where the tudatpy binding code is located (this is a separate git repository);
• tudat-multidoc, where the documentation and the system to build the API is located (this is a separate git repository);
• cli, where the Python Command Line Interface scripts to build the API are located;

In addition, once the project is built, all the build output will be dumped in the cmake-build-debug directory, which is not tracked by Git. If the API is also built, more untracked directories will appear, but this is explained in the tudat-multidoc/README.md file.

Prerequisites

• [Windows Users] Windows Subsystem for Linux (WSL)
  • All procedures, including the following prerequisite, assume the use of WSL. Power users who wish to do otherwise, must do so at their own risk, with reduced support from the team.
  • Note that WSL is a, partially separated, Ubuntu terminal environment for Windows. Anaconda/Miniconda, Python and any other dependencies you require while executing code from the tudat-bundle, must be installed in its Linux version via the Ubuntu terminal. This does not apply to PyCharm/CLion however, which can be configured to compile and/or run Python code through the WSL.
  • Note that, to access files and folders of WSL directly in Windows explorer, one can type \\wsl$ or Linux in the Windows explorer access bar, then press enter.
  • At the opposite, please follow this guide to access Windows file trough WSL.
  • This guide from Microsoft contains more information on the possibilities given trough WSL.
  • In the Ubuntu terminal environment under WSL, run the command sudo apt-get install build-essential to install the necessary compilation tools
• Anaconda/Miniconda installation (Installing Anaconda)
• CMake installation
  • Inside the Ubuntu terminal, install CMake by calling sudo apt install cmake.

Setup

1. Clone the repository and enter directory

git clone https://github.com/tudat-team/tudat-bundle
cd tudat-bundle

Note
The tudat-bundle repository uses git submodules, which "allow you to keep a Git repository as a subdirectory of another Git repository" (from the Git guide). In particular, in the tudat-bundle there are four different subdirectories that are separate repositories: tudat, tudatpy, tudat-multidoc and tudat-multidoc/multidoc. Each repository has its own branches and functions separately from the others. This is the reason why the following two steps are needed.

2. Clone the tudat & tudatpy submodules

git submodule update --init --recursive

3. Switch tudat & tudatpy to their desired branches using

cd <tudat/tudatpy>
git checkout <branch-name>

We recommend working with the develop branches (tudatpy/develop, tudat/develop), as they receive frequent updates and are the ones used to build the Conda packages.

4. Install the contained environment.yaml file to satisfy dependencies

conda env create -f environment.yaml

It is possible that the creation of the environment will 'time out'. A likely reason for this is that the packages required cannot be found by the current channel, conda-forge. It is then advisable to add the channel anaconda to ensure a proper creation of the environment.

There are two directions you can go from here: the command line or CLion.

Build & Install: Command line

5. Activate the conda environment

conda activate tudat-bundle

6. Build Tudat and TudatPy

This script will compile the C++ source code of Tudat into libraries. The process will take some time, but you can speed it up using the option -j and the number of cores you want to allocate to it.

python build.py -j <number-of-cores>

You can further adjust the behavior of build.py with additional command line arguments. Running python build.py -h will give you a list with all the available options.

7. Install

Building the libraries from source is conceptually equivalent to manually downloading them as a zip file: you do have the code, but Conda is not aware of it, so you will get an error if you try to import it. The following script creates links to the files generated by build.py in the place where Conda will look for them or, in other words, installs your libraries in your Conda environment.

python install.py

If you know about PIP's editable installs, that is exactly what install.py does. If you don't, just know that there is no need to reinstall the libraries when you recompile them or modify the Python source, your environment is automatically updated every time you modify a file.

If you ever want to uninstall the libraries, just run python uninstall.py. Note that this will not eliminate the build itself, but just remove it from your Conda environment.

Alternative build: CLion

Note

• [Windows Users ∩ CLion Users] In CLion, be sure to set WSL as your Toolchain in File>Settings>Build, Execution, Deployment>Toolchains.

• [CLion Users] In CLion, the convention to set CMake arguments is to add them to File>Settings>Build, Execution, Deployment>CMake Options.

5. Open CLion, create a new project from File > New Project and select the directory that has been cloned under bullet point 1 (named tudat-bundle).

Note
To avoid issues with CLion, the directory of the project should correspond exactly to the cloned directory named tudat-bundle.

6. Create a build profile in File > Settings > Build, Execution, Deployment > CMake.

Note
The CMake configuration option CMAKE_BUILD_TYPE will be determined by the the build profile's Build type entry. A Release configuration will suppress a significant amount of harmless warnings during compilation. Currently, with the move to a later version of boost, some warnings have cropped up that have either not been fixed in the source code, or have not been suppressed via tudat/cmake_modules/compiler.cmake.

7. Add the CMake configuration to the File > Settings > Build, Execution, Deployment > CMake > CMake options text box:

-DCMAKE_PREFIX_PATH=<CONDA_PREFIX>
-DCMAKE_CXX_STANDARD=14
-DBoost_NO_BOOST_CMAKE=ON

The CONDA_PREFIX may be determined by activating the environment installed in step 4 and printing its value:

conda activate tudat-bundle && echo $CONDA_PREFIX

The following line can also be edited if you wish to build tudatpy with its debug info (switching from Release to RelWithDebInfo; note that Debug is also available):

-DCMAKE_BUILD_TYPE=RelWithDebInfo

[Optional] Add -j<n> to File > Settings > Build, Execution, Deployment > CMake > Build options to use multiple processors. It is likely that if you use all of your processors, your build will freeze your PC indefinitely. It is recommended to start at -j2 and work your way up with further builds, ensuring no unsaved work in the background.

8. In the source tree on the left, right click the top level CMakeLists.txt then Load/Reload CMake Project.

9. Build > Build Project

Alternative build: VSCode

This section explains how to configure VSCode with CMake presets to build and manage your tudat build. The configuration supports parallel builds, switching between Debug and Release modes, enabling/disabling tests, and cleaning build directories.

Requirements

1. VSCode with the following extensions:

   • CMake Tools
   • C++ Extension

2. CMake installed on your system (minimum version 3.19).

3. Conda environment for managing dependencies.

4. Make/Ninja installed based on your operating system for build generation.

Steps to Configure VSCode

1. Create the CMakePresets.json file in the root directory of your project. Use the following template with necessary adjustments:

{
  "version": 3,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 19,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "default",
      "hidden": false,
      "generator": "Unix Makefiles", // Set this based on the OS: "Unix Makefiles" for Linux/macOS, "Ninja" or "Visual Studio" for Windows
      "binaryDir": "${sourceDir}/build", // Build directory
      "cacheVariables": {
        "CMAKE_PREFIX_PATH": "/path/to/your/conda/environment", // <--- CHANGE THIS: Set this to your conda environment or other toolchain path
        "CMAKE_INSTALL_PREFIX": "/path/to/your/conda/environment", // <--- CHANGE THIS
        "CMAKE_CXX_STANDARD": "14", // The C++ standard to use
        "Boost_NO_BOOST_CMAKE": "ON", // Ensures that the system-installed Boost CMake files are not used
        "CMAKE_BUILD_TYPE": "Release", // Default to Release build
        "TUDAT_BUILD_TESTS": "ON" // Set to ON to build tests by default
      }
    },
    {
      "name": "debug",
      "inherits": "default",
      "description": "Debug build configuration",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug" // Use Debug mode for this preset
      }
    },
    {
      "name": "no-tests",
      "inherits": "default",
      "description": "Build without tests",
      "cacheVariables": {
        "TUDAT_BUILD_TESTS": "OFF" // Disable test building in this preset
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "hidden": false,
      "configurePreset": "default", // Use the default configuration preset
      "jobs": 8, //<--- CHANGE THIS: Parallel build with N cores
      "targets": [
        "all" // Build the default target (usually all)
      ]
    },
    {
      "name": "debug-build",
      "configurePreset": "debug", // Use the debug configuration preset
      "jobs": 8, //<--- CHANGE THIS: Parallel build with N cores
      "targets": [
        "all"
      ]
    },
    {
      "name": "build-no-tests",
      "configurePreset": "no-tests", // Use the no-tests configuration preset
      "jobs": 8, //<--- CHANGE THIS: Parallel build with N cores
      "targets": [
        "all"
      ]
    },
    {
      "name": "clean",
      "configurePreset": "default",
      "jobs": 8, //<--- CHANGE THIS: Parallel build with N cores
      "targets": [
        "clean" // Run the clean target
      ]
    }
  ]
}

Comments on the Configuration

• CMAKE_PREFIX_PATH: Set the CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX to your tudat-bundle environment. This is critical to ensure CMake can find the necessary libraries and dependencies.

• Generator: Depending on your OS, the generator should be:

  • "Unix Makefiles" for macOS and Linux.
  • "Ninja" for Windows (if Ninja is installed).
  • "Visual Studio" for Windows if using Visual Studio.

• Parallel Jobs: The jobs key is used to specify the number of jobs for parallel builds. Set the number of cores to be used for the build.

• Presets:

  • default: Builds the project in Release mode with tests.
  • debug: Builds the project in Debug mode.
  • no-tests: Builds the project without tests.
  • clean: Cleans the build directory.

How to Use Presets in VSCode

1. Open VSCode in your project directory.

2. Open the Command Palette (F1 or Ctrl+Shift+P) and run the command CMake: Select Configure Preset.

3. Choose one of the configure presets:

   • default: for Release builds.
   • debug: for Debug builds.
   • no-tests: to skip building tests.

4. Once configured, run the command CMake: Select Build Preset from the Command Palette, and choose one of the build presets:

   • default: to build the project.
   • debug-build: to build in Debug mode.
   • build-no-tests: to build without tests.
   • clean: to clean the build directory.

5. To start the build, run CMake: Build from the Command Palette or use the build button in the status bar.

Troubleshooting

• CMake Errors: If CMake cannot find dependencies, check that the CMAKE_PREFIX_PATH and CMAKE_INSTALL_PREFIX are set correctly in the CMakePresets.json file.
• Wrong Generator: If the build fails due to an unsupported generator, change the "generator" field in the preset to match your OS and toolchain.

Verify your build

Running tudat tests

1. Enter the tudat build directory

cd <build_directory>/tudat

2. Run the tests using ctest (packaged with CMake)

ctest

Desired result:

..
100% tests passed, 0 tests failed out of 224
Total Test time (real) = 490.77 sec

Running tudatpy tests

1. Enter the tudatpy build directory

cd <build_directory>/tudatpy

2. Run the tests using pytest

pytest

Desired result:

=========================================== 6 passed in 1.78s ============================================

C++ Code Formatting with Clang-Format

tudat-bundle uses clang-format to enforce a consistent code style. The configuration file is located in the root of the repository as .clang-format.

Prerequisites

Ensure clang-format is installed. You can check the installation by running:

clang-format --version

If it's not installed, install clang-format using a package manager:

• On Ubuntu/Debian: sudo apt install clang-format
• On macOS: brew install clang-format
• On Windows: Download and install from LLVM's official site.

Configuration File

This .clang-format file configures formatting settings, including indentation width, brace wrapping, spacing rules, and alignment settings. These settings will ensure your code remains organized, readable, and consistent with tudat code style.

Usage

1. Running Clang-Format on a Single File

To format a single file, run:

clang-format -i path/to/your/file.cpp

The -i flag formats the file in place.

2. Running Clang-Format on Multiple Files

To format all .cpp and .h files in your project directory:

find path/to/your/project -name '*.cpp' -o -name '*.h' | xargs clang-format -i

Alternatively, if you're using an IDE like Visual Studio Code, you can configure it to automatically format on save.

3. Setting Up Automatic Formatting in VSCode

If you’re using Visual Studio Code, you can automate code formatting:

1. Install the Clang-Format extension from the marketplace.
2. Open your project’s Settings (File > Preferences > Settings).
3. Search for Clang-Format and set the path to your .clang-format file.
4. Enable Format on Save by setting "editor.formatOnSave": true in your settings.json.

4. Checking Format Without Applying

To preview formatting changes without modifying files, run:

clang-format -output-replacements-xml path/to/your/file.cpp

This will show XML output if there are any format issues. You can then decide to apply formatting manually.