project-structure

name	project-structure
description	Overview of the main directories and important files in the repository. Use this to understand the project layout and find where code lives.

Project Structure Guide

Overview of the main directories and important files in the repository.

Top-Level Directories

• apps/ - C++ apps, benchmarks, examples, and tests (see apps/CMakeLists.txt).
• assets/ - Scene assets and simulation data.
• cmake/ - Shared CMake utilities and macros.
• docs/ - Documentation, specs, and site assets.
• external/ - Third-party dependencies (e.g., external/muda/).
• include/ - Public C++ headers.
• output/ - Generated outputs from simulations. (the contents is ignored by git)
• python/ - Python package, tests, and metadata.
• scripts/ - Utility scripts and notebooks.
• src/ - Core C++ implementation.
• xmake/ - XMake rules and build helpers.

Subfolder Purposes

apps/

• app/ - Shared app utilities and test helpers.
• benchmarks/ - Benchmark executables.
• examples/ - Example applications (each in its own subfolder).
• tests/ - C++ test suites grouped by feature area.

assets/

• scenes/ - Scene README and references.
• sim_data/ - Mesh assets (linemesh/, tetmesh/, trimesh/).

docs/

• build_install/ - Build and install guides.
• development/ - Developer docs and diagrams.
• specification/ - API/spec references and constitutions.
• tutorial/ - Tutorial content and media.
• overrides/ - MkDocs HTML overrides.
• stylesheets/ - Docs CSS.
• javascripts/ - Docs JS.
• media/ - Images for docs pages.
• misc/ - Miscellaneous documentation.

external/

• muda/ - Third-party CUDA/math dependency (source + docs + tests).

include/

• uipc/ - Public headers grouped by module (backend, core, geometry, io, etc.).
• uipc_gui/ - Public GUI-related headers. (now not supported)

python/

• src/uipc/ - Pure python code to enhance the C++ pybind11 bindings.
• tests/ - Python test suite.

scripts/

• optional_import/ - Optional dependency loaders.
• symbol_calculation/ - Symbolic derivation notebooks and helpers.
• SymEigen/ - SymEigen utilities, notebooks, and tests.

src/

• backends/ - Backend implementations (common/, cuda/, none/).
  • common/ - Common utilities for all backends.
  • cuda/ - CUDA backend with CUDA kernels.
  • none/ - An empty backend that does nothing, as a template for creating a new backend or checking the basic functionality.
• constitution/ - Physical constitution implementations.
• core/ - Core engine systems and modules.
• geometry/ - Geometry algorithms and data types.
• gui/ - GUI runtime components. (now not supported)
• io/ - Serialization and I/O.
• pybind/ - C++/Python bindings.
• sanity_check/ - Internal scene sanity checks to ensure the correctness of scene before the simulation.
• usd/ - USD integration.
• vdb/ - VDB integration.