Skip to content

Building the CUDA core

Details behind Installation. Users of the PyPI wheel rarely need them.

Which core is loaded

The wheel ships a prebuilt CUDA core, so the compiled backend (impl='c') works right after install, with any PyTorch version: nothing compiles, no nvcc, no C++ compiler. The core matching your torch's CUDA major is loaded:

Core GPUs
cu12 V100 (sm_70) through H100/H200; Blackwell through PTX
cu13 T4 / RTX 20 (sm_75) through Blackwell (native); driver >= 580, as torch cu130 needs

A V100 needs a torch built for CUDA 12 (nvcc 13 cannot target sm_70). The eager PyTorch and JAX backends are pure Python and need no core.

The core links cuFFT at run time. Torch's pip CUDA wheels bring it; if yours did not (conda torch, a CPU wheel plus a system driver), add it with pip install "sweep-solver[cuda12]" (or [cuda13], matching your core).

When nvcc is needed

Only when no shipped core fits (a torch built for a CUDA major with no core, or a GPU older than the shipped architectures, e.g. Pascal) or when installing from source. Then the core alone is built locally, once: 2–5 min, on the first impl='c' call or with python -m sweep.build. It is cached under TORCH_EXTENSIONS_DIR/sweep_C/core/ (default ~/.cache/torch_extensions/...) and reused by later runs without nvcc. Use an nvcc of your torch's CUDA major:

= 12.4 for CUDA 12 (>= 12.8 to target Blackwell; SWEEP_JIT_ALLOW_OLD_CUDA=1 tries 12.0–12.3), or any CUDA 13 nvcc.

Installing from source

A clone carries no prebuilt core; building one needs only nvcc (no torch headers, no C++ compiler). PropTorch(...) picks impl='c' when it can run and falls back to "eager" otherwise; which equations have a compiled implementation is in the impl="c" column of Equations. The JAX backend (PropJax) needs a working JAX install; SWEEP imports it lazily, only when used.

Building where there is no GPU

A local core build needs nvcc and a target architecture, not a card. On a CPU node (CI, or a CPU allocation on a cluster), name the arch and a cache directory:

TORCH_CUDA_ARCH_LIST=7.0 TORCH_EXTENSIONS_DIR=/scratch/ext python -m sweep.build --no-gpu-required

Point the GPU job at the same TORCH_EXTENSIONS_DIR and it starts without compiling, and without nvcc: a source stamp beside the core says it matches the tree and the target.

The host (CPU) core

The same csrc/ tree compiled by g++ instead of nvcc serves impl='c' on a CPU device, for impl='auto' as for an explicit impl='c'. It needs a C++17 compiler with OpenMP (g++ >= 9 or clang++ >= 10; CXX overrides) and ninja — no nvcc, no torch headers, no GPU:

python -m sweep.build --cpu

builds it once into TORCH_EXTENSIONS_DIR/sweep_C/core_cpu/ (2–3 min). Without it, the first CPU construction with impl='auto' builds the same core (the compiler's output kept in build.log there; a failed build warns once and that process runs eager), and so does the first impl='c' call. SWEEP_CORE_CPU=<path> points at a core built elsewhere; python -m sweep.build --cpu --core files one under sweep/lib/cpu/ with its core.json for a wheel. ViscoAcoustic (cuFFT) and the equations not ported yet (ElasticBorn, the qP equations, the SEM kernels; sweep.backend.c.hostcore.HOST_UNPORTED) are not built into it: on a CPU device impl='c' falls back to eager with a warning for them (PropSEM refuses impl='c' off CUDA, as it always has). Architecture, numerics and the kernel rules are in The host (CPU) core.

Diagnostics

sweep list equations
import sweep
print(sweep.is_torch_binding_available())          # can impl='c' run on CUDA here? builds nothing
print(sweep.backend.torch.binding.diagnostics())   # why or why not, which core, which shim; ["host_core"] for the CPU

sweep.precompile() loads the core up front (building it first when none fits) and raises a clear error if the GPU, or nvcc when needed, is missing. It is optional: the first impl='c' call does the same.

Advanced

  • Custom core: SWEEP_CORE=<path/to/libsweep_core.so>. A core.json beside it gets the same fit check as a shipped core (ABI, CUDA major, architectures).
  • Developer builds of the pybind shim: same kernels and results as the default ctypes layer, but tied to the torch they are built against.
    • SWEEP_JIT_FULL=1 builds it with the JIT loader on first use (torch's C++ headers, a C++ compiler and the CUDA runtime headers).
    • SWEEP_BUILD_CUDA=1 pip install -v ".[cuda]" --no-build-isolation builds it ahead of time from a clone, as a sweep._C extension that takes precedence over the ctypes layer (nvcc, a C++ compiler and torch's headers; set TORCH_CUDA_ARCH_LIST to your card and have ninja on PATH).
    • sweep.backend.torch.binding.diagnostics()["shim"] reads "pybind" for either.
  • Release cores: how the wheel's cores are built is in Release cores.