🎉 Release new version v0.4.6

CITATION.cff

@@ -1,32 +1,29 @@
 cff-version: 1.2.0
-message: "If you use this software, please cite it as below."
+message: "If you find MaterialPointSolver.jl useful or have used it in your research, please cite it as follows."
 authors:
-- family-names: "Huo"
-  given-names: "Zenan"
-  orcid: "https://orcid.org/0000-0000-0000-0000"
-- family-names: "Bot"
-  given-names: "Hew"
-  orcid: "https://orcid.org/0000-0000-0000-0000"
-title: "My Research Software"
-version: 2.0.4
-doi: 10.5281/zenodo.1234
-date-released: 2017-12-18
-url: "https://github.com/github-linguist/linguist"
-preferred-citation:
-  type: article
-  authors:
-  - family-names: "Lisa"
-    given-names: "Mona"
-    orcid: "https://orcid.org/0000-0000-0000-0000"
-  - family-names: "Bot"
-    given-names: "Hew"
-    orcid: "https://orcid.org/0000-0000-0000-0000"
-  doi: "10.0000/00000"
-  journal: "Journal Title"
-  month: 9
-  start: 1 # First page number
-  end: 10 # Last page number
-  title: "My awesome research software"
-  issue: 1
-  volume: 1
-  year: 2021
+  - family-names: Huo
+    given-names: Zenan
+  - family-names: Alkhimenkov
+    given-names: Yury
+  - family-names: Jaboyedoff
+    given-names: Michel
+  - family-names: Podladchikov
+    given-names: Yury
+  - family-names: Räss
+    given-names: Ludovic
+  - family-names: Wyser
+    given-names: Emmanuel
+  - family-names: Mei
+    given-names: Gang
+title: "A high-performance backend-agnostic Material Point Method solver in Julia"
+journal: "Computers and Geotechnics"
+volume: 183
+start: 107189  # 对应 pages 的起始页码
+year: 2025
+doi: "10.1016/j.compgeo.2025.107189"
+url: "https://www.sciencedirect.com/science/article/pii/S0266352X25001387"
+keywords:
+  - "MPM"
+  - "Julia language"
+  - "Heterogeneous computing"
+  - "Effective memory throughput"

Project.toml

@@ -1,27 +1,32 @@
 name = "MaterialPointSolver"
 uuid = "dc4aa359-7d89-437d-91bb-f4b330c522c1"
 authors = ["Zenan Huo <zenan.huo@outlook.com>"]
-version = "0.4.5"
+version = "0.4.6"
 
 [deps]
 Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 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"
+CodecZlib = "0.7"
 DelimitedFiles = "1.9"
 HDF5 = "0.17"
 KernelAbstractions = "0.9"
 ProgressMeter = "1.10"
+StatsBase = "0.34"
 Suppressor = "0.2"
 SysInfo = "0.3"
 julia = "1.11"
@@ -31,12 +36,14 @@ 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"
 
 [extensions]
 MaterialPointSolverAMDGPUExt = "AMDGPU"
 MaterialPointSolverCUDAExt = "CUDA"
 MaterialPointSolverMetalExt = "Metal"
 MaterialPointSolveroneAPIExt = "oneAPI"
+MaterialPointSolverDebugExt = "WGLMakie"
 
 [extras]
 AMDGPU = "21141c5a-9bdb-4563-92ae-f87d6854732e"
@@ -46,6 +53,8 @@ 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"
 
 [targets]
 test = ["Test", "BenchmarkTools", "DelimitedFiles"]

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.5-pink)]()
+[![Version](https://img.shields.io/badge/version-v0.4.6-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,7 +14,9 @@
 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>
 
-<img src="docs/assets/readme.gif" width="100%" align="center">
+> 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 ⚙️
 
@@ -65,31 +67,44 @@ julia> ]
   - ✅ 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">
+
 ## Citation 🔥
 
 If you find `MaterialPointSolver.jl` useful or have used it in your research, please cite it as follows:
 
 ```bib
-@article{index,
-  title={Here is the title},
-  author={authors},
-  journal={journal},
-  year={year}
+@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}
 }
 ```
 > [!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.
+
 ## Acknowledgement 👍
 
 This project is sponsored by [Risk Group | Université de Lausanne](https://wp.unil.ch/risk/) and [China Scholarship Council [中国国家留学基金管理委员会]](https://www.csc.edu.cn/).
 
 ## MPM ➕ Julia
 
-* [[package]: elastoPlasm.jl](https://github.com/ewyser/elastoPlasm.jl) is fully witten in Julia, it solves explicit elasto-plastic problems within a finite deformation framework.
+* [📦 [package]: elastoPlasm.jl](https://github.com/ewyser/elastoPlasm.jl) is fully witten in Julia, it solves explicit elasto-plastic problems within a finite deformation framework.
 
-* [[package]: Tesserae.jl](https://github.com/KeitaNakamura/Tesserae.jl) is an MPM-related Julia package, it provides some useful functions that can be used for MPM, such as convenient macros for transferring data between grids and particles.
+* [📦 [package]: Tesserae.jl](https://github.com/KeitaNakamura/Tesserae.jl) is an MPM-related Julia package, it provides some useful functions that can be used for MPM, such as convenient macros for transferring data between grids and particles.
 
-* [[code]: MPM-Julia](https://github.com/vinhphunguyen/MPM-Julia) is the code for the paper: Sinai, V.P. Nguyen, C.T. Nguyen and S. Bordas. Programming the Material Point Method in Julia. Advances in Engineering Software,105: 17--29, 2017.
+* [✍️ [code]: MPM-Julia](https://github.com/vinhphunguyen/MPM-Julia) is the code for the paper: Sinai, V.P. Nguyen, C.T. Nguyen and S. Bordas. Programming the Material Point Method in Julia. Advances in Engineering Software,105: 17--29, 2017.
 
-* [[code]: jump](https://github.com/vinhphunguyen/jump) is for the theory of the MPM described in the book 'The Material Point Method: Theory, Implementations and Applications (Scientific Computation) 1st ed. 2023 Edition'. [https://link.springer.com/book/10.1007/978-3-031-24070-6](https://link.springer.com/book/10.1007/978-3-031-24070-6)
+* [[✍️ code]: jump](https://github.com/vinhphunguyen/jump) is for the theory of the MPM described in the book 'The Material Point Method: Theory, Implementations and Applications (Scientific Computation) 1st ed. 2023 Edition'. [https://link.springer.com/book/10.1007/978-3-031-24070-6](https://link.springer.com/book/10.1007/978-3-031-24070-6)

docs/Project.toml

@@ -2,10 +2,12 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 MaterialPointSolver = "dc4aa359-7d89-437d-91bb-f4b330c522c1"
+WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
 
 [sources]
 MaterialPointSolver = {path = ".."}
 
 [compat]
 Documenter = "1.8"
-DocumenterVitepress = "0.1"
+DocumenterVitepress = "0.1"
+WGLMakie = "0.11"

docs/make.jl

@@ -1,4 +1,4 @@
-using Documenter, DocumenterVitepress, MaterialPointSolver
+using Documenter, DocumenterVitepress, MaterialPointSolver, WGLMakie
 
 makedocs(
     modules = [MaterialPointSolver],
@@ -23,8 +23,7 @@ makedocs(
             "interface/kernelfunctions.md",
             "interface/mpmprocess.md",
             "interface/workflow.md",
-            "interface/import.md",
-            "interface/export.md"
+            "interface/imexport.md",
         ],
         "Tutorials" => Any[
             "tutorials/example1.md",
@@ -38,8 +37,9 @@ makedocs(
             "advancedtopics/customextension.md",
             "advancedtopics/customfriction.md"
         ],
-        "utils.md",
-        "showcases.md"
+        "Useful Tools" => Any[
+            "utils/debug.md",
+        ]
     ],
     warnonly = [:missing_docs, :cross_references],
 )

docs/src/interface/imexport.md

@@ -0,0 +1,21 @@
+# Import/Export Simulation Results
+
+We use Julia's built-in [`Serialization`](https://docs.julialang.org/en/v1/stdlib/Serialization/#Serialization) functionality to implement the import and export of models. Sometimes the model file size is too large, so we use CodecZlib for compression (optional), and automatically determine whether it is a compressed file when reading.
+
+
+!!! note
+
+    We use the file suffix `.mpm` to denote model files generated by ***MaterialPointSolver.jl***.
+
+```@docs
+exportmodel(
+    args      ::     DeviceArgs{T1, T2}, 
+    grid      ::     DeviceGrid{T1, T2},
+    mp        :: DeviceParticle{T1, T2},
+    attr      :: DeviceProperty{T1, T2},
+    bc        ::DeviceVBoundary{T1, T2}; 
+    model_file::String = "temp.mpm",
+    compress  ::Bool   = true
+) where {T1, T2}
+importmodel(mpm_file::String)
+```

docs/src/utils/debug.md

@@ -0,0 +1,113 @@
+# Debug Mode (in-situ visualization)
+
+We have provided a mode that can display simulation results in real-time, which we call "debug mode." It is also backend-agnostic and happens to enable in-situ visualization. The original intent of this design was to allow users to immediately view the computation results while running a simulation. If the results do not develop as expected, the computation can be terminated at any time for a quick code review.
+
+Note that this feature will only be enabled after the user explicitly calls WGLMakie:
+
+```@example debug
+using MaterialPointSolver
+using WGLMakie
+```
+
+!!! note
+
+    - We implement this functionality through WGLMakie.jl, which theoretically supports computations on a remote headless server. However, as WGLMakie.jl is still in an experimental stage, we recommend launching Debug mode only on local machine for now.  
+    - We prefer to always use the plot panel provided by the Julia Language plugin in VSCode to display results; please enable the plot panel in the julia-vscode plugin.  
+    - The current maximum number of particles displayed is 500,000, but this can be customized by the user.
+
+## API
+
+In normal mode, we assume that you have already instantiated and obtained `args`, `grid`, `mp`, `attr`, and `bc`.
+
+:::tabs
+
+== normal mode
+
+```julia
+materialpointsolver!(args, grid, mp, attr, bc)
+```
+
+== debug mode
+
+```julia
+materialpointsolver!(args, grid, mp, attr, bc, debug)
+```
+
+:::
+
+where the type of `debug` is `DebugConfig`:
+
+```@docs
+DebugConfig
+```
+
+The current `DebugPlot` type has only one field, `plot::DebugPlot`, but more features may be added in the future.
+
+The type of `plot` is `DebugPlot`:
+
+```@docs
+DebugPlot
+```
+
+Here, we may need to explain the meaning of the calculate field in `DebugPlot`. Sometimes, the values we want to display might be derived from multiple attributes, such as displacement, so we need to define the computation rules.
+
+!!! note
+
+    - The return type of the user-defined `calculate` function must currently be a vector with the same length as the number of material points, and the input parameters of this custom function should always be: (i) `grid`, (ii) `mp`, (iii) `attr`, (iv) `bc`, and (v) vid, with the order fixed and unchangeable.  
+    - Users can directly use `debug=DebugConfig()`, which will apply the default debug configuration, visualizing the color based on the density of the material points.
+
+
+## Examples
+
+If you want to visualize the equivalent plastic strain, then：
+
+```@example debug
+plotfunc(grid, mp, attr, bc, vid) = Array{Float32, 1}(mp.ϵq)
+plotconfig = DebugPlot(cbname="equivalent plastic strain", calculate=plotfunc)
+debug = DebugConfig(plot=plotconfig)
+```
+
+```@raw html
+<img src="./figures/debug1.png" width=100%>
+```
+
+If you want to visualize the displacement：
+
+```@example debug
+function tmpf(grid, mp, attr, bc, vid)
+    ξ0 = Array{Float32, 2}(mp.ξ0[vid, :])
+    ξ1 = Array{Float32, 2}(mp.ξ[vid, :] )
+
+    val = @. sqrt((ξ1[:, 1] - ξ0[:, 1])^2 .+ 
+                  (ξ1[:, 2] - ξ0[:, 2])^2 .+ 
+                  (ξ1[:, 3] - ξ0[:, 3])^2)
+    return val
+end
+plotconfig = DebugPlot(pointsize=1, axis=true, axfontsize=10, calculate=tmpf, cbname="disp")
+debug = DebugConfig(plotconfig)
+```
+
+```@raw html
+<img src="./figures/debug2.png" width=100%>
+```
+
+If you need a smooth visualization, try to decrease the `pointsize` or `pointnum`:
+
+
+```@example debug
+function tmpf(grid, mp, attr, bc, vid)
+    ξ0 = Array{Float32, 2}(mp.ξ0[vid, :])
+    ξ1 = Array{Float32, 2}(mp.ξ[vid, :] )
+
+    val = @. sqrt((ξ1[:, 1] - ξ0[:, 1])^2 .+ 
+                  (ξ1[:, 2] - ξ0[:, 2])^2 .+ 
+                  (ξ1[:, 3] - ξ0[:, 3])^2)
+    return val
+end
+plotconfig = DebugPlot(pointsize=1f-2, axis=true, axfontsize=10, calculate=tmpf, cbname="disp", pointnum=1000) # [!code focus]
+debug = DebugConfig(plotconfig)
+```
+
+```@raw html
+<img src="./figures/debug3.png" width=100%>
+```