WoSX is a C++17 header-only library, with GPU support and Python bindings, for solving partial differential equations with Walk on Spheres-style Monte Carlo methods. It is designed for problems where creating a volume mesh is awkward, expensive, or unnecessary: the solver queries the original boundary representation directly and estimates the solution only where values are needed.

WoSX is forked from Zombie, and has equivalent CPU functionality. This repository builds on that foundation with GPU support and demo applications that show how the same ideas apply to complex 2D and 3D geometries.

WoSX is research software. The algorithms are still an active area of research, and the implementations are meant to be clear reference implementations rather than final word on performance or variance reduction. For a broader introduction to Walk on Spheres and its recent extensions, see this overview talk and this webpage for in-depth resources such as recent publications and tutorials.

The best way to get started is through the demo applications in demo_apps/:

Thermal Conduction	Electrostatics	Potential Flow

• basic_2d: compact 2D reference problems for Laplace, Poisson, screened Poisson, and multiple solvers.
• thermal_conduction: thermal rendering on a complex Mars rover mesh with textured boundary data.
• electrostatics: moving comb-drive electrostatics with interactive electric potential and field visualization.
• potential_flow: exterior potential flow around complex 3D shapes.
• geometric_deformation: Coming soon!

Each demo has its own README with the problem setup, expected outputs, and C++ and Python run commands.

Most WoSX applications follow the same high-level workflow:

1. Define geometric queries for the domain boundary, such as distance, intersection, and projection queries.
2. Define PDE data: source term, screening, and Dirichlet, Neumann, or Robin boundary conditions.
3. Choose sample/evaluation points where the solution and its spatial gradient should be estimated.
4. Choose a solver, run the random walks, and write or visualize the resulting values.

The same conceptual workflow applies in C++ and Python, and on CPU and GPU. The CPU API uses ordinary C++ objects and callbacks. The GPU API packages the same ideas into GPU task handles, shader resources, and PDE definitions in the Slang Shading Language.

WoSX targets scalar and vector-valued PDEs in 2D and 3D, including Laplace, Poisson, and screened Poisson equations. Boundary conditions may be mixed across the same boundary:

• Dirichlet: prescribed solution value.
• Neumann: prescribed normal derivative.
• Robin: linear combination of solution value and normal derivative.

Screened Poisson problems currently use a constant absorption coefficient. Geometric queries are backed by FCPW, with line-segment boundaries in 2D and triangle-mesh boundaries in 3D. Exterior problems can be handled through a Kelvin transform.

Available solver families include Walk on Spheres for Dirichlet conditions, Walk on Stars for Neumann and Robin conditions, and Boundary Value Caching and Reverse Walk on Stars for noise reduction. Reverse Walk on Stars is CPU-only; the other main solvers are available through the CPU and GPU demos.

GPU support has been extensively tested with CUDA. WoSX uses Slang/RHI through FCPW, which also provides backend support for Vulkan, Direct3D, and Metal (though these backends have not been tested with WoSX).

After cloning the repository, initialize submodules:

git submodule update --init --recursive

Configure and build from the repository root:

cmake -S . -B build -DWOSX_ENABLE_GPU_SUPPORT=ON -DWOSX_BUILD_DEMO_APPS=ON
cmake --build build -j4

Use -DWOSX_ENABLE_GPU_SUPPORT=OFF for a CPU-only build. Python bindings can be enabled in CMake with -DWOSX_BUILD_BINDINGS=ON.

Install the Python package from the project root:

pip install . --force-reinstall

To build the Python bindings with GPU support:

pip install . --config-settings=cmake.define.WOSX_ENABLE_GPU_SUPPORT=ON --force-reinstall

The Python API can be inspected from a Python console:

import wosx
help(wosx)

The core WoSX library depends on the following open source software, included as submodules:

• FCPW: Fastest Closest Points in the West (MIT License)
• nanoflann (BSD License)
• oneTBB (Apache-2.0 License)
• pcg32 (Apache-2.0 License)

The demo applications depend on:

• polyscope (MIT License)
• stb (MIT License)
• nlohmann/json (MIT License)

The Python bindings are generated using nanobind (BSD License).

Rohan Sawhney

Code is released under the Apache License, Version 2.0.

Contributions and pull requests from the community are welcome. Rather than requiring a formal Contributor License Agreement (CLA), we use the Developer Certificate of Origin to ensure contributors have the right to submit their contributions to this project. Please ensure that all commits have a sign-off added with an email address that matches the commit author to agree to the DCO terms for each particular contribution.

The full text of the DCO can be found here.

@software{WoSX,
author = {Sawhney, Rohan},
title = {Walk on Spheres Extensions (WoSX)},
version = {1.0},
year = {2026}}