fix(ga): change default dual mode to Iinv+ for correct B*dual(B)=I

[utiberious]

Summary

Changes the default dual_mode from 'I+' to 'Iinv+' so that B * B.dual() == I holds, which is the conventional definition of the dual in geometric algebra.

With 'I+', dual(B) = B * I, which does not satisfy this identity in general. The correct definition is dual(B) = B * I_inv.

Fixes #514

Changes

• galgebra/ga.py: Change dual_mode_value default from 'I+' to 'Iinv+'
• test/test_test.py: Update existing dual mode test, add test_dual_correctness verifying B * B.dual() == I
• examples/ipython/Smith Sphere.ipynb: Update notebook outputs to match corrected dual

Test plan

• Unit tests pass
• Full CI with nbval notebooks passes (Smith Sphere notebook outputs updated)

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[utensil]

Thanks for digging into this. The convention ('Iinv+') is correct and consistent with kingdon's polarity dual.

A few things to address before this could be considered for merge:

1. The test comment "For any blade B, B * B.dual() should equal I" is wrong. It holds for unit bivectors in 3D Euclidean (where B²=-1) but fails for vectors (where B²=1, so B * dual(B) = -I). The test itself is fine, just the comment needs fixing.

2. The Smith Sphere notebook formula needs to be updated, not just the outputs. The down() and up() functions compute n = -1 * N.dual() to get the normal vector to a plane. With 'I+' that minus sign was needed to get the correct outward normal. With 'Iinv+' it flips the projection pole from north to south, which is why cells 9 and 14 show denominator changes from |z+1|² to |z-1|² — geometrically wrong results. The fix is n = N.dual() (remove the minus).

That said, this is a global default change and a breaking change for any user calling .dual() without setting a mode explicitly. Given that the existing mode system already lets users opt into 'Iinv+', we'd rather not change the default in 0.6.0. This PR is useful as a reference for how the convention change affects tests and user code, and could be revisited for a later release with a deprecation notice.

[utiberious]

Good catches, addressed in 2025e17:

1. Fixed the test comment: now says "For a unit bivector B with B*B = -1" instead of claiming it holds for all blades.

2. Fixed the Smith Sphere notebook formula: removed the negation in down() and up() (n = N.dual() instead of n = -N.dual()). With Iinv+ the dual already gives the correct outward normal, so the minus was double-negating. The denominators now correctly show |z+1|^2 (north pole projection).

3. Accepted: agree that changing the global default is too disruptive for 0.6.0. This PR serves as a reference for how the convention change would affect tests and user code. Users can already opt into Iinv+ explicitly via Ga.dual_mode('Iinv+').

[utensil]

Thanks, CI is green.

I'll leave this PR open for demonstrating the change of default dual mode. Also I'm considering to default to this new dual mode for Kingdon compatible interface in #524 .

[utensil]

Thanks for fixing this — the math is correct. 'Iinv+' (dual(A) = A·I⁻¹) is the standard Hodge dual per Doran & Lasenby, and issue #514 confirms the bug: with the old 'I+' default, B * B.dual() gives -I instead of I for a unit bivector.

That said, this is a breaking change in default behavior for any code that calls dual() without explicitly setting Ga.dual_mode(), so a few things are needed before this can merge:

1. Docs need updating

doc/module-components.rst still describes the old default in two places:

• Line 342: method signature shows GA.dual_mode(mode='I+')
• Line 359: prose says "default for the dual mode is mode='I+'"

Both should be updated to 'Iinv+'.

2. Changelog entry missing

Please add an entry to doc/changelog.rst (following the existing :bug: format) noting the breaking change and migration path, e.g.:

:bug:`514` The default dual mode has changed from `'I+'` to `'Iinv+'` so that
`B * B.dual() == I` holds for unit blades, matching the standard definition
(Doran & Lasenby). To preserve the old behavior, call `Ga.dual_mode('I+')`
at the start of your program.

3. Minor cleanup (optional)

galgebra/primer.py:34 has an explicit Ga.dual_mode('Iinv+') call that was a workaround for this exact bug. With the default fixed it becomes a no-op — worth removing or updating the comment to reflect that it's now just confirming the default.

---

Note: primer.py already used 'Iinv+' explicitly, which shows this is the right direction. Happy to revisit once the docs and changelog are in place.

[utensil]

All three requested items are now addressed:

• ✅ doc/module-components.rst — both the method signature (line 342) and the prose (line 359) updated to 'Iinv+'; prose now correctly says A*I^{-1} is returned
• ✅ doc/changelog.rst — entry added with the :bug:514`` format and migration note
• ✅ galgebra/primer.py — explicit Ga.dual_mode('Iinv+') call kept, comment updated to "Confirms the default" rather than "workaround" framing

The PR is technically complete. Holding off on merge for now — this is a breaking change in default behavior and needs deliberate inclusion into a release rather than a quiet merge. Tracking here for when the time is right.