project-structure

# 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. - `include/` - Public C++ headers. - `output/` - Generated outputs from simulations. (the contents is ignored by git) - `python/` - Python package, tests, and metadata. - `libuipc-samples/` - Tracked git submodule containing Python examples, benchmarks, and sample assets. - `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. ### `include/` - `uipc/` - Public headers grouped by module (backend, core, geometry, io, etc.). The removed C++ GUI has no public header tree. ### `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. - `geometry/metis/` - Private C++ METIS implementation and required GKlib-derived support code, built as `uipc_metis` for mesh partitioning. - `constitution/` - Physical constitution implementations. - `core/` - Core engine systems and modules. - `geometry/` - Geometry algorithms and data types. - `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. The supported visualization frontend is the pure-Python polyscope layer at `python/src/uipc/gui.py`. CMake is the primary and wheel-tested build. XMake mirrors the active optional USD/VDB targets, disables ccache, and synchronizes pybind staging before packaging. Remaining dependency-version differences are documented in [the build guide](../../../agent_docs/07-build-test-workflow.md) and [the secondary-module guide](../../../agent_docs/12-secondary-modules-samples-and-docs.md).