MCPcopy
hub / github.com/st-tech/ppf-contact-solver

github.com/st-tech/ppf-contact-solver @v1.0-assets sqlite

repository ↗ · DeepWiki ↗ · release v1.0-assets ↗
770 symbols 2,045 edges 37 files 548 documented · 71%
README

ZOZO's Contact Solver 🫶

A contact solver for physics-based simulations involving 👚 shells, 🪵 solids and 🪢 rods. All made by ZOZO, Inc., the largest fashion e-commerce company in Japan.

Getting Started All Examples All Examples (Windows Native) Python API Docs Docker Build Build Windows solver_logo

🤖 Our Use of LLMs

We highly respect that readers expect human-written content. The majority of texts are human-typed. Our use of LLMs is clarified in 🤖 LLM Transparency.

👀 Quick Look

🚀 Double click start.bat (Windows) or run a Docker command (Linux/Windows) to get it running

glance-terminal

🌐 Click the URL and explore our examples

glance-jupyter

✨ Highlights

  • 💪 Robust: Contact resolutions are penetration-free. No snagging intersections.
  • ⏲ Scalable: An extreme case includes beyond 180M contacts. Not just one million.
  • 🚲 Cache Efficient: All on the GPU runs in single precision. No double precision.
  • 🥼 Not Rubbery: Triangles never extend beyond strict upper bounds (e.g., 1%).
  • 📐 Finite Element Method: We use FEM for deformables and symbolic force jacobians.
  • ⚔️ Highly Stressed: We run GitHub Actions to run stress tests 10 times in a row.
  • 🚀 Massively Parallel: Both contact and elasticity solvers are run on the GPU.
  • 🪟 Windows Executable: No installation wizard shown. Just unzip and run (Video).
  • 🐳 Docker Sealed: All can be deployed fast. The image is ~1GB.
  • 🌐 JupyterLab Included: Open your browser and run examples right away (Video).
  • 🐍 Documented Python APIs: Our Python code is fully docstringed and lintable (Video).
  • ☁️ Cloud-Ready: Our solver can be seamlessly deployed on major cloud platforms.
  • ✨ Stay Clean: You can remove all traces after use.

⚠️ Built for offline uses; not real time. Some examples may run at an interactive rate.

🔖 Table of Contents

📚 Advanced Contents

📝 Change History

More history records

🎓 Technical Materials

📘 A Cubic Barrier with Elasticity-Inclusive Dynamic Stiffness

📌 Reference Implementation

The main branch is undergoing frequent updates and will deviate from the paper. To retain consistency with the paper, we have created a new branch sigasia-2024.

  • 🛠️ Only maintenance updates are planned for this branch.
  • 🚫 General users should not use this branch as it is not optimized for best performance.
  • 🚫 All algorithmic changes listed in this (Markdown) are excluded from this branch.
  • 📦 We also provide a pre-compiled Docker image: ghcr.io/st-tech/ppf-contact-solver-compiled-sigasia-2024:latest of this branch.
  • 🌐 Template Link for vast.ai
  • 🌐 Template Link for RunPods

⚡️ Requirements

  • 🔥 A modern NVIDIA GPU (CUDA 12.8 or newer)
  • 💻 x86 architecture (arm64 is not supported)
  • 🐳 A Docker environment (see below) or 🪟 Windows 10/11 for native executable (see below)

💨 Getting Started

⚠️ Do not run warmup.py locally. If you do, you are very likely to hit failures and find it difficult to cleanup.

🪟 Windows Native Executable

For Windows 10/11 users, a self-contained executable (~230MB) is available. No Python, Docker, or CUDA Toolkit installation is needed. All should simply work out of the box (Video).

🤔 If you are cautious, you can review the build workflow to verify safety yourself. We try to maximize transparency; we never build locally and upload.

  1. Install the latest NVIDIA driver (Link)
  2. Download the latest release from GitHub Releases and unzip
  3. Double click start.bat

JupyterLab frontend will auto-start. You should be able to access it at http://localhost:8080.

🐳 Docker (Linux and Windows)

Install a NVIDIA driver (Link) on your host system and follow the instructions below specific to the operating system to get a Docker running:

🐧 Linux 🪟 Windows
Install the Docker engine from here (Link). Also, install the NVIDIA Container Toolkit (Link). Just to make sure that the Container Toolkit is loaded, run sudo service docker restart. Install the Docker Desktop (Link). You may need to log out or reboot after the installation. After logging back in, launch Docker Desktop to ensure that Docker is running.

Next, run the following command to start the container. If no edits are needed, just copy and paste:

🪟 Windows (PowerShell)
$MY_WEB_PORT = 8080  # Web port on your side
$IMAGE_NAME = "ghcr.io/st-tech/ppf-contact-solver-compiled:latest"
docker run --rm -it `
  --name ppf-contact-solver `
  --gpus all `
  -p ${MY_WEB_PORT}:${MY_WEB_PORT} `
  -e WEB_PORT=${MY_WEB_PORT} `
  $IMAGE_NAME # Image size ~1GB
🐧 Linux (Bash/Zsh)
MY_WEB_PORT=8080  # Web port on your side
IMAGE_NAME=ghcr.io/st-tech/ppf-contact-solver-compiled:latest
docker run --rm -it \
  --name ppf-contact-solver \
  --gpus all \
  -p ${MY_WEB_PORT}:${MY_WEB_PORT} \
  -e WEB_PORT=${MY_WEB_PORT} \
  $IMAGE_NAME # Image size ~1GB

The image download shall be started. Our image is hosted on GitHub Container Registry (~1GB). JupyterLab will then auto-start. Eventually you should be seeing:

==== JupyterLab Launched! 🚀 ====
     http://localhost:8080
    Press Ctrl+C to shutdown
================================

Next, open your browser and navigate to http://localhost:8080. The port 8080 can change if you change the MY_WEB_PORT variable. Keep your terminal window open. Now you are ready to go! 🎉

🛑 Shutting Down

To shut down the container, just press Ctrl+C in the terminal. The container will be removed and all traces will be cleaned up. 🧹

If you wish to keep the container running in the background, replace --rm with -d. To shutdown the container and remove it, run docker stop ppf-contact-solver && docker rm ppf-contact-solver.

🔧 Advanced Installation

If you wish to build the docker image from scratch, please refer to the cleaner installation guide (Markdown).

🐍 How To Use

Our frontend is accessible through a browser using our built-in JupyterLab interface. All is set up when you

Core symbols most depended-on inside this repo

get
called by 55
frontend/_scene_.py
dot3
called by 45
frontend/_bvh_.py
copy
called by 43
frontend/_param_.py
items
called by 33
frontend/_param_.py
update
called by 29
frontend/_scene_.py
max
called by 24
frontend/_scene_.py
run
called by 23
warmup.py
check_contact_offset_violation
called by 22
frontend/_proximity_.py

Shape

Method 430
Function 273
Class 67

Languages

Python100%

Modules by API surface

frontend/_scene_.py169 symbols
frontend/_session_.py110 symbols
frontend/_mesh_.py61 symbols
frontend/_sdf_.py40 symbols
frontend/tests/_invisible_collider_.py33 symbols
warmup.py30 symbols
frontend/_plot_.py28 symbols
frontend/_app_.py28 symbols
frontend/_bvh_.py27 symbols
frontend/_asset_.py23 symbols
frontend/_proximity_.py19 symbols
eigsys/eigsys_invariants_2.py17 symbols

For agents

$ claude mcp add ppf-contact-solver \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact