Fix Python version compatibility for C++ extensions and build tooling

.gitignore

@@ -10,3 +10,6 @@ build/
 venv/
 venv_dry/
 *.mp4
+# Compiled Python extensions (version-specific)
+*.so
+*.pyd

.pre-commit-config.yaml

@@ -12,4 +12,4 @@ repos:
         # supported by your project here, or alternatively use
         # pre-commit's default_language_version, see
         # https://pre-commit.com/#top_level-default_language_version
-        language_version: python3.11
+        language_version: python3.9

README.md

@@ -1,18 +1,172 @@
-# Heterarchical Granular Dynamics
+# Heterarchical Granular Dynamics (HGD)
 
 **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 a granular material as a result of the motion of voids. In particular, it (currently) models non-inertial problems quite well. In particular, segregation is well modelled for several systems.
+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.
 
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-# Installation
+## 🚀 Quick Start
 
-1. Download and unzip (or clone) this repository
-2. Install python 3.11 or newer. `c++` version of the code also requires `openmp` on the system.
-3. Install the required python packages with `pip install -e .`. This also builds the `c++` extension module.
-4. Set up your pre-commit hooks (so that when you make changes things are kept nice and clean) by running `pre-commit install`
-5. Run the code with `python HGD/main.py json/collapse.json5`. The parameters for this specific case are stored in `json/collapse.json5`. Change that file name to a different `json5` file to use those values instead. Default parameters are stored in `json/defaults.json5`.
+**New to HGD?** Follow our comprehensive [Getting Started Guide](https://benjym.github.io/HGD/getting-started) for step-by-step installation and your first simulation.
+
+**Already installed?** Try running an example:
+```bash
+python HGD/main.py json/hopper.json5
+```
+
+## 📋 Prerequisites
+
+Before 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)
+
+<details>
+<summary>📦 <b>Quick install commands for dependencies</b></summary>
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get update
+sudo apt-get install python3 python3-pip g++ cmake libomp-dev
+```
+
+**macOS:**
+```bash
+brew install python cmake libomp
+```
+
+**Windows:**
+- Install Python from [python.org](https://www.python.org/downloads/)
+- Install Visual Studio with C++ support
+- Install CMake from [cmake.org](https://cmake.org/download/)
+
+</details>
+
+## 🔧 Installation
+
+1. **Clone or download this repository:**
+   ```bash
+   git clone https://github.com/benjym/HGD.git
+   cd HGD
+   ```
+
+2. **Install HGD and dependencies:**
+   ```bash
+   pip install -e .
+   ```
+
+   This command installs all required Python packages and compiles the C++ extension modules.
+
+3. **Verify installation:**
+   ```bash
+   python -c "import HGD; print('HGD installed successfully!')"
+   ```
+
+4. **(Optional) Set up pre-commit hooks for development:**
+   ```bash
+   pre-commit install
+   ```
+
+## 🎯 Running Simulations
+
+Run a simulation using a JSON5 configuration file:
+
+```bash
+python HGD/main.py json/<config_file>.json5
+```
+
+**Example:**
+```bash
+python HGD/main.py json/hopper.json5
+```
+
+The simulation parameters are stored in the JSON5 file. Default parameters are available in `json/defaults.json5`.
+
+## 📚 Documentation & Resources
+
+- **[Getting Started Guide](https://benjym.github.io/HGD/getting-started)** - Complete installation and first simulation walkthrough
+- **[Examples Guide](https://benjym.github.io/HGD/examples)** - Detailed description of all example scenarios
+- **[Troubleshooting](https://benjym.github.io/HGD/troubleshooting)** - Solutions to common problems
+- **[API Documentation](https://benjym.github.io/HGD/)** - Comprehensive code reference
+- **[Default Parameters](json/defaults.json5)** - All configurable parameters with defaults
+
+## 💡 Example Simulations
+
+HGD includes several example configurations. Start with the quickest one:
+
+```bash
+# 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](https://benjym.github.io/HGD/examples) for complete descriptions and usage instructions.
+
+## 🔍 Viewing Results
+
+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
+    └── ...
+```
+
+## 🛠️ Configuration
+
+Simulations are configured using JSON5 files. Key parameters include:
+
+```json5
+{
+    // 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.
+
+## ❓ Troubleshooting
+
+**Installation fails?** Check the [Troubleshooting Guide](https://benjym.github.io/HGD/troubleshooting) for solutions to common issues:
+- C++ compiler not found
+- CMake errors
+- OpenMP missing
+- Memory errors
+- And more...
+
+**Need help?** See the [Support](#-support) section below.
 
 # Documentation