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

[Copilot]

Build failures occurred due to Python version mismatches: Black configured for 3.11 while project supports 3.9+, and a pre-compiled C++ extension for Python 3.12 committed to the repository.

Changes

Python version alignment

• pyproject.toml: Black target-version changed from py311 to py39
• .pre-commit-config.yaml: language_version changed from python3.11 to python3.9

C++ extension compilation

• Removed: HGD/motion/d2q4_cpp.cpython-312-x86_64-linux-gnu.so
• .gitignore: Added *.so and *.pyd to exclude version-specific compiled extensions
• Extensions now build on user's system during pip install -e . with correct Python version

Documentation improvements

• docs/getting-started.md: Installation walkthrough with prerequisites
• docs/examples.md: All 19 examples documented with runtimes and difficulty
• docs/troubleshooting.md: Common installation and runtime issues
• README.md: Quick start with links to documentation site
• mkdocs.yml: Navigation updated to include new guides

Example configurations

• json/minimal_test.json5: 10-second validation test
• json/quick_test.json5: 30-second test with video generation
• json/collapse.json5: Fixed missing defined_time_step_size parameter for inertia mode

Technical notes

• C extensions are Python version-specific (cpython-312 ≠ cpython-39)
• scikit-build-core handles automatic compilation during installation
• Requires C++ compiler, CMake 3.15+, and OpenMP (documented in prerequisites)

Original prompt

pretend you're a new user. try to install and use this code to solve a granular mechanics problem. use only the instructions provided. make a detailed plan to improve onboarding of new users

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[benjym]

@copilot The validate_instructions script is too much. Can you also move all the MD files into the docs and integrate there?

[Copilot]

@copilot The validate_instructions script is too much. Can you also move all the MD files into the docs and integrate there?

Done! I've removed validate_installation.py and moved all MD files into the docs/ directory:

• GETTING_STARTED.md → docs/getting-started.md
• EXAMPLES.md → docs/examples.md
• TROUBLESHOOTING.md → docs/troubleshooting.md
• ONBOARDING_TEST.md → docs/onboarding-test.md

Updated mkdocs.yml to include all the new docs in the navigation, and updated the README to link to the documentation site (https://benjym.github.io/HGD/) instead of local files.

Installation verification is now simplified to a basic Python import test instead of the validation script.

Commit: ab9045a

[benjym]

its failing a build test (something about python version mismatch). can you fix?

[benjym]

@copilot

its failing a build test (something about python version mismatch). can you fix?

[Copilot]

@copilot

its failing a build test (something about python version mismatch). can you fix?

Fixed! The build failure was caused by a Python version mismatch:

• pyproject.toml had target-version = ['py311'] for Black, but specified requires-python = ">=3.9"
• .pre-commit-config.yaml was set to python3.11

I've updated both to use Python 3.9 to be consistent with the project's minimum Python requirement. This should resolve the build test failure.

Changes:

• pyproject.toml: Changed Black target-version from py311 to py39
• .pre-commit-config.yaml: Changed language_version from python3.11 to python3.9

Commit: e147664

[Copilot]

Pull request overview

This PR addresses build and onboarding issues by aligning declared Python support (3.9+) with tooling configs, preventing committed Python-version-specific native extensions, and expanding the user-facing documentation and example configs.

Changes:

• Align formatter/tooling Python versions to 3.9+ (Black + pre-commit).
• Add/adjust example JSON5 configs and fix collapse.json5 inertia requirements.
• Add mkdocs pages and expand README/docs to improve installation/onboarding guidance.

Reviewed changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
requirements.txt	Adds a dependency list for users who prefer pip install -r.
pyproject.toml	Sets Black target version to py39 to match supported Python.
.pre-commit-config.yaml	Pins pre-commit hook runtime to Python 3.9.
.gitignore	Ignores compiled extension artifacts (*.so, *.pyd).
mkdocs.yml	Updates navigation to include new guides.
json/minimal_test.json5	Adds a fast “no video” validation config.
json/quick_test.json5	Adds a fast validation config with video output enabled.
json/collapse.json5	Adds defined_time_step_size needed for inertia mode.
docs/getting-started.md	Adds a detailed install + first-run guide.
docs/examples.md	Documents included example configs and how to run them.
docs/troubleshooting.md	Adds common install/runtime troubleshooting guidance.
docs/onboarding-test.md	Adds a “simulated new user” onboarding checklist.
README.md	Reworks README for quick start + links to docs site.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

docs/onboarding-test.md instructs users to run python validate_installation.py, but there is no validate_installation.py in the repository root. Either add that script or update this step to use an existing verification method (e.g., the import check or running python HGD/main.py json/minimal_test.json5).

[Copilot]

This onboarding document refers to GETTING_STARTED.md / EXAMPLES.md / TROUBLESHOOTING.md, but the actual docs pages in this repo are docs/getting-started.md, docs/examples.md, and docs/troubleshooting.md (and mkdocs.yml uses those). Update the references so readers can find the right files.

Suggested change

	## Phase 2: Installation (GETTING_STARTED.md)
	### Step 2.1: Install System Dependencies
	```bash
	# Ubuntu/Debian (documented in README and GETTING_STARTED)
	## Phase 2: Installation (docs/getting-started.md)
	### Step 2.1: Install System Dependencies
	```bash
	# Ubuntu/Debian (documented in README and docs/getting-started.md)

[Copilot]

This troubleshooting entry references No module named 'skbuild', but the project is configured to build with scikit-build-core (pyproject.toml uses scikit_build_core.build) and there are no skbuild imports in the codebase. Consider updating the error/module name and guidance to match the current build backend.

[Copilot]

The proposed fix installs scikit-build-core, but that package does not provide a skbuild module. Either change the recommendation to scikit-build (if the error is truly about skbuild) or change the documented error to the module that would be missing with the current build backend (e.g., scikit_build_core).

Suggested change

	pip install scikit-build-core pybind11
	pip install scikit-build pybind11

[Copilot]

The docs claim only C++11 support is required, but the CMake configuration requests cxx_std_14 (C++14). Update the prerequisite to C++14 so users don't hit confusing compiler/CMake errors.

Suggested change

	- **C++ Compiler** with C++11 support:
	- **C++ Compiler** with C++14 support:

[Copilot]

json/defaults.json5 is linked as a relative path from the mkdocs page, but the json/ directory is outside docs/ and won’t be published by mkdocs by default. This link will likely 404 on the documentation site; consider linking to the GitHub file URL or copying/exposing the defaults file under docs/.

Suggested change

	- Check [defaults.json5](json/defaults.json5) for all available parameters
	- Check `defaults.json5` in the `json/` directory for all available parameters

[Copilot]

This list claims validate_installation.py was added, but the file is not present in the repository. Either add the script or remove/replace this bullet so the onboarding doc stays accurate.

Suggested change

- ✅ validate_installation.py (automated verification)