GeoTaichi
Quick start | Capabilities | Coupling formulations | Examples | Documentation | Citation | Contact
Brief description
GeoTaichi is an open-source, Taichi-powered simulation framework for granular materials, deformable solids, incompressible fluids, and coupled soil–water–structure interaction. It combines the material point method (MPM), discrete element method (DEM), level-set DEM (LSDEM), affine body dynamics (ABD), finite element method (FEM), and isogeometric analysis (IGA) with explicit, semi-implicit, and implicit solver routes.
Developed by Multiscale Geomechanics Lab, Zhejiang University.
Overview
GeoTaichi targets multiscale and multiphysics geomechanics: large-deformation and elastoplastic solids, arbitrarily shaped grains, free-surface flow, saturated porous media, and contact with deformable or nearly rigid structures. Solver modules can be used independently or combined through explicit contact exchange, immersed boundary methods (IBM), or fully coupled incremental potential contact (IPC).
GeoTaichi is an actively developed research project released under GPL-3.0. Taichi provides parallel CPU and GPU execution on supported Windows, Linux, and macOS configurations. Backend, precision, dimensionality, and material support depend on the selected solver; the module READMEs document these restrictions.
Examples
Have an example to share? Submit a PR!
Explicit MPM
Semi-implicit Incompressible MPM
Two-phase Semi-implicit MPM
Explicit Soft Constraint
Implicit Affine Body Dynamics (ABD)
Explicit Soft Constraint
Explicit MPM-DEM
Semi-implicit MPM with Immersed Boundary Method
Implemented routes include Solid MPM–ABD impact.
Core capabilities
- MPM: explicit and implicit solid mechanics with sparse grid and adaptive refinement, semi-implicit incompressible flow, and two-phase porous-media formulations.
- DEM, LSDEM, and ABD: spheres and clumps, signed-distance representations of irregular rigid particles, granular contact, and implicit affine-body mechanics with IPC.
- FEM and IGA: volume, membrane, and cloth FEM; NURBS-based IGA; explicit and implicit mechanics with formulation-specific material and contact support.
- MPM–DEM: explicit continuum–grain contact and semi-resolved incompressible fluid–sphere coupling.
- MPM–LSDEM: explicit level-set contact, fully resolved incompressible IBM, and hybrid two-phase solid–fluid–grain coupling.
- MPM–ABD: solid and hyperelastic soft-particle IPC.
- FEM–DEM: explicit grain–deformable-surface contact.
- FEM–LSDEM: deforming FEM boundaries interact with rigid-particle signed-distance geometry.
- FEM–ABD: fully coupled IPC for volume, membrane, and cloth structures.
- FEM–MPM: explicit contact exchange and fully coupled implicit IPC with elastic or plastic MPM.
- IGA–MPM: independent NURBS structures and MPM continua coupled through explicit contact or implicit point–NURBS IPC.
- Verification and tests distinguish unit/integration checks from numerical comparisons against analytical or published references. Each solver README links its example-backed features to the relevant theory log.
GeoTaichi introduces three new coupling formulations: MPM–ABD IPC, incompressible MPM–DEM coupling (fully resolved LSDEM volume-fraction IBM and semi-resolved sphere coupling), and IGA–MPM point–NURBS contact coupling. These contributions concern the coupling operators and formulations built on established MPM, ABD, DEM, LSDEM, IGA, IBM, and IPC methods. Their derivations, implementation details, and concrete examples are documented in the linked theory logs below.
| Formulation |
Method and scope |
Theory |
| Incompressible material point method–DEM coupling |
Fully resolved 3D MPM–LSDEM uses rigid-body SDFs to estimate cell solid fractions and apply volume-fraction IBM forcing. Semi-resolved 3D MPM–sphere DEM uses normalized Gaussian volume mapping, porosity-aware pressure projection, and drag/pressure-force exchange. |
LSDEM volume-fraction IBM; Semi-resolved sphere coupling |
| Isogeometric analysis–material point method coupling (IGA–MPM) |
Independent deformable NURBS IGA structures and MPM continua interact through point–NURBS contact. The linked 3D examples demonstrate explicit DEM-law exchange and fully coupled implicit IPC with elastic or plastic MPM blocks. |
IGA–MPM theory log |
| Material point method–affine body dynamics coupling (MPM–ABD) |
Fully coupled solid MPM–ABD IPC couples active MPM-grid displacements and affine-body controls, including supported finite-strain plasticity. This route is currently 3D with lagged friction. Hyperelastic soft-MPM–ABD IPC and incompressible fluid–ABD IBM are separate routes. |
MPM–ABD derivation |
Quick start
Install from source
GeoTaichi is distributed through this source repository. There is no supported PyPI installation workflow. Use Python 3.10 or newer; the dependency declarations are maintained in pyproject.toml.
Clone the repository and create a Python environment:
git clone https://github.com/Yihao-Shi/GeoTaichi.git
cd GeoTaichi
python -m venv .venv
Activate it on Linux/macOS:
source .venv/bin/activate
Or in Windows PowerShell:
.\.venv\Scripts\Activate.ps1
Install the local checkout, not a GeoTaichi package from PyPI:
python -m pip install --upgrade pip
python -m pip install -e .
The editable install makes geotaichi importable without manually setting PYTHONPATH. Some geometry dependencies may need platform-specific system libraries. Select a backend supported by your hardware and solver; not all implicit GPU routes support the same precision or devices.
Run an example
Run commands from the repository root. For a small, CPU-selectable coupling example:
python examples/mpdem/AffineBody/ABDImpactDP/direct_mpm_abd_impact.py --arch cpu --steps 10
For the explicit column-collapse example:
python examples/mpm/column_collapse/DPmaterial.py
The latter uses the default GPU initialization. If using CPU, change its initialization to init(arch="cpu", default_fp="float64"); arch must be passed by name, not as init('cpu'). Check each example’s configuration, input assets, and output directory before running a full simulation.
Visualization
Simulation outputs can be inspected in ParaView by opening a .vtu or .vts time series, selecting Apply, and choosing the representation and field to display. Developer tools describe the particle-field and Blender rendering workflows used for the gallery. Rendered surfaces are visualization reconstructions, not a replacement for the underlying simulation data.
Documentation
Documentation is maintained alongside the source. Module READMEs describe supported formulations, theory logs, configuration, workflows, and limitations:
- Core solvers: MPM, DEM, FEM, and IGA.
- Coupled solvers: MPM–DEM, FEM–DEM, FEM–MPM, and IGA–MPM.
- Shared models and numerics: Constitutive models, Contact models, Contact detection, and Linear solvers.
- Usage and development: Python examples, Solver integration principles, Blender add-on, Developer tools, and Tests and verification.
Start with the README for your solver and a matching Python example. Additional derivations and technical notes are available in docs.
License
This project is licensed under the GNU General Public License v3 - see the LICENSE for details.
Citation
If GeoTaichi supports your research, please consider starring the repository and citing the relevant publications.
The publications below describe the original framework and GPU level-set DEM. For newer coupling formulations, consult the linked theory logs, examples, and source revision; these papers should not be read as publications of every feature currently in the repository.
If you publish work that makes use of GeoTaichi, please cite the relevant references:
@article{shi2024geotaichi,
title={GeoTaichi: A Taichi-powered high-performance numerical simulator for multiscale geophysical problems},
author={Shi, YH and Guo, N and Yang, ZX},
journal={Computer Physics Communications},
volume={301},
pages={109219},
year={2024},
publisher={Elsevier}
}
@article{shi2025gpu,
title={GPU-accelerated level-set DEM for arbitrarily shaped particles with broad size distributions},
author={Shi, YH and Guo, N and Yang, ZX},
journal={Powder Technology},
pages={121293},
year={2025},
publisher={Elsevier}
}
Acknowledgements
We thank all amazing contributors for their great work and open source spirit. We welcome all kinds of contributions to file an issue at GitHub Issues.
Contributors
Release Notes
V0.5.0 (Oct 2, 2026)
- Please click here for more details
V0.4.0 (Aug 27, 2025)
- Please click here for more details
V0.3.0 (December 12, 2024)
- Please click here for more details
V0.2.2 (July 22, 2024)
- Fix computing the intersection area between circles and triangles
- Add “Destory” and “Reflect” boundaries in DEM modules, see the v0.2.2 release
V0.2 (July 1, 2024)
- Fix some bugs in DEM and MPM modules, see details
- Add some advanced constitutive model
V0.1 (January 21, 2024)
评论