Skip to the content.

Running C and C++ in a Jupyter Notebook on TACC Vista

xeus-cpp gives you eight interactive kernels on Vista: C11, C17, C23, C++17, C++20, C++23, and OpenMP variants of C23 and C++23. Cells compile and run immediately, no sbatch, no wait.

The conda package installs cleanly but does not work out of the box on Vista. It needs three fixes the upstream docs do not mention. All three are in setup-kernels.sh; this page explains what they are and why, so the next person can debug it.

What it is good for

Teaching. A student can run #pragma omp parallel for and watch the thread count change, interactively, instead of learning the compile-submit-wait loop on day one.

It is not how real work runs. It is an interpreter, single-process. Compiled optimization and MPI are outside its scope. OpenMP shares memory within one node; MPI passes messages between nodes and needs ibrun, so it cannot run in a notebook kernel at all.

Install

unset PYTHONPATH
source $WORK/miniforge3/etc/profile.d/conda.sh

conda create -y -n xcpp -c conda-forge xeus-cpp
conda install -y -n xcpp -c conda-forge clang=21 libstdcxx-devel_linux-aarch64
conda activate xcpp

Light enough (~100 MB, ~35 packages) to run on a login node, unlike the R environment.

Then the three fixes.

Fix 1: copy the kernelspecs to $HOME

xeus-cpp registers its kernels inside the conda env, at $CONDA_PREFIX/share/jupyter/kernels/. The Jupyter server launched by TAP is a different Python entirely and never looks there.

cp -r $CONDA_PREFIX/share/jupyter/kernels/* ~/.local/share/jupyter/kernels/

A plain copy is safe here because xeus-cpp writes absolute paths into argv. Some kernels write a bare command name, which breaks on copy; this one does not.

Fix 2: install the compiler headers

A fresh xeus-cpp env has neither the clang resource directory nor the C++ standard library headers. $CONDA_PREFIX/lib/clang/ does not exist at all. The symptom is confusing, because the #include lines fail silently and you only see the downstream damage:

error: use of undeclared identifier 'std'

clang=21 supplies the resource directory (it must be 21 to match the path baked into the kernelspecs). libstdcxx-devel_linux-aarch64 supplies the C++ headers, but puts them somewhere clang does not search:

$CONDA_PREFIX/lib/gcc/aarch64-conda-linux-gnu/<gcc-version>/include/c++/

Fix 3: add the header paths to the kernelspecs

Because of where fix 2 put the headers, each C++ kernelspec needs three -I flags appended to argv:

<base>/include/c++
<base>/include/c++/aarch64-conda-linux-gnu
<base>/include/c++/backward

Do not hardcode the gcc version; it moves. setup-kernels.sh globs for it.

Optional: raise the OpenMP thread count

TACC sets OMP_NUM_THREADS=1 in the default environment to stop jobs from oversubscribing nodes, and the kernel inherits it. Every OpenMP demo will report one thread until you override it.

Add an env block to the two *omp kernelspecs:

"env": { "OMP_NUM_THREADS": "16" }

Or call omp_set_num_threads(16); at runtime in a cell, which is arguably better for teaching since students see the number change.

Two rules students will hit in the first ten minutes

Put both in the handout.

1. OpenMP pragmas must be inside a function. The interpreter treats a cell as global scope, and a pragma there is a hard error:

error: unexpected OpenMP directive '#pragma omp parallel'

Wrong:

#pragma omp parallel
{ ... }

Right:

void show_threads() {
    #pragma omp parallel
    {
        #pragma omp single
        std::cout << "threads: " << omp_get_num_threads() << std::endl;
    }
}

then call show_threads(); in the next cell.

2. After any compilation error, restart the kernel. xeus-cpp does not recover from a failed parse. Subsequent cells fail with unrelated-looking errors (typically use of undeclared identifier) because earlier #includes never took effect. Editing and re-running does not help. Restart.

Verifying

#include <iostream>
std::cout << "hello, " << __cplusplus << std::endl;

201703 for C++17, 202002 for C++20, 202302 for C++23.

OpenMP, three separate cells:

#include <omp.h>
#include <iostream>
void show_threads() {
    #pragma omp parallel
    {
        #pragma omp single
        std::cout << "threads: " << omp_get_num_threads() << std::endl;
    }
}
omp_set_num_threads(16);
show_threads();

Troubleshooting

Symptom Cause Fix
use of undeclared identifier 'std' Headers missing, or a previous cell failed to parse Fixes 2 and 3; restart the kernel
unexpected OpenMP directive Pragma at global scope Wrap it in a function
Kernels absent from the picker Kernelspecs still inside the conda env Fix 1, then restart the Jupyter server
threads: 1 TACC’s OMP_NUM_THREADS=1 omp_set_num_threads(n) or an env block
Errors persist after fixing the code Interpreter state poisoned by an earlier failure Restart the kernel