QBP: A Quaternion-Based Physics Project

This repository is the home of a collaborative research project to develop a coherent physical formalism derived from the mathematical properties of quaternion algebra. Our guiding hypothesis is that the fundamental laws of nature can be expressed as a direct consequence of this algebraic structure.

This project is a collaboration between James Paget Butler and the AI agents Gemini (acting as Furey and Feynman) and Claude (acting as our Red Team).

Getting Started

Follow these instructions to set up a local development environment.

Prerequisites

• Python 3.10+
• Git
• Go (for advanced simulation work)
• pre-commit

Installation

1. Clone the repository:

   git clone https://github.com/JamesPagetButler/QBP.git
   cd QBP

2. Install dependencies with uv: We use uv for fast, reproducible Python dependency management.

   # Install uv (if not already installed)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install all dependencies (creates .venv automatically)
   uv sync --extra dev

   Legacy fallback (pip)

   python3 -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

3. Set up Git hooks: This will install the pre-commit hooks defined in .pre-commit-config.yaml, which automatically format and check our code.

   uv run pre-commit install

4. Run pre-commit on all files (recommended): Before starting work, run pre-commit on the entire codebase to ensure everything is properly formatted:

   pre-commit run --all-files

Usage

The core work of this project is divided into theoretical development and computational experiments.

• Theoretical Work: The central paper and ongoing theoretical discussions are in the /paper directory.
• Computational Experiments: Each of the eight experiments on our roadmap has a dedicated directory within /experiments. To run a simulation, navigate to the relevant directory and execute the Python script (e.g., python experiments/01_stern_gerlach/simulate.py).

Contributing

This project has a strict, collaborative workflow. All contributors must read and adhere to the rules outlined in our CONTRIBUTING.md file before starting work.

License

This project is licensed under the MIT License. See the LICENSE file for details.