QuadMath: Analytical Review of Quadray Coordinates (4D)

This repository organizes a comprehensive review of Quadray coordinates, integer volume quantization, optimization on tetrahedral lattices, and information geometry. It contains modular Markdown sources, LaTeX outputs, and build scripts to produce individual and combined PDFs.

Repository: https://github.com/docxology/QuadMath

DOI: 10.5281/zenodo.16887791

License: Apache-2.0

Quick Start

# Clone and setup
git clone https://github.com/docxology/QuadMath.git
cd QuadMath
uv sync

# Run tests to ensure everything works
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 coverage run -m pytest -q

# Generate all outputs (figures, PDFs, LaTeX)
bash quadmath/scripts/render_pdf.sh

# Clean all generated outputs (regeneratable)
bash quadmath/scripts/clean_output.sh

Repository Architecture: The render_pdf.sh Paradigm

This repository follows a unified test-driven development workflow where source code, tests, and documentation are developed together in complete coherence:

Core Workflow

1. Source Code (src/): Implements mathematical functionality with 100% test coverage
2. Tests (tests/): Validates all functionality using real numerical examples
3. Scripts (quadmath/scripts/): Generate figures and data from src/ modules
4. Documentation (quadmath/markdown/): Documents mathematical concepts and references code
5. render_pdf.sh: Orchestrates the entire pipeline ensuring coherence

How render_pdf.sh Works

The render_pdf.sh script orchestrates a complete pipeline that ensures all components work together:

• Runs all generation scripts (validates src/ code works)
• Validates markdown integrity (images, references, equations)
• Generates auto-updated glossary from src/ API
• Builds individual and combined PDFs from validated markdown
• Exports LaTeX for further processing

This ensures that the mathematical concepts in the markdown, the implemented code in src/, and the generated figures are all coherent and synchronized.

Project Structure

• src/: Source code modules (100% test coverage required)
• tests/: Test suite (no mocks, real numerical examples)
• quadmath/markdown/
  • 01_introduction.md: Introduction to 4D namespaces and quadrays
  • 02_4d_namespaces.md: Coxeter.4D, Einstein.4D, Fuller.4D distinctions
  • 03_quadray_methods.md: Quadray analytical details and methods
  • 04_optimization_in_4d.md: Optimization on tetrahedral lattices
  • 05_extensions.md: Extensions and applications
  • 06_discussion.md: Discussion and implications
  • 07_resources.md: References and resources
  • 08_equations_appendix.md: Mathematical equations supplement
  • 09_free_energy_active_inference.md: Free energy and active inference
  • 10_symbols_glossary.md: Auto-generated API glossary from source code
• quadmath/scripts/: Figure and data generation scripts that import from src/
• quadmath/latex/: LaTeX preamble and utilities
• quadmath/output/: All generated artifacts (figures, data, PDFs, LaTeX)
• quadmath/resources/: Images, diagrams, and supplementary assets

Test Suite and Code Connections

The test suite (tests/) ensures 100% coverage of all src/ modules, validating that:

• All mathematical functions work correctly
• Figure generation scripts can import and use source modules
• Generated outputs are deterministic and reproducible
• Markdown documentation accurately reflects implemented functionality

Figure and Manuscript Generation

Figures are generated by scripts in quadmath/scripts/ that:

• Import directly from src/ modules (no code duplication)
• Generate PNG/MP4/SVG files to quadmath/output/figures/
• Save raw data (CSV/NPZ) to quadmath/output/data/
• Print output paths for manifest collection

The markdown files reference these generated figures, and render_pdf.sh ensures all references are valid before building PDFs.

Build (PDF)

Dependencies: pandoc, xelatex (TeX Live).

• Ubuntu/Debian:
  • sudo apt-get update
  • sudo apt-get install -y pandoc texlive-xetex texlive-fonts-recommended fonts-dejavu
• macOS:
  • brew install pandoc
  • brew install --cask mactex-no-gui

Build Commands

# Generate all outputs (figures, PDFs, LaTeX)
bash quadmath/scripts/render_pdf.sh

# Clean all generated outputs (regeneratable)
bash quadmath/scripts/clean_output.sh

Output Structure

After running render_pdf.sh, you'll find:

quadmath/output/
├── figures/          # PNG/MP4/SVG files
├── data/             # CSV/NPZ files and manifests
├── pdf/              # Individual and combined PDFs
│   ├── 01_introduction.pdf
│   ├── 02_4d_namespaces.pdf
│   ├── ...
│   └── quadmath_review.pdf (combined)
└── tex/              # Exported LaTeX files

Development Workflow

1. Always run tests first: PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 coverage run -m pytest -q
2. Ensure 100% coverage for src/ (enforced via .coveragerc)
3. Run render_pdf.sh after significant changes to validate coherence
4. Source code changes must be reflected in tests AND documentation
5. Documentation changes must generate working PDFs

For detailed workflow information, see WORKFLOW.md. For development rules and enforcement, see .cursorrules.

Contributing

This project follows a strict test-driven development workflow. Before contributing:

1. Fork the repository from https://github.com/docxology/QuadMath
2. Create a feature branch for your changes
3. Write tests first following TDD principles
4. Ensure 100% test coverage is maintained
5. Run the complete pipeline with bash quadmath/scripts/render_pdf.sh
6. Submit a pull request with clear description of changes

Citation

If you use this work in your research, please cite:

@software{quadmath2025,
  title={QuadMath: Analytical Review of Quadray Coordinates (4D)},
  author={docxology},
  year={2025},
  url={https://github.com/docxology/QuadMath},
  doi={10.5281/zenodo.16887791},
  license={Apache-2.0}
}