Disclaimer: This code is under development and is likely to have significant breaking changes in the near future. Many features are incomplete or redundant. Please contact the development team if you would like a tour.
A Python package for simulating the motion of granular materials as a result of the motion of voids. HGD models non-inertial problems and segregation particularly well for several systems.
New to HGD? Follow our comprehensive Getting Started Guide for step-by-step installation and your first simulation.
Already installed? Try running an example:
python HGD/main.py json/hopper.json5Before installing HGD, ensure you have:
- Python 3.9 or newer (Python 3.11+ recommended)
- C++ compiler (g++, Clang, or MSVC)
- CMake 3.15+
- OpenMP (for parallel execution)
📦 Quick install commands for dependencies
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install python3 python3-pip g++ cmake libomp-devmacOS:
brew install python cmake libompWindows:
- Install Python from python.org
- Install Visual Studio with C++ support
- Install CMake from cmake.org
-
Clone or download this repository:
git clone https://github.com/benjym/HGD.git cd HGD -
Install HGD and dependencies:
pip install -e .This command installs all required Python packages and compiles the C++ extension modules.
-
Verify installation:
python -c "import HGD; print('HGD installed successfully!')" -
(Optional) Set up pre-commit hooks for development:
pre-commit install
Run a simulation using a JSON5 configuration file:
python HGD/main.py json/<config_file>.json5Example:
python HGD/main.py json/hopper.json5The simulation parameters are stored in the JSON5 file. Default parameters are available in json/defaults.json5.
- Getting Started Guide - Complete installation and first simulation walkthrough
- Examples Guide - Detailed description of all example scenarios
- Troubleshooting - Solutions to common problems
- API Documentation - Comprehensive code reference
- Default Parameters - All configurable parameters with defaults
HGD includes several example configurations. Start with the quickest one:
# Quick validation (10 seconds)
python HGD/main.py json/minimal_test.json5
# Simple examples
python HGD/main.py json/collapse.json5 # ~1 minute
python HGD/main.py json/hopper.json5 # ~2 minutes| Example | Description | Runtime |
|---|---|---|
minimal_test.json5 |
Installation verification | ~10 sec |
hopper.json5 |
Material flowing through a hopper | ~2 min |
collapse.json5 |
Column collapse under gravity | ~1 min |
footing.json5 |
Load bearing capacity test | ~3 min |
temperature.json5 |
Thermal effects in flow | ~5 min |
See the Examples Guide for complete descriptions and usage instructions.
After running a simulation, results are saved in the output/ directory:
output/
└── <simulation_name>/
├── <parameter_set>/
│ ├── nu_*.png # Density snapshots
│ ├── s_*.png # Particle size snapshots
│ ├── nu.mp4 # Density video
│ └── s.mp4 # Particle size video
└── ...
Simulations are configured using JSON5 files. Key parameters include:
{
// Grid resolution
nx: 50, // Horizontal cells
ny: 50, // Vertical cells
nm: 20, // Internal states
// Physical properties
H: 1.0, // System height (m)
repose_angle: 30, // Friction angle (degrees)
s_m: 0.001, // Min particle size (m)
gsd_mode: 'bi', // Grain size distribution
// Simulation
t_f: 5.0, // Final time (s)
save_inc: 1, // Save frequency
plot: ['nu', 's'], // Variables to plot
}See json/defaults.json5 for all available parameters.
Installation fails? Check the Troubleshooting Guide for solutions to common issues:
- C++ compiler not found
- CMake errors
- OpenMP missing
- Memory errors
- And more...
Need help? See the Support section below.
You can read the docs here.
You can contact the development team here.