Improve usability

.devcontainer/devcontainer.json

@@ -1,42 +1,25 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
 {
-    "name": "python dev",
-    "image": "mcr.microsoft.com/devcontainers/python:3.12",
-    "mounts": [
-		"source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached"
-	],
-    "customizations":{
+    "name": "HydraxMPM",
+    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+    "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+    "features": {},
+
+    // Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": "./.devcontainer/postCreateCommand.sh",
+
+    // Configure tool-specific properties.
+    "customizations": {
         "vscode": {
-            "extensions":[
-                "ms-python.python",
-                "ms-python.vscode-pylance",
-                "GitHub.copilot",
-                "oderwat.indent-rainbow",
-                "aaron-bond.better-comments",
-                "njpwerner.autodocstring",
-                "spywhere.guides",
-                "charliermarsh.ruff",
-                "streetsidesoftware.code-spell-checker",
-                "ms-toolsai.jupyter",
-                "littlefoxteam.vscode-python-test-adapter",
-                "VisualStudioExptTeam.vscodeintellicode"
-            ],
+            "extensions": ["ms-python.python", "editorconfig.editorconfig"],
             "settings": {
-                "python.pythonPath": ".venv/bin/python",
-                "editor.rulers": [120],
-                "python.testing.unittestArgs": [
-                    "-v",
-                    "-s",
-                    "./tests",
-                    "-p",
-                    "test_*.py"
-                ],
-                "python.testing.pytestEnabled": false,
-                "python.testing.unittestEnabled": true,
-                "editor.defaultFormatter": "charliermarsh.ruff",
-                "editor.formatOnSave": true
+                "python.testing.pytestArgs": ["tests"],
+                "python.testing.unittestEnabled": false,
+                "python.testing.pytestEnabled": true,
+                "python.defaultInterpreterPath": "/workspaces/Shongololo/.venv/bin/python",
+                "python.testing.pytestPath": "/workspaces/Shongololo/.venv/bin/pytest"
             }
         }
-    },
-    "postCreateCommand": "curl -sSL https://install.python-poetry.org | python3 - && poetry install",
-
-}
+    }
+}

.devcontainer/postCreateCommand.sh

@@ -0,0 +1,10 @@
+#! /usr/bin/env bash
+
+# Install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install Dependencies
+uv sync
+
+# Install pre-commit hooks
+uv run pre-commit install --install-hooks

.github/workflows/ci.yml

@@ -1,8 +1,8 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
-      - master 
+      - master
       - main
 permissions:
   contents: write
@@ -26,11 +26,11 @@ jobs:
         run: uv python install 3.12
       - name: Sync UV
         run: uv sync --all-extras
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: uv run mkdocs gh-deploy --force
+      - run: uv run mkdocs gh-deploy --force

.github/workflows/run_tests.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.11", "3.12"]
-        
+
     steps:
       - uses: actions/checkout@v4
 

.gitignore

@@ -11,6 +11,12 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+core.*
+uv.lock
+imgui.ini
+polyscope.ini
+settings.json
+
 flowdex/
 
 # C extensions

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-yaml
+      - id: debug-statements
+      - id: trailing-whitespace
+      # - id: check-docstring-first
+
+  # - repo: https://github.com/astral-sh/ruff-pre-commit
+  #   rev: "v0.6.3"
+  #   hooks:
+  #     - id: ruff
+  #       args: [--exit-non-zero-on-fix]
+  #     - id: ruff-format

.vscode/settings.json

@@ -4,4 +4,4 @@
     ],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true
-}
+}

Makefile

@@ -0,0 +1,74 @@
+.PHONY: install
+install: ## Install the virtual environment and install the pre-commit hooks
+	@echo "🚀 Creating virtual environment using uv"
+	@uv sync
+	@uv run pre-commit install
+
+.PHONY: check
+check: ## Run code quality tools.
+	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+	@uv lock --locked
+	@echo "🚀 Linting code: Running pre-commit"
+	@uv run pre-commit run -a
+	# @echo "🚀 Static type checking: Running mypy"
+	# @uv run mypy
+	@echo "🚀 Checking for obsolete dependencies: Running deptry"
+	@uv run deptry .
+
+.PHONY: test
+test: ## Test the code with pytest
+	@echo "🚀 Testing code: Running pytest"
+	@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=xml
+
+
+# EXAMPLES
+.PHONY: examples 
+examples:  ## run all examples
+	@uv run examples/bvp/two_sphere_impact/two_sphere_impact.py
+
+
+.PHONY: verification 
+verification:  ## run all examples
+	@echo "📈 Plotting verification tests"
+	@echo "MCC TRX CD CU '"
+	@uv run verification/mcc/trx_cu_cd.py
+
+
+
+
+.PHONY: help
+help:
+	@uv run python -c "import re; \
+	[[print(f'\033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([a-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]"
+
+
+.DEFAULT_GOAL := help
+
+
+
+
+# .PHONY: build
+# build: clean-build ## Build wheel file
+# 	@echo "🚀 Creating wheel file"
+# 	@uvx --from build pyproject-build --installer uv
+
+# .PHONY: clean-build
+# clean-build: ## Clean build artifacts
+# 	@echo "🚀 Removing build artifacts"
+# 	@uv run python -c "import shutil; import os; shutil.rmtree('dist') if os.path.exists('dist') else None"
+
+# .PHONY: publish
+# publish: ## Publish a release to PyPI.
+# 	@echo "🚀 Publishing."
+# 	@uvx twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
+
+# .PHONY: build-and-publish
+# build-and-publish: build publish ## Build and publish.
+
+# .PHONY: docs-test
+# docs-test: ## Test if documentation can be built without warnings or errors
+# 	@uv run mkdocs build -s
+
+# .PHONY: docs
+# docs: ## Build and serve the documentation
+# 	@uv run mkdocs serve

README.md

@@ -1,27 +1,109 @@
+<br /><br />
 
-A Material Point Method solver developed with [JAX](https://jax.readthedocs.io/en/latest/quickstart.html)
+<div style="position: relative; height: 160px; margin-bottom: 20px;">
+  <p align="center" style="position: absolute; top: 0; left: 0; width: 100%;">
+    <img src="docs/_static/hydraxmpm.png" alt="HydraxMPM Logo" width="250" /* Set desired larger width */ >
+  </p>
+</div>
+<h1 align="center"><b>HydraxMPM</b></h1>
+<p align="center">
+  <b>A JAX-powered Material Point Method & Single Integration Point simulation environment for granular materials</b>
+</p>
+<p align="center" style="font-style: normal; letter-spacing: 1px; font-size: 0.9em; opacity: 0.9;">
+  Develop · Diagnose · Simulate
+</p>
+<p align="center">
+  📖 <a href="LINK_TO_YOUR_DOCUMENTATION_SITE"><strong>Documentation (coming Soon)</strong></a> | ⚙️ <a href="#installation">Installation</a> | 🤝 <a href="LINK_TO_CONTRIBUTING.MD">Contributing (coming Soon)</a>
+  <!-- Add badges here if you have them: e.g., build status, license -->
+</p>
 
-This code is still in pre-alpha, i.e., all models may not be feature-complete.
 
+HydraxMPM integrates the **Material Point Method (MPM)** solver for large-scale granular dynamics simulations and **Single Integration Point (SIP)** testing <!--for detailed constitutive **model creation and diagnosis**-->, within one environment. Built on JAX, it leverages automatic differentiation and hardware acceleration (CPU/GPU/TPU) for research and development of numerical models capturing solid-like and fluid-like behavior of granular materials.
 
-## Current features
-Basic shape functions (linear, cubic)
-Solvers (USL, APIC)
-Materials ( Drucker Prager, Linear isotropic Elastic, Modified Cam Clay, Newtonian Fluid, $\mu (I)$ rheology)
-Forces (Rigid body contact, gravity, slip and no slip boundaries)
 
-## Installation instructions
-- Install uv [here](https://docs.astral.sh/uv/getting-started/installation/)
-- Clone repository `git clone git@github.com:GrainLearning/HydraxMPM.git && cd HydraxMPM`
-- Install dependencies `uv sync`
-- Run an example, e.g., `uv run examples/dambreak/dambreak.py`. Output is found in the `./examples/dambreak/` directory.
+<p align="center"> 
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/_static/sip_animation_light.gif">
+    <source media="(prefers-color-scheme: light)" srcset="docs/_static/sip_animation_dark.gif">
+    <img alt="Animation demonstrating HydraxMPM simulation (light/dark mode versions)" src="docs/_static/sip_animation_dark.gif">
+  </picture>
+</p>
 
 
-## Contributors:
-Retief Lubbe, Hongyang Cheng
 
-University of Twente, SMM
 
-## Acknowledgements
+<table style="margin: 0px auto;" align="center" >
+  <tr>
+    <td align="center" valign="top"  padding="0 15px 0 0">
+      <source media="(prefers-color-scheme: dark)" srcset="docs/_static/mpm_models_ss_light.png">
+      <source media="(prefers-color-scheme: light)" srcset="docs/_static/mpm_models_ss_dark.png">
+      <img src="docs/_static/mpm_models_ss_dark.png" alt="MPM simulation SS (light mode)" height="300">
+    </td>
+    <td align="center" valign="top"  padding="0 15px 0 0">
+      <source media="(prefers-color-scheme: dark)" srcset="docs/_static/mpm_models_ke_light.png">
+      <source media="(prefers-color-scheme: light)" srcset="docs/_static/mpm_models_ke_dark.png">
+      <img src="docs/_static/mpm_models_ke_dark.png" alt="MPM simulation KE (light mode)" height="300">
+    </td>
+  </tr>
+</table>
+
+
+
+
+
+## Capabilities
+
+*   🔬 **Diagnose Constitutive Models:** Perform controlled SIP tests (triaxial, shear, and compression) for advanced constitutive model analysis.
+*   ⛰️ **Simulate Large-Scale Processes:** Model complex, large-deformation granular processes (e.g., landslides) using MPM.
+*   ⚖️ **Validate Across Scales:** Compare solid-l  ike and fluid-like model behavior at both element (SIP) and system (MPM) levels.
+*   ∇ **Gradient-Aware:** Utilize automatic differentiation for sensitivity analysis, inverse problems, and optimization.
+
+## Key Features
+
+*   **Unified MPM & SIP:** Shared API facilitates rapid prototyping and validation.
+*   **High Performance:** JAX backend with JIT compilation.
+*   **Differentiable:** Enables advanced gradient-based studies.
+*   **Modular:** Designed for extensibility in research settings.
+*   **Solvers & Schemes:** Explicit MPM (USL) with FLIP/PIC, APIC, AFLIP transfer; Linear, Quadratic, Cubic B-spline basis functions.
+*   **Available Models:** Drucker-Prager, Modified Cam-Clay, Newtonian Fluid, Incompressible $\mu (I)$ rheology.
+*   **SIP Tests:** Triaxial (Drained/Undrained), Constant Pressure/Volume Shear, Isotropic Compression.
+*   **Contact & Boundaries:** Rigid body contact (penalty-based), slip/no-slip conditions.
+*   **Time Stepping & Stability:** Fixed and adaptive time stepping with Courant–Friedrichs–Lewy (CFL) condition.
+
+
+## Installation
+
+1.  **Install uv:** Follow instructions [here](https://docs.astral.sh/uv/getting-started/installation/).
+2.  **Clone & Install Dependencies:**
+    ```bash
+    git clone https://github.com/GrainLearning/HydraxMPM.git && cd HydraxMPM
+    uv sync
+    ```
+3.  **Run Example:**
+    ```bash
+    uv run ./examples/dambreak/dambreak.py
+    ```
+    *(Output in `./examples/dambreak/output`)*
+
+
+
+## 👥 Contributors:
+
+* Retief Lubbe (Soil Micro Mechanics group / University of Twente)
+* Hongyang Cheng (Soil Micro Mechanics group / University of Twente)
+
+## 🙏 Acknowledgements
 This research is part of the project TUSAIL [Training in Upscaling Particle Systems: Advancing Industry across Length-scales](https://tusail.eu)  and has received funding from the European Horizon2020 Framework Programme for research, technological development and demonstration under grant agreement ID 955661.
 
+> [!WARNING]
+> This is a research software under active development (pre-alpha). APIs and functionality are subject to change without notice.
+
+
+
+<!--
+## 🧠 Key Benefits
+
+* **Unify local and global views:** Test, compare and validate constitutive models at a SIP-level, and directly apply them to large-scale MPM simulations – all within the same framework.
+* **Cutting-Edge performance** Built on JAX, leveraging Just-In-Time (JIT) for high-performance array-based operations on the CPU, GPU, and TPU.
+* **Solve inverse problems with ease:** All internals are automatically differentiable, enabling model diagnosis and gradient-based optimization (e.g., reducing the need to solve the tangential stiffness tensor).
+* **Modular & Extendable:** The modular structure, coupled with batched and parallelized continuum mechanics operations, will enable modification and extension of existing components, while also enabling rapid prototyping. -->