### Install mkdocs and plugins

Source: https://spirimirror.github.io/libuipc-doc/build_install/build_docs

Installs the required Python packages for building the documentation: mkdocs, mkdocs-material, mkdocs-literate-nav, mkdoxy, and mkdocs-video.

```bash
pip install mkdocs mkdocs-material mkdocs-literate-nav mkdoxy mkdocs-video

```

--------------------------------

### Install Vcpkg

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Clones the Vcpkg repository and runs the bootstrap script to install Vcpkg.

```bash
mkdir ~/Toolchain
cd ~/Toolchain
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
```

--------------------------------

### Manually Install Pyuipc

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Manually installs the Python binding if errors occur during the automatic installation.

```bash
cd build/python
pip install .
```

--------------------------------

### Check Pyuipc Installation

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Runs the uipc_info.py script to verify that Pyuipc is installed correctly.

```bash
cd libuipc/python
python uipc_info.py
```

--------------------------------

### Install pyuipc via pip

Source: https://spirimirror.github.io/libuipc-doc/build_install

Install the current PyPI wheel with `pip install pyuipc`. The wheel supports only Windows and Ubuntu 22.04. Python 3.10-3.14 are supported. This installs the Python extension and core libraries.

```bash
pip install pyuipc
```

--------------------------------

### Configure and build with XMake

Source: https://spirimirror.github.io/libuipc-doc/build_install/xmake

Navigates into the cloned directory and configures the project with XMake. The default build includes the CUDA backend, examples, and tests.

```bash
cd libuipc
xmake f -c

```

--------------------------------

### Start and enter XMake CUDA 12.8 container

Source: https://spirimirror.github.io/libuipc-doc/build_install/docker

Navigate to the docker artifacts directory, start the dev-xmake-cu128 service, and open a bash shell inside the container.

```bash
cd libuipc/artifacts/docker
docker compose up -d dev-xmake-cu128
docker compose exec dev-xmake-cu128 bash
```

--------------------------------

### Build the full documentation site

Source: https://spirimirror.github.io/libuipc-doc/build_install/build_docs

Builds the complete site, including generated C++ API pages, using the build helper script. On Windows, it detects Doxygen in the default install directory if not on PATH.

```bash
python scripts/build_docs.py -o output/site

```

--------------------------------

### Install Pyuipc in Any Python Venv

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Configures and builds the project to install Pyuipc into any Python virtual environment, such as uv.

```bash
cmake -S .. -DUIPC_BUILD_PYBIND=1 -DUIPC_PYTHON_EXECUTABLE_PATH=<YOUR_PYTHON_EXECUTABLE_PATH> -DCMAKE_BUILD_TYPE=<Release/RelWithDebInfo>
cmake --build .  -j8
```

--------------------------------

### Create solver environment on Linux

Source: https://spirimirror.github.io/libuipc-doc/build_install/blender

Creates a Python 3 virtual environment, installs pyuipc 0.0.28, and probes CUDA. Use this on Linux.

```bash
python3 -m venv .venv-uipc-blender
.venv-uipc-blender/bin/python -m pip install pyuipc==0.0.28
.venv-uipc-blender/bin/python -m uipc doctor --probe-cuda

```

--------------------------------

### Create solver environment on Windows

Source: https://spirimirror.github.io/libuipc-doc/build_install/blender

Creates a Python 3.14 virtual environment, installs pyuipc 0.0.28, and probes CUDA. Use this on Windows.

```bash
py -3.14 -m venv .venv-uipc-blender
.\\.venv-uipc-blender\\Scripts\\python.exe -m pip install pyuipc==0.0.28
.\\.venv-uipc-blender\\Scripts\\python.exe -m uipc doctor --probe-cuda

```

--------------------------------

### Start and enter CMake CUDA 12.8 container

Source: https://spirimirror.github.io/libuipc-doc/build_install/docker

Navigate to the docker artifacts directory, start the dev-cmake-cu128 service, and open a bash shell inside the container.

```bash
cd libuipc/artifacts/docker
docker compose up -d dev-cmake-cu128
docker compose exec dev-cmake-cu128 bash
```

--------------------------------

### Example Usage of REGISTER_IMPLICIT_GEOMETRY_UIDS

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/implicit__geometry__uid__auto__register_8h

Example macro invocation that defines a block returning a list of UIDInfo. The macro is used to register implicit geometry UIDs.

```cpp
++
REGISTER_IMPLICIT_GEOMETRY_UIDS()
{
    using namespace uipc::builtin;
    list<UIDInfo> uids;
    return uids;
}
```

--------------------------------

### Python tetrahedralize example

Source: https://spirimirror.github.io/libuipc-doc/specification/tetrahedralization

Reads a closed surface OBJ, creates default tetrahedralization options, enables surface preservation, calls tetrahedralize, and prints the report.

```python
from uipc.geometry import (
    SimplicialComplexIO,
    tetrahedralization_default_config,
    tetrahedralize,
)

surface = SimplicialComplexIO().read("closed_surface.obj")
options = tetrahedralization_default_config()
options["preserve_surface"] = True
volume, report = tetrahedralize(surface, options)
print(report)

```

--------------------------------

### Configure, build, and package with XMake

Source: https://spirimirror.github.io/libuipc-doc/build_install/dev_in_uv

Configures xmake with Python binding support, creates a virtual environment, builds the project, and packages the Python wheel. `xmake pack` invokes the same full-package stub generator as CMake and installs missing stub dependencies with `uv pip --python`.

```bash
uv venv --seed --python 3.12 .venv
source .venv/bin/activate
xmake f --pybind=true --python_system=true --python_version=3.12.x -c
xmake build -j8
xmake pack -v
```

--------------------------------

### Live reload for editing prose

Source: https://spirimirror.github.io/libuipc-doc/build_install/build_docs

Starts a live-reload server for editing prose using the mkdocs-with-api.yaml configuration. Requires doxygen on PATH. For a faster prose-only preview, use mkdocs.yaml, but API links will 404.

```bash
python -m mkdocs serve -f mkdocs-with-api.yaml

```

--------------------------------

### SceneVisitor::begin_pending

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1backend_1_1SceneVisitor

Starts a pending operation on the scene, allowing modifications to be batched.

```APIDOC
## SceneVisitor::begin_pending

### Description
Begins a pending state for the scene, enabling batched modifications.

### Method
begin_pending

### Parameters
None

### Returns
void

### Exceptions
No-throw guarantee.
```

--------------------------------

### C++ tetrahedralize example

Source: https://spirimirror.github.io/libuipc-doc/specification/tetrahedralization

Reads a closed surface OBJ, creates default tetrahedralization options, enables surface preservation, and calls tetrahedralize to generate a volume mesh.

```cpp
#include <uipc/geometry/tetrahedralization.h>
#include <uipc/io/simplicial_complex_io.h>

int main()
{
    uipc::geometry::SimplicialComplexIO io;
    auto surface = io.read("closed_surface.obj");
    auto options = uipc::geometry::tetrahedralization_default_config();
    options["preserve_surface"] = true;
    auto [volume, report] = uipc::geometry::tetrahedralize(surface, options);
}

```

--------------------------------

### Get instances of a geometry (C++)

Source: https://spirimirror.github.io/libuipc-doc/tutorial/geometry

Calls the instances() function on a SimplicialComplexIO-read geometry to retrieve its instance collection. The size is initially 1 because a geometry starts as a single instance.

```cpp
SimplicialComplexIO io;
auto cube = io.read("cube.msh");
auto Is = cube.instances();
Is.size(); // 1

```

--------------------------------

### Useful Docker Compose commands

Source: https://spirimirror.github.io/libuipc-doc/build_install/docker

Common commands to start, enter, stop, and remove containers for a given service name.

```bash
# Start container
docker compose up -d <service-name>

# Enter container
docker compose exec <service-name> bash

# Stop container
docker compose stop <service-name>

# Remove containers
docker compose down
```

--------------------------------

### Build Libuipc with XMake

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Configures and builds the project using XMake.

```bash
cd libuipc
xmake f -c
xmake build -j8
```

--------------------------------

### Implement backend entrance (entrance.cpp)

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Defines the required C ABI functions uipc_create_engine and uipc_destroy_engine. Do not redefine uipc_query_module or uipc_init_module; they are provided by src/backends/common/module.cpp.

```cpp
// src/backends/my_backend/entrance.cpp
#include <backends/common/module.h>
#include <my_backend/sim_engine.h>

using namespace uipc;

extern "C" UIPC_BACKEND_API core::IEngine* uipc_create_engine(
    backend::EngineCreateInfo* info)
{
    return new my_backend::SimEngine(*info);
}

extern "C" UIPC_BACKEND_API void uipc_destroy_engine(core::IEngine* engine)
{
    delete engine;
}

```

--------------------------------

### Set up Python development environment with uv

Source: https://spirimirror.github.io/libuipc-doc/build_install/xmake

Creates a virtual environment, configures xmake with Python binding support, builds the project, and packages the Python wheel. This workflow does not add 'builder=xmake' or 'python_editable'.

```bash
uv venv --seed --python 3.12 .venv
source .venv/bin/activate
xmake f --pybind=true --python_system=true --python_version=3.12.x -c
xmake build -j8
xmake pack -v

```

--------------------------------

### init

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1core_1_1IEngine

Initializes the engine with a world.

```APIDOC
## init

### Description
Initializes the engine with a world.

### Method
void

### Signature
`void uipc::core::IEngine::init(internal::World& w)`

### Parameters
- `w` (internal::World&) - Required - The world to initialize the engine with.

### Returns
void
```

--------------------------------

### Assemble a libuipc scene (C++/Python)

Source: https://spirimirror.github.io/libuipc-doc/tutorial/scene_setup

Shows the standard assembly order for a libuipc simulation: create an Engine and World, configure the Scene, build the scene contents, then call world.init(scene) once before alternating world.advance() and world.retrieve(). The C++ and Python versions are equivalent and are presented as interchangeable tabs.

```cpp
Engine engine{"cuda", "output/my_scene"};
World world{engine};

auto config = Scene::default_config();
config["dt"] = 0.01;
Scene scene{config};

// Build contact table, geometry, constitutions, and objects here.

world.init(scene);
if(!world.is_valid())
    throw std::runtime_error("scene initialization failed");

while(world.frame() < 100)
{
    world.advance();
    world.retrieve();
}

```

```python
engine = Engine("cuda", "output/my_scene")
world = World(engine)

config = Scene.default_config()
config["dt"] = 0.01
scene = Scene(config)

# Build contact table, geometry, constitutions, and objects here.

world.init(scene)
if not world.is_valid():
    raise RuntimeError("scene initialization failed")

while world.frame() < 100:
    world.advance()
    world.retrieve()

```

--------------------------------

### Create default config and construct scene (C++)

Source: https://spirimirror.github.io/libuipc-doc/specification/scene_config

Creates a default scene configuration, sets dt, gravity, and contact friction, then constructs a uipc::core::Scene with it.

```cpp
auto config = uipc::core::Scene::default_config();
config["dt"] = 0.01;
config["gravity"] = uipc::Vector3{0.0, -9.8, 0.0};
config["contact"]["friction"]["enable"] = true;

uipc::core::Scene scene{config};

```

--------------------------------

### Install Python build requirements with uv pip

Source: https://spirimirror.github.io/libuipc-doc/build_install/dev_in_uv

Installs the Python build requirements needed for non-isolated CMake builds: scikit-build-core, setuptools-scm, pybind11, pybind11-stubgen, numpy, and typing_extensions.

```bash
uv pip install scikit-build-core setuptools-scm pybind11 pybind11-stubgen numpy typing_extensions
```

--------------------------------

### init

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/namespaceuipc

Initializes the library with the given configuration. This is a core API function.

```APIDOC
## init

### Description
Initializes the library with the given configuration. This is a core API function.

### Signature
`UIPC_CORE_API void init(const Json& config)`

### Parameters
- `config` (const Json&) - The configuration to initialize with.

### Returns
Nothing.
```

--------------------------------

### REGISTER_CONSTITUTION_UIDS macro definition and usage

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/constitution__uid__auto__register_8h

The macro definition and its usage example. The macro registers ConstitutionUIDs and expands to REGISTER_CONSTITUTION_UIDS_INTERNAL(__COUNTER__). The example shows a typical implementation returning a list of UIDInfo.

```cpp
#define REGISTER_CONSTITUTION_UIDS (
    ...
) `REGISTER_CONSTITUTION_UIDS_INTERNAL(__COUNTER__)`

```

```cpp
++
REGISTER_CONSTITUTION_UIDS()
{
    using namespace uipc::builtin;
    list<UIDInfo> uids;
    return uids;
}

```

--------------------------------

### Create Engine and World

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Shows how the frontend user creates an Engine with a backend name and workspace path, then constructs a World from it. The backend is dynamically loaded when the Engine is created.

```cpp
core::Engine engine{"BACKEND_NAME", "workspace/path"};
core::World  world{engine};
```

--------------------------------

### positions

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets the positions of the vertices.

```APIDOC
## positions

### Description
Get the positions of the vertices.

### Method
Member function

### Signature
AttributeSlot<Vector3> & positions() noexcept

### Returns
- **AttributeSlot<Vector3>&** - Reference to the positions attribute slot.
```

--------------------------------

### size()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1IAttribute

Get the size of the attribute.

```APIDOC
## size()

### Description
Get the size of the attribute.

### Signature
```cpp
SizeT uipc::geometry::IAttribute::size () noexcept const
```

### Returns
- **SizeT** - The size of the attribute.

```

--------------------------------

### World::init(Scene&)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1core_1_1World

Initializes the world with a given scene. This method sets up the world for simulation using the provided scene.

```APIDOC
## World::init(Scene&)

### Description
Initializes the world with a given scene. This method sets up the world for simulation using the provided scene.

### Method
void

### Parameters
- **s** (Scene&) - Required - The scene to initialize the world with.

### Return Value
void

```

--------------------------------

### topo

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplexAttributes

Gets the topology of the simplicial complex.

```APIDOC
## topo

### Description
Gets the topology of the simplicial complex.

### Method
Function

### Signature
```cpp
inline AttributeSlot<TopoValueT> & topo();
inline const AttributeSlot<TopoValueT> & topo() const;
```

### Parameters
None.

### Returns
AttributeSlot<TopoValueT>& or const AttributeSlot<TopoValueT>& - The topology attribute slot.
```

--------------------------------

### meta()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get the meta attributes of the geometries.

```APIDOC
## meta()

### Description
Get the meta attributes of the geometries.

### Signatures
```cpp
MetaAttributes meta();
CMetaAttributes meta() const;
```

### Parameters
None.

### Returns
- **MetaAttributes** - Non-const version: meta attributes.
- **CMetaAttributes** - Const version: const meta attributes.
```

--------------------------------

### Create default config and construct scene (Python)

Source: https://spirimirror.github.io/libuipc-doc/specification/scene_config

Creates a default scene configuration, sets dt, gravity, and contact friction, then constructs a Scene with it.

```python
from uipc.core import Scene

config = Scene.default_config()
config["dt"] = 0.01
config["gravity"] = [[0.0], [-9.8], [0.0]]
config["contact"]["friction"]["enable"] = True

scene = Scene(config)

```

--------------------------------

### Create engine with backend name

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Instantiates the engine using the backend name 'my_backend'. If the module fails to load, verify the shared library location as described.

```cpp
core::Engine engine{"my_backend", "my_workspace"};

```

--------------------------------

### instances()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get the instance attributes of the geometries.

```APIDOC
## instances()

### Description
Get the instance attributes of the geometries.

### Signatures
```cpp
InstanceAttributes instances();
CInstanceAttributes instances() const;
```

### Parameters
None.

### Returns
- **InstanceAttributes** - Non-const version: instance attributes.
- **CInstanceAttributes** - Const version: const instance attributes.
```

--------------------------------

### dim()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get the dimension of the simplicial complex.

```APIDOC
## dim()

### Description
Get the dimension of the simplicial complex.

### Signature
```cpp
IndexT dim() noexcept const;
```

### Parameters
None.

### Returns
- **IndexT** - The dimension of the simplicial complex.
```

--------------------------------

### MySimSystem header and implementation with REGISTER_SIM_SYSTEM

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Shows how to define a custom SimSystem subclass in a header and register it in the source file. The constructor signature determines which engine instantiates the system; a system taking cuda::SimEngine& is only used by the CUDA engine, while one taking backend::SimEngine& works with any engine. Call REGISTER_SIM_SYSTEM(MySimSystem) in the source file to register the system.

```cpp
// my_backend/my_sim_system.h
#include <backends/common/sim_system.h>
namespace uipc::my_backend
{
    class MySimSystem : public backend::SimSystem
    {
      public:
        using SimSystem::SimSystem;
      protected:
        void do_build() override;
        // a safe way to keep the reference of other system
        SimSystemSlot<OtherSimSystem> other_system;
        // a safe way to keep the reference of a collection of other systems
        SimSystemSlotCollection<AnotherSimSystem> another_systems;
    };
}

// my_backend/my_sim_system.cpp
namespace uipc::my_backend
{
    REGISTER_SIM_SYSTEM(MySimSystem);
}

```

--------------------------------

### Build pairwise material table (Python)

Source: https://spirimirror.github.io/libuipc-doc/specification/scene_configs/contact

Equivalent Python version of the pairwise material table setup. Imports GPa and MPa units, creates the table and elements, inserts pair rows, and applies them to meshes.

```python
from uipc.unit import GPa, MPa

table = scene.contact_tabular()
steel = table.default_element()
rubber = table.create("rubber")

table.default_model(0.3, 1.0 * GPa)
table.insert(steel, rubber, 0.8, 300.0 * MPa)
table.insert(rubber, rubber, 1.0, 100.0 * MPa)

steel.apply_to(steel_mesh)
rubber.apply_to(rubber_mesh)

```

--------------------------------

### Register backend in CMakeLists.txt

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Creates a runtime-loadable shared library named uipc_backend_my_backend and links backend common utilities. Place this in src/backends/my_backend/CMakeLists.txt.

```cmake
# src/backends/my_backend/CMakeLists.txt
uipc_add_backend(my_backend)
file(GLOB SOURCES "*.cpp" "*.h" "details/*.inl")
target_sources(my_backend PRIVATE ${SOURCES})

```

--------------------------------

### offset()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1backend_1_1BufferView

Returns the offset in elements from the start of the buffer.

```APIDOC
## offset()

### Description
Returns the offset in elements from the start of the buffer.

### Method
Member Function

### Signature
```cpp
SizeT uipc::backend::BufferView::offset () noexcept const
```

### Parameters
None.

### Returns
- **SizeT** - The offset in elements.
```

--------------------------------

### Implement SimEngine lifecycle (sim_engine.cpp)

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Implements the engine lifecycle hooks. do_init pulls scene data, builds systems, and dumps topology to <workspace>/systems.json. do_advance drives the simulation pipeline, while do_sync and do_retrieve handle buffer uploads and geometry attribute writes.

```cpp
// src/backends/my_backend/sim_engine.cpp
#include <my_backend/sim_engine.h>

namespace uipc::my_backend
{
void SimEngine::do_init(backend::WorldVisitor v)
{
    // 1. pull scene data you need from the visitor
    // 2. build all registered sim systems and their dependencies
    build_systems();
    // 3. dump system topology to <workspace>/systems.json for debugging
    dump_system_infos();
}

void SimEngine::do_advance()
{
    // drive your simulation pipeline here
}

void SimEngine::do_sync()    { /* upload results to the frontend buffers */ }
void SimEngine::do_retrieve() { /* write back geometry attributes */ }
}  // namespace uipc::my_backend

```

--------------------------------

### transforms

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets the non-const transforms attribute slot.

```APIDOC
## transforms

### Description
A short-cut to get the non-const transforms attribute slot.

### Method
Member function

### Signature
AttributeSlot<Matrix4x4> & transforms()

### Returns
- **AttributeSlot<Matrix4x4>&** - Reference to the transforms attribute slot.
```

--------------------------------

### positions (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets the const positions of the vertices.

```APIDOC
## positions (const)

### Description
A short cut to get the positions of the vertices (const version).

### Method
Member function

### Signature
const AttributeSlot<Vector3> & positions() noexcept const

### Returns
- **const AttributeSlot<Vector3>&** - Const reference to the positions attribute slot.
```

--------------------------------

### List and run benchmarks from the performance registry

Source: https://spirimirror.github.io/libuipc-doc/development/testing_and_benchmarks

Lists available benchmarks and runs specific ones from the benchmarks/manifest.json registry. The --quick flag runs a quick variant, --frames sets the frame count, and --env overrides environment variables. These commands are used for canonical throughput measurements.

```bash
python scripts/run_benchmark.py list

```

```bash
python scripts/run_benchmark.py run rigid-wrecking-balls --quick

```

```bash
python scripts/run_benchmark.py run stiff-gipc-case2 --quick

```

```bash
python scripts/run_benchmark.py run stiff-gipc-case2 --frames 250

```

```bash
python scripts/run_benchmark.py run mas-bunny --frames 100

```

```bash
python scripts/run_benchmark.py run cube-wall-cloth --frames 100

```

--------------------------------

### MySimSystem::do_build with require, find, and SimSystemException

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Shows how to implement do_build to require or find other systems. require<T> throws if the system is not found, while find<T> returns nullptr. Throw SimSystemException to invalidate the system on bad conditions. The backend cleans up invalid systems and their strong dependents, and a cycle aborts initialization.

```cpp
namespace uipc::my_backend
{
void MySimSystem::do_build()
{
    // require other systems
    auto& other_system_ref = require<OtherSimSystem>();
    other_system.register_system(&other_system_ref);

    // find other systems
    auto* another_system_ptr = find<AnotherSimSystem>();
    another_systems.register_system(another_system_ptr);

    if(...) // if some bad condition happened
        throw SimSystemException("This system is invalid");
}
}

```

--------------------------------

### Logger::current_logger (getter)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1Logger

Gets the current logger.

```APIDOC
## Logger::current_logger (getter)

### Description
Gets the current logger.

### Method
static Logger current_logger()

### Parameters
None

### Return Type
Logger

```

--------------------------------

### Logger::get_level

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1Logger

Gets the current log level.

```APIDOC
## Logger::get_level

### Description
Gets the current log level.

### Method
spdlog::level::level_enum get_level() const

### Parameters
None

### Return Type
spdlog::level::level_enum

```

--------------------------------

### World::init(internal::Scene&)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1core_1_1internal_1_1World

Initializes the world with a given scene.

```APIDOC
## World::init(internal::Scene&)

### Description
Initializes the world using the provided scene.

### Method
Member Function

### Signature
```cpp
void uipc::core::internal::World::init(
    internal::Scene & s
)
```

### Parameters
- **s** (internal::Scene&) - Required - Reference to the scene to initialize with.

### Returns
void

```

--------------------------------

### transforms (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets the const transforms attribute slot.

```APIDOC
## transforms (const)

### Description
A short-cut to get the const transforms attribute slot.

### Method
Member function

### Signature
const AttributeSlot<Matrix4x4> & transforms() const

### Returns
- **const AttributeSlot<Matrix4x4>&** - Const reference to the transforms attribute slot.
```

--------------------------------

### Build with XMake inside container

Source: https://spirimirror.github.io/libuipc-doc/build_install/docker

Configure the build with Python bindings enabled (--pybind=y) and compile using all available CPU cores.

```bash
xmake config --pybind=y
xmake -j$(nproc)
```

--------------------------------

### to_json() const

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AttributeCollection

Get the JSON representation of the attribute collection.

```APIDOC
## to_json() const

### Description
Get the JSON representation of the attribute collection.

### Signature
cpp
Json to_json() const;


### Returns
- **Json** - The JSON representation of the attribute collection.

```

--------------------------------

### Profile with nsight.session

Source: https://spirimirror.github.io/libuipc-doc/tutorial/profiling

Use nsight.session to run the simulation under Nsight Compute and collect kernel-level GPU metrics. The session advances 50 steps then profiles 10 steps, writing reports to the output directory as Markdown, JSON, and .ncu-rep files.

```python
from uipc.profile import nsight

with nsight.session(world, name='test') as s:
    s.advance(50)
    s.profile(10)

```

--------------------------------

### names() const

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AttributeCollection

Get the names of all attribute slots in the collection.

```APIDOC
## names() const

### Description
Get the names of all attribute slots in the collection.

### Signature
cpp
vector<string> names() const;


### Returns
- **vector<string>** - A vector containing the names of all attribute slots.

```

--------------------------------

### Enable optional libraries (USD and VDB)

Source: https://spirimirror.github.io/libuipc-doc/build_install/xmake

Configures the build to enable the optional USD and VDB libraries. These are disabled by default.

```bash
xmake f --usd=true --vdb=true -c

```

--------------------------------

### vertices()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get a wrapper of the vertices and their attributes of the simplicial complex.

```APIDOC
## vertices()

### Description
Get a wrapper of the vertices and their attributes of the simplicial complex.

### Signatures
```cpp
VertexAttributes vertices() noexcept;
CVertexAttributes vertices() noexcept const;
```

### Parameters
None.

### Returns
- **VertexAttributes** - Non-const version: a wrapper of vertices and their attributes.
- **CVertexAttributes** - Const version: a const wrapper of vertices and their attributes.
```

--------------------------------

### BufferView::BufferView(HandleT, SizeT, SizeT, SizeT, SizeT, std::string_view)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/buffer__view_8h_source

Constructs a BufferView with the given handle, element offset, element count, element size, element stride, and backend name.

```APIDOC
## BufferView::BufferView(HandleT, SizeT, SizeT, SizeT, SizeT, std::string_view)

### Description
Constructs a BufferView with the specified handle, element offset, element count, element size, element stride, and backend name.

### Parameters
- **handle** (HandleT) - Required - The handle to the underlying buffer.
- **element_offset** (SizeT) - Required - The offset in elements from the start of the buffer.
- **element_count** (SizeT) - Required - The number of elements in the view.
- **element_size** (SizeT) - Required - The size of each element in bytes.
- **element_stride** (SizeT) - Required - The stride between elements in bytes.
- **backend_name** (std::string_view) - Required - The name of the backend that owns the buffer.

```

--------------------------------

### triangles()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get a wrapper of the triangles and their attributes of the simplicial complex.

```APIDOC
## triangles()

### Description
Get a wrapper of the triangles and their attributes of the simplicial complex.

### Signatures
```cpp
TriangleAttributes triangles() noexcept;
CTriangleAttributes triangles() noexcept const;
```

### Parameters
None.

### Returns
- **TriangleAttributes** - Non-const version: a wrapper of triangles and their attributes.
- **CTriangleAttributes** - Const version: a const wrapper of triangles and their attributes.
```

--------------------------------

### Run benchmark with timer diagnostics

Source: https://spirimirror.github.io/libuipc-doc/development/testing_and_benchmarks

Runs a benchmark with UIPC_BENCHMARK_TIMERS=1 to enable timer scopes for stage diagnostics. Timer scopes synchronize nested GPU regions and change wall time, so use them for attribution, not as a substitute for Timer-free throughput results.

```bash
python scripts/run_benchmark.py run stiff-gipc-case2 --frames 60 \
  --env UIPC_BENCHMARK_TIMERS=1

```

--------------------------------

### tetrahedra()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get a wrapper of the tetrahedra and their attributes of the simplicial complex.

```APIDOC
## tetrahedra()

### Description
Get a wrapper of the tetrahedra and their attributes of the simplicial complex.

### Signatures
```cpp
TetrahedronAttributes tetrahedra() noexcept;
CTetrahedronAttributes tetrahedra() noexcept const;
```

### Parameters
None.

### Returns
- **TetrahedronAttributes** - Non-const version: a wrapper of tetrahedra and their attributes.
- **CTetrahedronAttributes** - Const version: a const wrapper of tetrahedra and their attributes.
```

--------------------------------

### Serve the generated site locally

Source: https://spirimirror.github.io/libuipc-doc/build_install/build_docs

Serves the built site from the output/site directory on port 8000. Stop the server with Ctrl+C.

```bash
python -m http.server 8000 --directory output/site

```

--------------------------------

### edges()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get a wrapper of the edges and their attributes of the simplicial complex.

```APIDOC
## edges()

### Description
Get a wrapper of the edges and their attributes of the simplicial complex.

### Signatures
```cpp
EdgeAttributes edges() noexcept;
CEdgeAttributes edges() noexcept const;
```

### Parameters
None.

### Returns
- **EdgeAttributes** - Non-const version: a wrapper of edges and their attributes.
- **CEdgeAttributes** - Const version: a const wrapper of edges and their attributes.
```

--------------------------------

### SimplicialComplexAttributes::topo (non-const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplexAttributes

Gets the topology of the simplicial complex.

```APIDOC
## SimplicialComplexAttributes::topo (non-const)

### Description
Gets the topology of the simplicial complex.

### Method
AttributeSlot<TopoValueT>& topo()

### Parameters
None.

### Returns
AttributeSlot<TopoValueT>& - Reference to the topology attribute slot.
```

--------------------------------

### Creating a baseline and checking for regressions

Source: https://spirimirror.github.io/libuipc-doc/tutorial/profiling

Create a baseline on a stable runner, then check later results on that same runner. The check exits nonzero when an enforced metric exceeds its saved allowance (10% by default), a benchmark/frame plan is missing, or compatibility facts do not match.

```bash
python -m uipc benchmark baseline bench/cube_ground -o baselines/cube_ground.json
python -m uipc benchmark check bench-candidate/cube_ground \
    --baseline baselines/cube_ground.json \
    --json-output bench-candidate/gate.json

```

--------------------------------

### attribute_count() const

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AttributeCollection

Get the number of attribute slots in the collection.

```APIDOC
## attribute_count() const

### Description
Get the number of attribute slots in the collection.

### Signature
cpp
SizeT attribute_count() const;


### Returns
- **SizeT** - The number of attribute slots.

```

--------------------------------

### uipc::init

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/common_2uipc_8h_source

Initializes the UIPC library with the provided configuration. This function must be called before using other UIPC features.

```APIDOC
## uipc::init

### Description
Initializes the UIPC library with the provided configuration. This function must be called before using other UIPC features.

### Function Signature
cpp
void init(const Json& config);


### Parameters
- **config** (const Json&) - Required - The configuration object used to initialize the library.

### Return Value
None (void).

### Usage Example
cpp
#include <uipc/common/uipc.h>

uipc::init(config);

```

--------------------------------

### vertex_count

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1core_1_1FiniteElementStateAccessorFeature

Gets the number of vertices in the finite element system.

```APIDOC
## vertex_count

### Description
Gets the number of vertices in the finite element system.

### Method
SizeT vertex_count() const

### Parameters
None

### Returns
SizeT - The number of vertices.
```

--------------------------------

### Build Blender add-on ZIP

Source: https://spirimirror.github.io/libuipc-doc/build_install/blender

Builds the libuipc_blender-0.8.0.zip from the repository root. Output is output/blender-dist/libuipc_blender-0.8.0.zip.

```bash
python scripts/build_blender_addon.py

```

--------------------------------

### Install native mesher into Blender's Python (Windows)

Source: https://spirimirror.github.io/libuipc-doc/build_install/blender

Commands to install the built libuipc Python package into the external Python interpreter used by Blender, then verify the native tetrahedralize function is available. Required for the Generate Tetrahedra button when using the 0.0.28 wheel.

```bash
.\.venv-uipc-blender\Scripts\python.exe -m pip install --no-deps --force-reinstall .\build\python
.\.venv-uipc-blender\Scripts\python.exe -c "from uipc.geometry import tetrahedralize; print('Native mesher ready')"

```

--------------------------------

### static void Timer::enable_all()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1Timer

Enables all timers globally.

```APIDOC
## static void Timer::enable_all()

### Description
Enables all timers globally.

### Method
Static Function

### Signature
```cpp
static inline void uipc::Timer::enable_all ()
```

```

--------------------------------

### Build and install Python package in editable mode with CMake

Source: https://spirimirror.github.io/libuipc-doc/build_install/dev_in_uv

Builds the project and installs the Python package in editable mode, specifying the build directory to cache CMake results and disabling build isolation to reuse prepared dependencies. Append `--config-settings=cmake.define.UIPC_CUDA_ARCHITECTURES=native` for a local-GPU build.

```bash
uv pip install -e . --config-settings=build-dir=build --no-build-isolation -v
```

--------------------------------

### Build with CMake inside container

Source: https://spirimirror.github.io/libuipc-doc/build_install/docker

Create a build directory, configure with CMake enabling the Python bindings (UIPC_BUILD_PYBIND=1) in Release mode, and compile using all available CPU cores.

```bash
mkdir build; cd build
cmake -S .. -DUIPC_BUILD_PYBIND=1 -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)
```

--------------------------------

### get_type

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1Geometry

Gets the type of the geometry. This is an override of the IGeometry interface method.

```APIDOC
## get_type

### Description
Gets the type of the geometry. This is an override of the IGeometry interface method.

### Method
get_type

### Signature
```cpp
virtual std::string_view uipc::geometry::Geometry::get_type() noexcept override const
```

### Parameters
None

### Returns
- **std::string_view** - The type of the geometry.
```

--------------------------------

### type

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1Geometry

Gets the type of the geometry. Inherited from uipc::geometry::IGeometry.

```APIDOC
## type

### Description
Gets the type of the geometry. Check the type to downcast the geometry to a specific type.

### Method
type

### Signature
std::string_view type() noexcept const

### Returns
- **std::string_view** - The type of the geometry.

```

--------------------------------

### Define UIPC_BUILTIN_BACKEND macro and include backend_name.h

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/backend__name_8h

Shows how to define the UIPC_BUILTIN_BACKEND macro before including the header, then undefine it after. This allows access to built-in backend names as string_view constants.

```cpp
#define UIPC_BUILTIN_BACKEND(name) constexpr std::string_view name = #name
#include <pyuipc/builtin/backend_name.h>
#undef UIPC_BUILTIN_BACKEND
```

--------------------------------

### operator[](std::string_view)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AbstractSimplicialComplex

Get the attribute collection with the given name.

```APIDOC
## operator[](std::string_view name)

### Description
Get the attribute collection with the given name.

### Signatures
```cpp
S<AttributeCollection> operator[](std::string_view name);
S<const AttributeCollection> operator[](std::string_view name) const;
```

### Parameters
- **name** (std::string_view) - The name of the attribute collection.

### Returns
- **S<AttributeCollection>** - Non-const version: shared pointer to the attribute collection.
- **S<const AttributeCollection>** - Const version: shared pointer to the const attribute collection.
```

--------------------------------

### type_name()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1IAttribute

Get the type name of data stored in the attribute slot.

```APIDOC
## type_name()

### Description
Get the type name of data stored in the attribute slot.

### Signature
```cpp
std::string_view uipc::geometry::IAttribute::type_name () noexcept const
```

### Returns
- **std::string_view** - The type name of the data.

```

--------------------------------

### Python: Simulation loop writing scene surfaces

Source: https://spirimirror.github.io/libuipc-doc/tutorial/animation

Initializes the scene, writes the initial surface, then advances the world for 360 frames, writing each frame's surface to an OBJ file.

```python
world.init(scene)
sio = SceneIO(scene)
sio.write_surface(f"scene_surface{world.frame()}.obj")
while world.frame() < 360:
    world.advance()
    world.retrieve()
    sio.write_surface(f"scene_surface{world.frame()}.obj")

```

--------------------------------

### vertex_count() const

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1core_1_1FiniteElementStateAccessorFeature

Gets the number of vertices in the finite element system.

```APIDOC
## vertex_count() const

### Description
Gets the number of vertices in the finite element system.

### Method
vertex_count

### Parameters
None

### Returns
SizeT - The number of vertices.
```

--------------------------------

### init

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1backend_1_1AnimatorVisitor

Initializes the animator visitor.

```APIDOC
## init

### Description
Initializes the animator visitor.

### Method Signature
`void init()`

### Parameters
None.

### Returns
None.

```

--------------------------------

### SimplicialComplexIO(SimplicialComplexIO&&)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplexIO

Move constructor for SimplicialComplexIO.

```APIDOC
## SimplicialComplexIO(SimplicialComplexIO&&)

### Description
Move constructor for SimplicialComplexIO.

### Method
Constructor

### Parameters
#### Parameters
- **other** (SimplicialComplexIO&&) - Required - The object to move from.

### Signature
SimplicialComplexIO(SimplicialComplexIO &&) = default

```

--------------------------------

### uipc::logger::get_level

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/logger_8h_source

Gets the current logging level of the current logger.

```APIDOC
## uipc::logger::get_level

### Description
Returns the current logging level of the current logger.

### Method
Free function

### Signature
`Logger::Level get_level();`

### Parameters
None

### Returns
- **Logger::Level** - The current logging level.

```

--------------------------------

### BufferView()

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1backend_1_1BufferView

Default constructor for BufferView.

```APIDOC
## BufferView()

### Description
Default constructor for BufferView.

### Method
Constructor

### Signature
```cpp
uipc::backend::BufferView::BufferView () = default
```

### Parameters
None.

### Returns
None.
```

--------------------------------

### SceneVisitor::SceneVisitor(SceneVisitor&&) = default

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1backend_1_1SceneVisitor

Defaulted move constructor.

```APIDOC
## SceneVisitor::SceneVisitor(SceneVisitor&&) = default

### Description
This constructor is defaulted, allowing move construction.

### Signature
```cpp
uipc::backend::SceneVisitor::SceneVisitor(
    SceneVisitor &&
) = default
```
```

--------------------------------

### get_attribute [2/2]

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1IAttributeSlot

Pure virtual function to get the attribute. This is a const overload.

```APIDOC
## get_attribute [2/2]

### Description
Pure virtual function to get the attribute. This is a const overload.

### Method
get_attribute

### Signature
```cpp
virtual const IAttribute & uipc::geometry::IAttributeSlot::get_attribute () noexcept const = 0
```

### Parameters
None

### Returns
- **const IAttribute&** - Const reference to the attribute.

### Exceptions
No-throw guarantee.
```

--------------------------------

### get_attribute [1/2]

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1IAttributeSlot

Pure virtual function to get the attribute. This is a non-const overload.

```APIDOC
## get_attribute [1/2]

### Description
Pure virtual function to get the attribute. This is a non-const overload.

### Method
get_attribute

### Signature
```cpp
virtual IAttribute & uipc::geometry::IAttributeSlot::get_attribute () noexcept = 0
```

### Parameters
None

### Returns
- **IAttribute&** - Reference to the attribute.

### Exceptions
No-throw guarantee.
```

--------------------------------

### Enable Python Bindings with XMake

Source: https://spirimirror.github.io/libuipc-doc/build_install/linux

Configures XMake to enable Python bindings and builds the project.

```bash
cd libuipc
xmake f --pybind=true --python_system=true --python_version=3.11.x -c
xmake build -j8
xmake pack -v
```

--------------------------------

### vertices (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets a const wrapper of the vertices and its attributes of the simplicial complex.

```APIDOC
## vertices (const)

### Description
A wrapper of the vertices and its attributes of the simplicial complex (const version).

### Method
Member function

### Signature
CVertexAttributes vertices() noexcept const

### Returns
- **CVertexAttributes** - A const wrapper of the vertices and its attributes.
```

--------------------------------

### triangles (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets a const wrapper of the triangles and its attributes of the simplicial complex.

```APIDOC
## triangles (const)

### Description
A wrapper of the triangles and its attributes of the simplicial complex (const version).

### Method
Member function

### Signature
CTriangleAttributes triangles() noexcept const

### Returns
- **CTriangleAttributes** - A const wrapper of the triangles and its attributes.
```

--------------------------------

### edges (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplex

Gets a const wrapper of the edges and its attributes of the simplicial complex.

```APIDOC
## edges (const)

### Description
A wrapper of the edges and its attributes of the simplicial complex (const version).

### Method
Member function

### Signature
CEdgeAttributes edges() noexcept const

### Returns
- **CEdgeAttributes** - A const wrapper of the edges and its attributes.
```

--------------------------------

### size() const

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1AttributeCollection

Get the size of the attribute slots (the number of elements in each slot).

```APIDOC
## size() const

### Description
Get the size of the attribute slots (the number of elements in each slot).

### Signature
cpp
SizeT size() const;


### Returns
- **SizeT** - The size of the attribute slots.

```

--------------------------------

### Command-line benchmark run

Source: https://spirimirror.github.io/libuipc-doc/tutorial/profiling

The command-line runner exposes the same boundary as the Python API. This command runs a benchmark for the cube_ground scene with 20 warmup frames and 50 measured frames, outputting to the bench directory.

```bash
python -m uipc benchmark run --scene cube_ground --warmup 20 --frames 50 --output bench

```

--------------------------------

### Subsystem pattern: MyGlobalSystem header and implementation

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Shows how to build a global system that manages subsystems using SimSystemSlotCollection. The global system registers subsystems and dispatches their lifecycle functions. Use this pattern to create a hierarchical system structure where subsystems can be added during do_build.

```cpp
// my_backend/my_global_system.h
namespace uipc::my_backend
{
class MyGlobalSystem : public SimSystem
{
  public:
    using SimSystem::SimSystem;
    void do_build() override {}
    void add_subsystem(SimSystem* subsystem);
    void dispatch_subsystems();

  private:
    friend class SimEngine;
    SimSystemSlotCollection<SimSystem> m_subsystems;
};
}

// my_backend/my_global_system.cpp
namespace uipc::my_backend
{
REGISTER_SIM_SYSTEM(MyGlobalSystem);

void MyGlobalSystem::add_subsystem(SimSystem* subsystem)
{
    m_subsystems.register_system(subsystem);
}

void MyGlobalSystem::dispatch_subsystems()
{
    for(auto& subsystem : m_subsystems.view())
    {
        subsystem->advance();
    }
}
}

```

--------------------------------

### SimplicialComplexAttributes::topo (const)

Source: https://spirimirror.github.io/libuipc-doc/Libuipc/classuipc_1_1geometry_1_1SimplicialComplexAttributes

Gets the topology of the simplicial complex (const version).

```APIDOC
## SimplicialComplexAttributes::topo (const)

### Description
Gets the topology of the simplicial complex (const version).

### Method
const AttributeSlot<TopoValueT>& topo() const

### Parameters
None.

### Returns
const AttributeSlot<TopoValueT>& - Const reference to the topology attribute slot.
```

--------------------------------

### Build backend with CMake

Source: https://spirimirror.github.io/libuipc-doc/development/backend

Configures and builds the project with CUDA backend disabled. Run from the repository root; the build output must place uipc_backend_my_backend.{dll,so} next to other backend modules or in config["module_dir"].

```bash
cmake -S . -B build -DUIPC_WITH_CUDA_BACKEND=OFF
cmake --build build --config Release -j8

```

--------------------------------

### Get meta information (Python)

Source: https://spirimirror.github.io/libuipc-doc/tutorial/geometry

Python equivalent of accessing the meta information of a geometry.

```python
meta = cube.meta()

```