Libuipc

https://spirimirror.github.io/libuipc-doc
Admin
Libuipc is a cross-platform C++20 and Python GPU incremental potential contact framework for forward...
Tokens:360,115
Snippets:2,802
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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

```

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

### 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)

```

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

### 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 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

```

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

### 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
```

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

### 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;
}
```

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

### 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};

```

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

### 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
```

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

### 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);
}

```

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

### 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

```

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

### 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.
```

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

### 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})

```

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

### 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.
```

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

### 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

```

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

### 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
```

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

### 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.
```

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

### 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
```

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

### 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")

```

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

### 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.

```

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

### 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

```

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

### 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.
```
Tokens:
Raw