LandslideSIM · ZenanH · Aug 3, 2025 · Mar 28, 2025 · Apr 6, 2025 · Apr 6, 2025
diff --git a/.gitignore b/.gitignore
@@ -24,4 +24,5 @@ docs/site/
 Manifest.toml
 .vscode
 .ipynb_checkpoints
-.DS_Store
+.DS_Store
+.CondaPkg
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "MaterialPointSolver"
 uuid = "dc4aa359-7d89-437d-91bb-f4b330c522c1"
 authors = ["Zenan Huo <zenan.huo@outlook.com>"]
-version = "0.4.7"
+version = "0.5.0"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
@@ -11,50 +11,48 @@ Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
-ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
-StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 SysInfo = "90a7ee08-a23f-48b9-9006-0e0e2a9e4608"
 
 [compat]
-Adapt = "4.0"
-BenchmarkTools = "1.5"
+Adapt = "4.3"
+BenchmarkTools = "1.6"
 CodecZlib = "0.7"
 DelimitedFiles = "1.9"
 HDF5 = "0.17"
 KernelAbstractions = "0.9"
-ProgressMeter = "1.10"
-StatsBase = "0.34"
-Suppressor = "0.2"
+PrecompileTools = "1.2"
+PrettyTables = "2.4"
 SysInfo = "0.3"
 julia = "1.11"
 
 [weakdeps]
 AMDGPU = "21141c5a-9bdb-4563-92ae-f87d6854732e"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 Metal = "dde4c033-4e86-420c-a63e-0dd931031962"
-oneAPI = "8f75cd03-7ff8-4ecb-9b8f-daf728133b1b"
 WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
+oneAPI = "8f75cd03-7ff8-4ecb-9b8f-daf728133b1b"
 
 [extensions]
 MaterialPointSolverAMDGPUExt = "AMDGPU"
 MaterialPointSolverCUDAExt = "CUDA"
 MaterialPointSolverMetalExt = "Metal"
 MaterialPointSolveroneAPIExt = "oneAPI"
-MaterialPointSolverDebugExt = "WGLMakie"
 
 [extras]
 AMDGPU = "21141c5a-9bdb-4563-92ae-f87d6854732e"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 Metal = "dde4c033-4e86-420c-a63e-0dd931031962"
-oneAPI = "8f75cd03-7ff8-4ecb-9b8f-daf728133b1b"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
-BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
-StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
+oneAPI = "8f75cd03-7ff8-4ecb-9b8f-daf728133b1b"
 
 [targets]
 test = ["Test", "BenchmarkTools", "DelimitedFiles"]
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![CI](https://github.com/LandslideSIM/MaterialPointSolver.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/LandslideSIM/MaterialPointSolver.jl/actions/workflows/ci.yml) 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg?logo=quicklook)](https://landslidesim.github.io/MaterialPointSolver.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-red.svg?logo=quicklook)](https://landslidesim.github.io/MaterialPointSolver.jl/dev/)
-[![Version](https://img.shields.io/badge/version-v0.4.7-pink)]()
+[![Version](https://img.shields.io/badge/version-v0.5.0-pink)]()
 
 [![](https://img.shields.io/badge/NVIDIA-CUDA-green.svg?logo=nvidia)](https://developer.nvidia.com/cuda-toolkit)
 [![](https://img.shields.io/badge/AMD-ROCm-red.svg?logo=amd)](https://www.amd.com/en/products/software/rocm.html)
@@ -14,8 +14,6 @@
 This package provides a high-performance, backend-agnostic implementation of the Material Point Method (MPM) using the <a href="https://julialang.org" target="_blank"><img src="https://raw.githubusercontent.com/JuliaLang/julia-logo-graphics/master/images/julia.ico" width="16em"> Julia Language</a>. It is lightweight and user-friendly, allowing efficient execution on various hardware accelerators with a single codebase. Please check here for the <a href="https://landslidesim.github.io/MaterialPointSolver.jl/stable/" target="_blank">documentation</a>.
 </p>
 
-> If you have a GPU from Intel® and want to try on it, please [contact me 📧](mailto:zenan.huo@outlook.com).
-
 <img src="https://cdn.jsdelivr.net/gh/LandslideSIM/MaterialPointSolver.jl@main/docs/assets/readme.gif" width="100%" align="center">
 
 ## Installation ⚙️
@@ -27,73 +25,34 @@ julia> ]
 (@1.11) Pkg> add MaterialPointSolver
 ```
 
-## Features 💪
-
-*These features can be combined in any way, but MLS-MPM can only use quadratic b-spline for the speed*
-
-- Basis function:
-
-  - ✅ standard MPM
-  - ✅ uGIMP (uniformed Generalized interpolation MPM)
-  - ✅ quadratic B-spline
-  - ✅ cubic B-spline (boundary modified)
-
-- Stress update scheme:
-
-  - ✅ USL (update stress last)
-  - ✅ USF (update stress first)
-  - ✅ MUSL (modified USL)
-
-- MPM formulation:
 
-  - ✅ one-phase single-point
-  - 🚧 two-phase single-point (saturated/unsaturated)
+## Design Philosophy 🧠
 
-- Constitutive model:
-
-  - ✅ linear elastic
-  - ✅ hyper elastic (Neo-Hookean)
-  - ✅ Drucker-Prager (with softening/harding)
-  - 🚧 Mohr-Coulomb
-  - ✅ Bingham
-
-    …
-
-- Others:
-
-  - ✅ Affine/MLS-MPM
-  - ✅ $\bar{F}$-based volumetric locking elimination
-  - ✅ Gaussian random field
-  - ✅ one-click switch between `FP64` and `FP32`
-  - ✅ user-defined algorithms/extensions at any level
-
-There is a `debug` model can be used to make sure the simulation is working as expect. It's also can be used for in-situ visualization in VSCode.
-
-<img src="https://cdn.jsdelivr.net/gh/LandslideSIM/MaterialPointSolver.jl@main/docs/assets/debug.gif" width="100%" align="center">
+- [x] A high-performance MPM solver for flexible scientific prototyping
+- [x] Supports user-defined fields and custom logic (e.g. acoustics, heat)
+- [x] Can be used in production environments with care to avoid performance regressions
+- [x] All MPM algorithms are modularized as plugins for easy modification and sharing
 
 ## Citation 🔥
 
 If you find `MaterialPointSolver.jl` useful or have used it in your research, please cite it as follows:
 
 ```bib
 @article{HUO2025107189,
-title = {A high-performance backend-agnostic Material Point Method solver in Julia},
-journal = {Computers and Geotechnics},
-volume = {183},
-pages = {107189},
-year = {2025},
-issn = {0266-352X},
-doi = {https://doi.org/10.1016/j.compgeo.2025.107189},
-url = {https://www.sciencedirect.com/science/article/pii/S0266352X25001387},
-author = {Zenan Huo and Yury Alkhimenkov and Michel Jaboyedoff and Yury Podladchikov and Ludovic Räss and Emmanuel Wyser and Gang Mei},
-keywords = {MPM, Julia language, Heterogeneous computing, Effective memory throughput}
+    title = {A high-performance backend-agnostic Material Point Method solver in Julia},
+    journal = {Computers and Geotechnics},
+    volume = {183},
+    pages = {107189},
+    year = {2025},
+    issn = {0266-352X},
+    doi = {https://doi.org/10.1016/j.compgeo.2025.107189},
+    url = {https://www.sciencedirect.com/science/article/pii/S0266352X25001387},
+    author = {Zenan Huo and Yury Alkhimenkov and Michel Jaboyedoff and Yury Podladchikov and Ludovic Räss and Emmanuel Wyser and Gang Mei},
+    keywords = {MPM, Julia language, Heterogeneous computing, Effective memory throughput}
 }
 ```
 > [!CAUTION]
-> This is the latest version of `MaterialPointSover.jl`, if you want to see the examples in the paper, please move to [https://github.com/LandslideSIM/Archive_MaterialPointSolver.jl_paper](https://github.com/LandslideSIM/Archive_MaterialPointSolver.jl_paper).
-
-> [!TIP]
-> After the article was published, we released many new features and achieved significant performance improvements. We are currently actively working on completing the documentation. If possible, you can directly review the source code.
+> This repo is the LATEST version of `MaterialPointSover.jl`. After the article was published, we released many new features and achieved significant performance improvements. Please move to [https://github.com/LandslideSIM/Archive_MaterialPointSolver.jl_paper](https://github.com/LandslideSIM/Archive_MaterialPointSolver.jl_paper) for the code used in the paper.
 
 ## Acknowledgement 👍
 

diff --git a/docs/make.jl b/docs/make.jl
@@ -15,30 +15,18 @@ makedocs(
             "introduction/getstarted.md",
             "introduction/why.md",
             "introduction/ecosystem.md",
-            "introduction/tips.md",
         ],
-        "Interface" => Any[
-            "interface/structs.md",
-            "interface/backendagnostic.md",
-            "interface/kernelfunctions.md",
-            "interface/mpmprocess.md",
-            "interface/workflow.md",
-            "interface/imexport.md",
-        ],
-        "Tutorials" => Any[
-            "tutorials/example1.md",
-            "tutorials/example2.md",
-            "tutorials/example3.md"
+        "DataType System" => Any[
+            "datatype/backgroundgrid.md",
         ],
         "Advanced Topics" => Any[
-            "advancedtopics/customkernel.md",
-            "advancedtopics/customconstitutive.md",
-            "advancedtopics/custommpmprocess.md",
-            "advancedtopics/customextension.md",
-            "advancedtopics/customfriction.md"
+            "advancedtopics/plugin.md",
+        ],
+        "Examples" => Any[
+            "examples/example1.md",
         ],
-        "Useful Tools" => Any[
-            "utils/debug.md",
+        "Others" => Any[
+            "others/gpu.md",
         ]
     ],
     warnonly = [:missing_docs, :cross_references],

diff --git a/docs/src/advancedtopics/customconstitutive.md b/docs/src/advancedtopics/customconstitutive.md
diff --git a/docs/src/advancedtopics/customextension.md b/docs/src/advancedtopics/customextension.md
diff --git a/docs/src/advancedtopics/customfriction.md b/docs/src/advancedtopics/customfriction.md
diff --git a/docs/src/advancedtopics/customkernel.md b/docs/src/advancedtopics/customkernel.md
diff --git a/docs/src/advancedtopics/custommpmprocess.md b/docs/src/advancedtopics/custommpmprocess.md
diff --git a/docs/src/advancedtopics/plugin.md b/docs/src/advancedtopics/plugin.md
@@ -0,0 +1,3 @@
+# Plugin System
+
+... todo
diff --git a/docs/src/datatype/backgroundgrid.md b/docs/src/datatype/backgroundgrid.md
@@ -0,0 +1 @@
+# Backgroud Grid
diff --git a/docs/src/examples/example1.md b/docs/src/examples/example1.md
@@ -0,0 +1,60 @@
+# 2D Soil Collapse Test
+
+!!! note
+
+    1) We use a classic example: 2D & 3D granular collapse[^1], to demonstrate how to establish computational models and solve them. 
+    2) To successfully run the code, we will install the dependencies at the beginning of the code provided below. If you are already familiar with the Julia Pkg ENV and have installed the necessary packages, you can ignore this part.
+    3) We default to using Nvidia's GPU or x86/ARM CPUs. If you want to use other acceleration backends, please make modifications in the appropriate places in the code.
+    4) We use Unicode to enhance readability (when comparing formulas), but sometimes it may be confused with regular letters, such as ``\nu`` and `v`. If you are using VSCode, you can enable the following in the settings:
+
+       ```json
+       "editor.unicodeHighlight.ambiguousCharacters": true,
+       ```
+
+    5) You can copy and save it in the `your_file.jl` and run the file directly using Julia in `REPL`:
+
+       ```julia-repl
+       julia> include("path/to/your_file.jl")
+       ```
+
+        Or run this file in the terminal:
+
+       ```bash
+       bash> julia path/to/your_file.jl
+       ```
+
+[^1]: Bui, H.H., Fukagawa, R., Sako, K., Ohno, S., 2008. Lagrangian meshfree particles method (SPH) for large deformation and failure flows of geomaterial using elastic–plastic soil constitutive model. Int. J. Numer. Anal. Methods Geomech. 32, 1537–1570. https://doi.org/10.1002/nag.688
+
+::: details Here is the complete 2D code
+
+```julia
+using Pkg
+Pkg.add(["MaterialPointSolver", "MaterialPointGenerator", "CairoMakie", "CUDA"])
+using MaterialPointSolver
+using MaterialPointGenerator
+using CairoMakie
+using CUDA
+```
+
+:::
+
+## 2D model description
+
+```@raw html
+<br>
+<img src="./figures/exp_model.png" width=50%>
+<br>
+```
+
+In this example, aluminum bars are used to model the non-cohesive soil collapse. We use uGIMP to simulate the failure process of soil collapse. The geometry of the numerical model is depicted in the figure, with a length ``l`` of ``0.2\ m`` and a height ``h`` of ``0.1\ m``. The parameters of the numerical model are provided in the Table.
+
+| Parameter   | Value            | Unit       | Description            |
+|:-----------:|:----------------:|:----------:|:----------------------:|
+| ``\rho``    | ``2650``         | ``kg/m^3`` | density                |
+| ``\mu``     | ``0.3``          | -          | Poisson's ratio        |
+| ``K``       | ``7\times 10^5`` | ``Pa``     | bulk modulus           |
+| ``t_{sim}`` | ``1.0``          | second     | simulation time        |
+| ``\phi``    | ``19.8``         | degree     | friction angle         |
+| ``\alpha``  | ``1.0``          |  -         | FLIP-PIC mixing factor |
+
+## 2D code explaination
diff --git a/docs/src/tutorials/figures/exp_model.png → docs/src/examples/figures/exp_model.png b/docs/src/tutorials/figures/exp_model.png → docs/src/examples/figures/exp_model.png
diff --git a/docs/src/interface/backendagnostic.md b/docs/src/interface/backendagnostic.md
diff --git a/docs/src/interface/imexport.md b/docs/src/interface/imexport.md