SpECTRE  v2024.12.16
Code development quick-start with Docker and Visual Studio Code

Table of Contents

This page describes how to get started developing SpECTRE on Mac, Linux, or Windows using Docker and the Visual Studio Code editor. This is a particularly quick way to get up and running with SpECTRE code development, though of course not the only way. If you prefer setting up your development environment differently, we suggest you read the Installation page. If you would like to jump right into a working development environment, read on!

Fork the SpECTRE repository on GitHub

The SpECTRE code lives on GitHub in the sxs-collaboration/spectre repository. Developers work on their own copy (or "fork") of the repository and contribute back to sxs-collaboration/spectre through pull requests. Fork the repository to your own account:

Clone the SpECTRE repository to your computer

To work on SpECTRE code you will need a local copy (or "clone") of the repository on your computer. We use SSH to communicate with GitHub, so you need to set up your SSH keys first. Follow GitHub's instructions to generate an SSH key and add it to your GitHub account:

Now you can download the repository via SSH. Navigate to your fork of the SpECTRE repository (i.e. the repository at the URL https://github.com/YOURNAME/spectre). Follow GitHub's instructions to clone the repository to your computer, selecting the SSH option:

Note
If you clone the SpECTRE repository using HTTPS instead of SSH, you won't be able to push any changes you make to your fork. You'll still be able to make local changes on your computer, but you won't be able to share your changes with anybody.

Install Docker

On your computer you will need Docker to run the containerized development environment. Install and start Docker:

If you're new to Docker, you can read through Docker's Getting started documentation to learn about their basic concepts. We will use Docker to download and jump into a prebuilt development environment that has everything installed to compile and run SpECTRE.

Install Visual Studio Code

We will use the Visual Studio Code editor to jump into the containerized development environment, edit code, compile executables and run them. Download and install Visual Studio Code:

Microsoft maintains extensive documentation for Visual Studio Code that you can read to get started using the editor. We recommend you take a look through the Tips and Tricks to get an idea of the editor's features.

Install the "Remote - Containers" extension

Visual Studio Code's "Remote - Containers" extension lets you run the editor in a Docker container. Install the extension:

Open the SpECTRE repository in Visual Studio Code

Now open the SpECTRE repository that you have cloned to your computer in Visual Studio Code. Depending on your operating system you can select File > Open, type Cmd+O (macOS) or Ctrl+O (Linux or Windows), drag the repository folder onto the Visual Studio Code icon or any other means to open the folder in Visual Studio Code.

Now is also time to learn how to use the single most important tool in Visual Studio Code, the command palette. Try it now: Hit Cmd+P (macOS) or Ctrl+P (Linux or Windows) and start typing the name of any file, for example QuickStartDockerVSCode.md. Hit Enter to open the file. This is how you can quickly open any file in the repository. Note that the search is fuzzy, so you can type any few letters in the path to the file. In addition to opening files, you can hit Cmd+Shift+P (macOS) or Ctrl+Shift+P (Linux or Windows) and type the name of any command that Visual Studio Code supports (or parts of it), for example Preferences: Open User Settings.

Reopen the SpECTRE repository in the development container

Open the command palette by hitting Cmd+Shift+P (macOS) or Ctrl+Shift+P (Linux or Windows) and run the command Remote-Containers: Reopen in container by starting to type a few letters of this command and then hitting Enter.

Visual Studio Code will download and run the container and drop you into a fully configured environment where you can proceed to compile and run SpECTRE. This may take a few minutes so just let VSCode run and do it's thing. There may be a show logs button somewhere on your screen if you're interested in the details of the download.

If you are interested to learn more about how this feature works you can read through the VS Code documentation on remote containers and inspect the .devcontainer/devcontainer.json file that's included in the SpECTRE repository.

Note
If you look into the .devcontainer/devcontainer.json file, you'll see we are using the sxscollaboration/spectre:dev container. We also offer other containers. The sxscollaboration/spectre:ci container has more compilers and the sxscollaboration/spectre:demo container has a couple pre-built executables. If you'd like to build in a different container, just switch the image name in the json file and reopen in the new container.

Configure, compile and run SpECTRE

With Visual Studio Code running in the development container you can now configure, compile and run SpECTRE with no additional setup. Hit Cmd+Shift+P (macOS) or Ctrl+Shift+P (Linux or Windows) to open the command palette and run the command CMake: Select a Kit. You should see a Default kit available. Then, open the command palette again, run CMake: Select Variant, and select either Release or Debug. For this tutorial we recommend using Release. If you want to actually develop SpECTRE, the Debug option would be better. This specific kit uses clang to build SpECTRE along with the Python bindings. Finally, open the command palette once more and run CMake: Configure which will now actually run CMake.

It will set up a build directory. You can open Visual Studio Code's integrated terminal with the keyboard shortcut Ctrl+` and navigate to the newly created build directory to inspect it:

cd build-Default-Debug

For compiling and running SpECTRE you can either use Visual Studio Code's CMake integration by looking up further commands in the command palette, or use the terminal. We will be using the terminal from now on. Try compiling an executable, for example:

make -j4 ExportCoordinates3D

Once the executable has compiled successfully you can try running it:

./bin/ExportCoordinates3D \
--input-file $SPECTRE_HOME/tests/InputFiles/ExportCoordinates/Input3D.yaml

This executable produced a volume data file in the build-Default-Debug directory that we can visualize in ParaView. Generate an XMF file from the volume data file that ParaView understands:

./bin/spectre generate-xdmf \
--file-prefix ExportCoordinates3DVolume --subfile-name element_data \
--output ExportCoordinates3DVolume

Since the build directory is shared with the host file system you can now open ParaView on your computer and load the generated XMF file as described in the visualization tutorial.

Note
If you wanted to run this executable again, you'd have to first remove the existing .h5 files, otherwise an error will occur.

Edit and contribute code to SpECTRE with VS Code

You are now ready to code! The other dev guides will teach you how to write SpECTRE code. Return to the Visual Studio Code documentation to learn more about editing code with Visual Studio Code.

In particular, the Visual Studio Code documentation can teach you how to use Git to commit your code changes to your repository:

SpECTRE code development follows a pull-request model. You can learn more about this process in our contributing guide:

Visual Studio Code can also help you create and review pull requests:

Interactively debug a SpECTRE test with VS Code

To track down an issue with your code it can be very useful to interactively debug it. First, make sure you have written a test case where the issue occurs. If you have not written a test yet, this is a great time to do it. Refer to the Writing Unit Tests dev guide to learn how to write tests.

To launch the interactive debugger, hit Cmd+Shift+P (macOS) or Ctrl+Shift+P (Linux or Windows) to open the command palette, run the command CMake: Set Debug Target and select your test executable (e.g. Test_LinearOperators) Then run the command CMake: Debug. The test executable will compile, run and stop on any breakpoints. Follow the Visual Studio Code documentation to learn how to set breakpoints in your code and inspect the state of your variables:

Real-time collaboration with Live Share

You can use the Live Share extension to work together with others and edit code simultaneously. Live Share can be very useful to debug code together. Follow these instructions to share a link to your current Visual Studio Code workspace:

Tips and tricks

  • The GitLens extension is very useful to browse your repository. Select the "Source Control" icon and explore the various panels.

  • When you build the documentation (e.g. with make doc), you can open it in a web server within VS Code:

    python3 -m http.server -d docs/html

    The web server launches on port 8000 by default, which is being forwarded outside the container, so you can just open http://127.0.0.1:8000 in your browser to view the documentation.

  • Instead of working in the Docker container, you can use the Remote - SSH extension to work on a remote machine such as your local supercomputing cluster. Ask the cluster administrators or users for suggestions concerning installing and running SpECTRE on the particular supercomputer.

  • You can work with Jupyter notebooks in Visual Studio Code. First, install Jupyter and all other Python packages you want to work with in the container:

    pip3 install jupyter matplotlib

    Any .ipynb notebook files you create or open will be displayed in VS Code's notebook editor. This is very useful for quickly plotting data from SpECTRE runs or using SpECTRE's Python bindings. Refer to the VS Code documentation on Jupyter support for more information.

  • Docker can quickly use up a lot of disk space. From time to time you can "prune" unneeded images and containers to reclaim disk space:

    When pruning containers, make sure no data is deleted that you care about!