Installation guide

Installing the full development environment

Cloning the repository

Click the green “Code” button at the top right of the homepage for the repository. Make sure the HTTPS tab is selected, copy the https address, then on your system navigate to the directory where you want to keep the code. Type the command (in Git Bash for Windows, or terminal for Linux/Unix/Mac):

git clone https://github.com/butchertx/variationalMC.git

This will copy the variationalMC directory into your current working directory.

Install Intel oneAPI

Get the Intel oneAPI toolkit [here](https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html). Download the correct version for the platform you’re working on. Development on this project is primarily supported for Linux/WSL, but the setup is intended to be flexible enough for cross-platform work. These instructions were written for the 2025.1.0 version of the Intel oneAPI Base Toolkit built on Ubuntu-22.04 within WSL.

When you have downloaded the installer, follow the instructions on the Intel webpage (linked above) to install and configure your system. Once it is installed, the main action for configuration is adding the oneAPI configuration script to your .bashrc file. This will configure the environment variables that are needed for compiling using the Intel compilers. Add the following line at the end of the file ~/.bashrc:

source /opt/intel/oneapi/2025.1/oneapi-vars.sh

If using a different version of the oneAPI toolkit, be sure to replace the “2025.1” with whichever version is installed. You can view the installed versions with the command

ls /opt/intel/oneapi

Install the build dependencies via conda

The build system uses cmake, and the documentation is built using sphinx and doxygen. To install all of the build dependencies together, it is easiest to use conda. If you have conda installed, the recommended way to do this is to create a new conda environment. This conda environment is specified in the doc/conda.yml file (from the root directory of the repository). To create the conda environment, run the following command from the root of the repository in the terminal:

conda env create -f doc/conda.yml

Then, activate the environment with:

conda activate vmc_build

If this doesn’t work, you can also try building an environment manually using doc/requirements.txt.

Pull in Gtest for testing

download the googletest repository from git: * recommended method is navigate to the [googletest Github repository](https://github.com/google/googletest), click “Code” in the top right, and choose “Download Zip”
On WSL:Ubuntu, I run the following commands to pull in the .zip from the default download location and unzip it:

cd ~/projects/variationalMC
mkdir -p thirdparty
cd thirdparty
cp /mnt/c/Users/Matthew/Downloads/googletest-main.zip .
unzip googletest-main.zip -d .

The result should be the following directory structure: thirdparty/googletest-main/..., where ... are the files in the root directory of the googletest repository.

Optional: Set up VS Code as your IDE

This is the recommended IDE setup because it comes with extension support for CMake, testing, and C++ language features. It also has a RemoteSSH extension that will allow you to work through the same interface on a remote host (compute cluster). With the variationalMC directory open in VS Code, do the following:

Install the following extensions:

C/C++
CMake Tools

Configuration

Configure the CMake extension settings. You can get the cmake path by typing which cmake in the terminal. If .vscode/settings.json does not exist, create it and populate it with the following:

{
    "cmake.cmakePath": "/usr/bin/cmake",
    "cmake.configureOnOpen": true,
    "cmake.buildDirectory": "${workspaceFolder}/build",
    "cmake.debugConfig": {
        "MIMode": "gdb",
        "miDebuggerPath": " /opt/intel/oneapi/debugger/2025.1/bin/gdb-oneapi"
    }
}

If the settings.json file already exists, just add the above options alongside any other options already in there.

Press Ctrl+Shift+P and Select “Edit User-Local CMake kits” (start typing it and VSCode will search for it). Add the following configuration to the resulting .json file:
{ "name": "Intel oneAPI", "compilers": { "C": "/opt/intel/oneapi/compiler/2025.1/bin/icx", "CXX": "/opt/intel/oneapi/compiler/2025.1/bin/icpx" }, "isTrusted": true }
Optional: delete the default configuration(s) that was already in this file.