Sync bundled Macdonald materials with upstream (GAlgebraPrimer Sep 2023)

[utensil]

The bundled copy of Alan Macdonald's materials under doc/books/Macdonald/ and the README reference are out of date.

GAlgebraPrimer.pdf — the archived copy is the November 29, 2022 version. The current version on Prof. Macdonald's site is dated September 15, 2023. We should archive the updated PDF in doc/books/Macdonald/ and update the README note (currently says "last updated on November 29, 2022, accessed May, 2024") to reflect the new version and access date.

GAfiles.zip audit — PRs #505 and #510 merged content from an earlier snapshot of http://www.faculty.luther.edu/~macdonal/GAfiles.zip into GAlgebra. The September 2023 update may include further changes to gprinter.py, lt.py, mv.py, or GAlgebraInit.py that were not captured in those PRs. We should download the current zip, diff it against what was merged, and determine if anything is worth incorporating or documenting as a known divergence.

[utensil]

Also, doc/books/Macdonald/README.md references the primer as "Last update: 1/24/18" which is even older and uses an ambiguous date format (month/day/year). That file should be updated to match the actual bundled version with an unambiguous date format (e.g. January 24, 2018), and then updated again as part of this issue once the September 2023 version is archived.

[utiberious]

Initial investigation

GAlgebraPrimer.pdf

• Bundled: creation date 2022-11-29 (confirmed via PDF metadata). README currently says Last update: 1/24/18 — stale and ambiguous (January 24, 2018).
• Upstream: http://www.faculty.luther.edu/~macdonal/GAlgebraPrimer.pdf is accessible and has creation date 2023-09-15 (490 KB). The URL changed slightly — the /laga/ subdirectory path 404s, but the root path works.

GAfiles.zip audit

Downloaded http://www.faculty.luther.edu/~macdonal/GAfiles.zip (44 KB). Key files inside and their zip timestamps:

• GAlgebraInit.py — 2023-01-21
• lt.py — 2023-01-21
• mv.py — 2023-01-21
• gprinter.py — 2021-11-02

The zip was not updated alongside the September 2023 primer — that was a PDF-only revision. The Python files are January 2023.

Lines present in zip but not in current galgebra source (potential missed changes):

zip file	galgebra equivalent	lines in zip ∉ galgebra
lt.py	galgebra/lt.py	107
mv.py	galgebra/mv.py	144
gprinter.py	galgebra/gprinter.py	77
GAlgebraInit.py	galgebra/__init__.py	63

Most of the bulk is whitespace/style and lines that galgebra refactored into other modules. A targeted function-level review is needed to find genuine behavioural gaps.

---

Proposed plan

PR 1 — PDF update (small, self-contained):

• Replace doc/books/Macdonald/GAlgebraPrimer.pdf with the September 2023 version
• Fix README: Last update: 1/24/18 → Last updated September 15, 2023 with access date

PR 2 — Code audit (token-efficient approach):

• Rather than full line-by-line diffs, compare function-by-function: for each function in the zip that isn't obviously in galgebra, determine its intent and check for a galgebra equivalent (possibly renamed/refactored)
• Document any genuine gaps as either worth merging or deliberate divergences
• Goal: a short audit note in the PR description, not a full diff dump

[utiberious]

Code audit findings (GAfiles.zip Jan 2023 vs galgebra current)

lt.py

is_vector() zero-vector guard (gap):

• Zip: if not out.is_vector(): raise ValueError — rejects zero output
• Galgebra: if not out.is_vector() and not out.is_zero(): raise ValueError — allows zero output
• The galgebra change was introduced in Sync updates from upstream, particularly GSG's work #510 to permit degenerate/projection maps. The zip's stricter check is arguably more correct for well-defined linear transforms.

Mlt.__init__ component-expression branch (deliberate NotImplementedError):

• Zip implements constructing an Mlt from a component expression (not a callable). Galgebra raises NotImplementedError with a comment noting args isn't defined at that point. This is a missing feature, not a regression — the component-expression path was never fully ported.

mv.py — Fully covered

All functions (qform, norm2, mag2, mag, is_versor) are present as both methods and module-level functions. Only whitespace diffs.

gprinter.py — Galgebra is ahead

Galgebra's gprinter.py has more than the zip: gxpdf() gained 4 extra params (evince, rm, null, documentclass), encoding modernised to UTF-8. No gaps.

GAlgebraInit.py — Not comparable

The zip file is a Jupyter notebook init script (executes gFormat, sets Ga.dual_mode, etc.). Galgebra's __init__.py is a standard Python module. Different purposes; nothing to merge.

---

Follow-up work:

• PR to restore stricter is_vector() zero-vector check in Lt.__init__
• Issue + PR for the Mlt component-expression constructor (NotImplementedError branch)