Add module gprinter, methods undual, g_invol, ccon, sp, `no…

…rm2`, `norm` for Mv, with validated tests (#510) Addresses #505 . Co-authored-by: Greg Grunberg <[email protected]> Co-authored-by: Alan Bromborsky <[email protected]>
pygae · May 15, 2024 · 644a32a · 644a32a
1 parent d4d09bd
commit 644a32a
Show file tree

Hide file tree

Showing 54 changed files with 10,486 additions and 339 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -41,6 +41,27 @@ jobs:
     - name: Lint
       run: |
         flake8 -v
+    - uses: hidakatsuya/[email protected]
+      if: "matrix.python-version == '3.11'"
+      with:
+        diff-pdf-version: '0.5'
+    - uses: actions/cache@v3
+      name: Tectonic Cache
+      if: "matrix.python-version == '3.11'"
+      with:
+        path: ~/.cache/Tectonic
+        key: ${{ runner.os }}-tectonic-${{ hashFiles('**/*.tex') }}
+        restore-keys: |
+          ${{ runner.os }}-tectonic-
+    - uses: wtfjoke/setup-tectonic@v2
+      if: "matrix.python-version == '3.11'"
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        biber-version: "latest"
+    - name: Set environment variables
+      if: "matrix.python-version == '3.11'"
+      run: |
+        echo "TEST_GXPDF=1" >> "$GITHUB_ENV"
     - name: Test
       run: |
         PYTEST_ARGS=();
@@ -49,8 +70,10 @@ jobs:
           PYTEST_ARGS+=(-k "$PYTEST_K_FILTER");
         fi;
         pytest \
+          -vv --durations=50 \
           --cov=galgebra \
           --nbval examples/ipython/ \
+          --nbval examples/primer/ \
           test \
           --nbval-current-env \
           --nbval-sanitize-with test/.nbval_sanitize.cfg \
@@ -60,6 +83,11 @@ jobs:
       uses: codecov/codecov-action@v3
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
+    - uses: actions/upload-artifact@v3
+      if: "matrix.python-version == '3.11' && failure()"
+      with:
+        name: PDF-diffs
+        path: test/diff
 
   release:
     name: Create release and send to PyPI

diff --git a/.gitignore b/.gitignore
@@ -139,3 +139,7 @@ examples/**/*.tex
 
 # Mac
 .DS_Store
+
+test/generated
+test/diff
+examples/GSG/
diff --git a/README.md b/README.md
@@ -25,6 +25,11 @@ Development Status
 
 The fork supports Python 3, increases test coverage, sets up CI and linters, maintains releases to [PyPI](https://pypi.org/project/galgebra/#history), improves [docs](http://galgebra.readthedocs.io) and has many bug fixes, see [Changelog](https://galgebra.readthedocs.io/en/latest/changelog.html).
 
+> [!NOTE]
+> Readers of Prof. Alan Macdonald's [Linear and Geometric Algebra](http://www.faculty.luther.edu/~macdonal/laga/index.html) and [Vector and Geometric Calculus](http://www.faculty.luther.edu/~macdonal/vagc/index.html), please check out [**Migrating guide for readers of LAGA&VAGC**](#migrating-guide-for-readers-of-lagavagc) below.
+> 
+> If you are coming from [sympy.galgebra](https://docs.sympy.org/0.7.6.1/modules/galgebra/) or [brombo/galgebra](https://github.com/brombo/galgebra), please check out section [Migration Guide](#migration-guide) below.
+
 Features
 --------------------
 
@@ -54,8 +59,8 @@ Overloaded Python operators for basic GA operations:
   AB &=  \texttt{A*B} \\
   A \wedge B &=  \mathtt{A \verb!^! B} \\
   A \cdot B &=  \texttt{A|B} \\
-  A \rfloor B &=  \texttt{A<B} \\
-  A \lfloor B &=  \texttt{A>B} \\
+  A \rfloor B &=  \mathtt{A \lt B} \\
+  A \lfloor B &=  \mathtt{A \gt B} \\
   A/B &=  \texttt{A/B} \\
 \end{aligned}\end{split}
 ```
@@ -77,10 +82,10 @@ The various derivatives of a multivector function is accomplished by multiplying
   F {\wedge}\bar{\nabla} &=  \mathtt{F \verb!^! rgrad} \\
   \nabla \cdot F &=  \texttt{grad|F} \\
   F \cdot \bar{\nabla} &=  \texttt{F|rgrad} \\
-  \nabla \rfloor F &=  \texttt{grad<F} \\
-  F \rfloor \bar{\nabla} &=  \texttt{F<rgrad} \\
-  \nabla \lfloor F &=  \texttt{grad>F} \\
-  F \lfloor \bar{\nabla} &= \texttt{F>rgrad}
+  \nabla \rfloor F &=  \mathtt{grad \lt F} \\
+  F \rfloor \bar{\nabla} &=  \mathtt{F \lt rgrad} \\
+  \nabla \lfloor F &=  \mathtt{grad \gt F} \\
+  F \lfloor \bar{\nabla} &= \mathtt{F \gt rgrad}
 \end{aligned}
 ```
 
@@ -92,10 +97,10 @@ The various derivatives of a multivector function is accomplished by multiplying
   \bar{\nabla} {\wedge}F &=  \mathtt{rgrad \verb!^! F} \\
   F \cdot \nabla &=  \texttt{F|grad} \\
   \bar{\nabla}\cdot F &=  \texttt{rgrad|F} \\
-  F \rfloor \nabla &=  \texttt{F<grad} \\
-  \bar{\nabla} \rfloor F &=  \texttt{rgrad<F} \\
-  F \lfloor \nabla &=  \texttt{F>grad} \\
-  \bar{\nabla} \lfloor F &= \texttt{rgrad>F}
+  F \rfloor \nabla &=  \mathtt{F \lt grad} \\
+  \bar{\nabla} \rfloor F &=  \mathtt{rgrad \lt F} \\
+  F \lfloor \nabla &=  \mathtt{F \gt grad} \\
+  \bar{\nabla} \lfloor F &= \mathtt{rgrad \gt F}
 \end{aligned}
 ```
 
@@ -152,8 +157,6 @@ You may also check out more examples [here](https://github.com/pygae/galgebra/bl
 
 For detailed documentation, please visit https://galgebra.readthedocs.io/ .
 
-**NOTE:** If you are coming from [sympy.galgebra](https://docs.sympy.org/0.7.6.1/modules/galgebra/) or [brombo/galgebra](https://github.com/brombo/galgebra), please check out section [Migration Guide](#migration-guide) below.
-
 <!-- end: getting-started -->
 <!-- begin: installation -->
 
@@ -201,7 +204,7 @@ Further, to run the complete test suite including the ones using [nbval](https:/
 
 ```bash
 pip install nbval
-pytest --nbval examples/ipython/ test --nbval-current-env --nbval-sanitize-with test/.nbval_sanitize.cfg
+pytest --nbval examples/ipython/ --nbval examples/primer/ test --nbval-current-env --nbval-sanitize-with test/.nbval_sanitize.cfg
 ```
 
 This could take more than 10 minutes, please be patient.
@@ -214,6 +217,15 @@ Migration Guide
 
 > Note: The APIs have changed since the era of `sympy.galgebra` and `brombo/galgebra`, some properties and methods are deprecated, the supported versions of Python and SymPy have also changed, please check [Changelog](https://galgebra.readthedocs.io/en/latest/changelog.html) and further update your scripts accordingly besides the following. If you encounter any problems, feel free to [open an issue](https://github.com/pygae/galgebra/issues/new)!
 
+### Migrating guide for readers of LAGA&VAGC
+
+Readers of [Linear and Geometric Algebra](http://www.faculty.luther.edu/~macdonal/laga/index.html) and [Vector and Geometric Calculus](http://www.faculty.luther.edu/~macdonal/vagc/index.html) might be guided by [GAlgebra Primer](http://www.faculty.luther.edu/~macdonal/GAlgebraPrimer.pdf) (version November 29, 2022, accessed May, 2024) to download [GAfiles.zip](http://www.faculty.luther.edu/~macdonal/GAfiles.zip) and copy `gprinter.py`, `lt.py`, `mv.py`, and `GAlgebraInit.py`¸ into where GAlgebra is installed. These steps are NO LONGER NEEDED since GAlgebra 0.6.0 as they are merge into GAlgebra with tests, copying these files will cause conflicts and regressions of fixed bugs.
+
+For minor differences to those files, please check out [the change log for GAlgebra 0.6.0](https://galgebra.readthedocs.io/en/latest/changelog.html#0.6.0). Also please note that:
+
+- `GAlgebraInit.py` is renamed to `primer.py` and can be imported like `from galgebra.primer import *` but it's usage is discouraged, although it saves some boilerplate code, this is not part of GAlgebra's maintained API, GAlgebra might remove it in future.
+- Some notebooks from the zip is included in GAlgebra in `examples/primer`.
+
 ### Migrating from [sympy.galgebra](https://docs.sympy.org/0.7.6.1/modules/galgebra/)
 
 GAlgebra is no longer part of SymPy since 1.0.0, if you have an import like this in your source:
@@ -249,6 +261,7 @@ Note that in the [doc/books](https://github.com/pygae/galgebra/blob/master/doc/b
 - `BookGA.pdf` which is a collection of notes on Geometric Algebra and Calculus based of "Geometric Algebra for Physicists" by Doran and Lasenby and on some papers by Lasenby and Hestenes.
 - `galgebra.pdf` which is the original main doc of GAlgebra in PDF format, while the math part is still valid, the part describing the installation and usage of GAlgebra is outdated, please read with caution or visit https://galgebra.readthedocs.io/ instead.
 - `Macdonald` which contains bundled supplementary materials for [Linear and Geometric Algebra](http://www.faculty.luther.edu/~macdonal/laga/index.html) and [Vector and Geometric Calculus](http://www.faculty.luther.edu/~macdonal/vagc/index.html) by Alan Macdonald, see [here](https://github.com/pygae/galgebra/blob/master/doc/books/Macdonald/) and [here](https://github.com/pygae/galgebra/blob/master/examples/Macdonald/) for more information.
+  - Particularly, `GAlgebraPrimer.pdf` is an archived version of [GAlgebra Primer](http://www.faculty.luther.edu/~macdonal/GAlgebraPrimer.pdf) by Alan Macdonald, last updated on November 29, 2022.
 
 <!-- end: bundled-resources -->
 

diff --git a/codecov.yml b/codecov.yml
@@ -0,0 +1,10 @@
+coverage:
+  status:
+    project:
+      default:
+        # Keep the project coverage target to auto
+        target: auto
+    patch:
+      default:
+        # Set the patch coverage target to 75%
+        target: 75%
diff --git a/doc/books/Macdonald/GAlgebraPrimer.pdf b/doc/books/Macdonald/GAlgebraPrimer.pdf
diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -2,6 +2,78 @@
 Changelog
 =========
 
+.. math::
+  \newcommand {\lt}[1] {\mathsf{#1}}
+  \newcommand {\mbf}[1] {\mathbf{#1}}
+  \newcommand {\es}[1] {\mathbf{e}_{#1}}
+  \newcommand {\til}[1] {\widetilde{#1}}
+
+- :bug:`518` :class:`~galgebra.mv.Mv` now correctly returns ``Mv`` instance when raise to power of zero. But in general, if one needs to call ``Mv`` methods on a result returned by some GA operations, it would be more prudent to initialize it as an ``Mv`` instance first, as sometimes the result becomes a ``sympy`` object.
+
+- :bug:`516` :attr:`~galgebra.mv.Mv.grades` no longer incorrectly returns ``None`` under some circumstances, as now all initialization branch will correctly call :meth:`~galgebra.mv.Mv.characterise_Mv`.
+
+- :bug:`513` :class:`~galgebra.mv.Mv` now correctly handles differentiating by a coordinate symbol.
+
+- :bug:`511` :class:`~galgebra.mv.Mv` now correctly handles negative integer power.
+
+- :feature:`510` Added :class:`~galgebra.gprinter.gprint` by Alan Bromborsky developed back in 2020, which improved printing of text and LaTeX for multiple GA objects in Jupytper notebooks, and is the recommended way to print GA formulas, see :doc:`tutorials/gprint` for a demonstration. Testability and test coverage are improved.
+
+- :support:`510` Testing infrastructure for generating and diffing PDFs is added, see ``test/test_gprinter.py`` and ``.github/workflows/ci.yml`` for details.
+
+- :feature:`510` Improved functionality for :class:`~galgebra.mv.Mv`, :class:`~galgebra.lt.Lt` by Greg Grunberg, with improved test coverage and minor fixes.
+
+  Changes by Greg Grunberg include (see the attached notebooks in :issue:`478` for details):
+
+  * The following methods of ``Mv`` are added, along with their corresponding functions (applied to multivectors ``A`` and ``B``):
+
+    * Undualization: :meth:`A.undual() <galgebra.mv.Mv.undual>` and :func:`undual(A) <galgebra.mv.undual>`
+    * Grade involution: :meth:`A.g_invol() <galgebra.mv.Mv.g_invol>` and :func:`g_invol(A) <galgebra.mv.g_invol>`
+    * Clifford conjugation: :meth:`A.ccon() <galgebra.mv.Mv.ccon>` and :func:`ccon(A) <galgebra.mv.ccon>`
+    * Scalar product: :meth:`A.sp(B) <galgebra.mv.Mv.sp>` and :func:`sp(A,B) <galgebra.mv.sp>`
+    * Quadratic form: :meth:`A.qform() <galgebra.mv.Mv.qform>` and :func:`qform(A) <galgebra.mv.qform>`
+    * Magnitude squared: :meth:`A.mag2() <galgebra.mv.Mv.mag2>` and :func:`mag2(A) <galgebra.mv.mag2>`
+    * Magnitude: :meth:`A.mag() <galgebra.mv.Mv.mag>` and :func:`mag(A) <galgebra.mv.mag>`
+
+  * The following methods of ``Mv`` are improved, along with their corresponding functions:
+
+    * Norm squared: :meth:`A.norm2() <galgebra.mv.Mv.norm2>` and :func:`norm2(A) <galgebra.mv.norm2>` now returns the absolute value of the quadratic form of ``A``.
+    * Norm: :meth:`A.norm() <galgebra.mv.Mv.norm>` and :func:`norm(A) <galgebra.mv.norm>`
+
+  * :class:`~galgebra.lt.Lt` is significantly improved and fixed, see also :doc:`tutorials/lt`:
+
+    * :class:`~galgebra.lt.Lt` adopts the contravariant-covariant indexing notation long used in tensor analysis and differential geometry, which is consistent with the indexing notation GAlgebra already uses for the display of a multivector's basis blade expansion
+    * :meth:`~galgebra.lt.Lt.Symbolic_Matrix` allows the creation, for a symbolic transformation :math:`\lt{T}`, of matrices with entries of any of the four forms :math:`{T^i}_j`, :math:`T^{ij}`, :math:`T_{ij}`, or :math:`{T_i}^j`, although GAlgebra will use only the first two.
+    * :meth:`~galgebra.lt.Lt.Dictionary_to_Matrix` fixes a bug that incorrectly raises an exception if `T` maps one or more of the basis vectors to the zero multivector, and improves the readability.
+    * :class:`~galgebra.lt.Lt` fixes a bug that erroneously post multiplies the transformation's standard matrix by ``self.Ga.g_inv`` (the reciprocal metric tensor), resulting in a contravariant-contravariant matrix  :math:`[T^{ij}] = [{T^i}_k g^{kj}]` instead of the standard matrix :math:`[{T^i}_j]`. In the same spirit, :meth:`~galgebra.lt.Lt.matrix` now returns the standard matrix $[{T^i}_j]$ instead of the product matrix :math:`[{T^i}_j][g_{ij}]`.
+    * :class:`~galgebra.lt.Lt` now distinguishes symmetric and antisymmetric transformations from general transformations, ``Amat`` will be the standard matrix :math:`[{T^i}_j]` of the transformation when ``mode=='g'``, , but will be :math:`[T_{ij}]` when ``mode in ['s','a']``.  Since :math:`[g^{ij}][T_{ij}] = [{T^i}_j]`, in either case ``Lt.__init__`` will receive the standard matrix as its first parameter.
+    * :class:`~galgebra.lt.Lt` now correctly handles Versor input, and initializes the internal ``lt_dict`` for the versor-based linear transformation.
+    * :class:`~galgebra.lt.Lt` adds support for both even and odd versors, after generalization of spinors to versors in ``Mv``.
+    * For versor based transformations, the inverse transformation :meth:`~galgebra.lt.Lt.inv` is now based on simply :math:`\til{\mbf{V}}` instead of :math:`\mbf{V}^{-1} = {\frac 1 {\mbf{V} \til{\mbf{V}}}} {\til{\mbf{V}}}`, as a versor-based transformation is independent of taking nonzero scalar multiples of the versor.
+    * :class:`~galgebra.lt.Lt` adds support for LaTeX printing of versor-based transformations.
+    * The determinant method :meth:`~galgebra.lt.Lt.det` for a linear transformation is fixed, it now uses directly the geometric algebra definition of :math:`\lt{L}`'s determinant: :math:`\det(\lt{L}) = \lt{L}(\mbf{E}) \mbf{E}^{-1}`, where :math:`\mbf{E}` denotes the basis blade :math:`\mbf{E} = \es{1} \wedge \cdots \wedge \es{n}` for the grade space of pseudoscalars.
+
+  Minor fixes includes:
+
+  * ``norm`` is fixed by using ``metric.square_root_of_expr`` instead of ``sqrt``
+  * making a "spinor" mv is kept for backward compatibility with existing tests, which is still aliased to making an "even" mv, see discussions ``10. An unimplemented suggestion`` in ``Changes to module lt.py`` attached in :issue:`478`
+  * fixed linting errors reported by ``flake8``
+  * fixed some typos of ``return``, ``raise`` etc.
+
+- :feature:`510` Added example notebooks for typical GAs by Greg Grunberg, and they are now part of the tests:
+
+  * Standard 2D Model :math:`\mathcal{G}_2`: :doc:`g2 <tutorials/g2>`
+  * Standard 3D Model :math:`\mathcal{G}_3`: :doc:`g3 <tutorials/g3>`
+  * Standard 4D Model :math:`\mathcal{G}_4`: :doc:`g4 <tutorials/g4>`
+  * 3D Homogeneous Coordinates :math:`\mathcal{G}_4`: :doc:`h3 <tutorials/h3>`
+  * 3D Conformal Model, Amsterdam convention :math:`\mathcal{G}_{4,1}`: :doc:`cm3 <tutorials/cm3>`
+  * Spacetime algebra: :doc:`spacetime <tutorials/spacetime>`
+  * Sphere-related algebras:
+
+    * Geometric algebra for unit sphere in :math:`\mathbb{R}^3` using spherical coordinates: :doc:`sp2 <tutorials/sp2>`
+    * Unit sphere :math:`\mathbb{R}^3` as a submanifold of :math:`\mathcal{G}_3` in cartesian coordinates: :doc:`sp2g3 <tutorials/sp2g3>`
+    * A geometric algebra for the unit sphere in :math:`\mathbb{R}^3` as a submanifold of :math:`\mathbb{R}^3` with spherical coordintes: :doc:`sp2sp3 <tutorials/sp2sp3>`
+    * Spherical Coordinates in :math:`\mathbb{R}^3`: :doc:`sp3 <tutorials/sp3>`
+
 - :release:`0.5.2 <2024.05.01>`
 
 - :support:`517` Add citation info, star history, contributors to README, and fix zenodo citation issue for ``0.5.1``.

diff --git a/doc/index.rst b/doc/index.rst
@@ -23,6 +23,8 @@
     :hidden:
 
     tutorials/algebra
+    tutorials/lt
+    tutorials/gprint
 
 .. toctree::
     :caption: API

diff --git a/doc/tutorials/cm3.nblink b/doc/tutorials/cm3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/cm3.ipynb"
+}
diff --git a/doc/tutorials/g2.nblink b/doc/tutorials/g2.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/g2.ipynb"
+}
diff --git a/doc/tutorials/g3.nblink b/doc/tutorials/g3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/g3.ipynb"
+}
diff --git a/doc/tutorials/g4.nblink b/doc/tutorials/g4.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/g4.ipynb"
+}
diff --git a/doc/tutorials/gprint.nblink b/doc/tutorials/gprint.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/gprint.ipynb"
+}
diff --git a/doc/tutorials/h3.nblink b/doc/tutorials/h3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/h3.ipynb"
+}
diff --git a/doc/tutorials/lt.nblink b/doc/tutorials/lt.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/ipython/lt.ipynb"
+}
diff --git a/doc/tutorials/sp2.nblink b/doc/tutorials/sp2.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/sp2.ipynb"
+}
diff --git a/doc/tutorials/sp2g3.nblink b/doc/tutorials/sp2g3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/sp2g3.ipynb"
+}
diff --git a/doc/tutorials/sp2sp3.nblink b/doc/tutorials/sp2sp3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/sp2sp3.ipynb"
+}
diff --git a/doc/tutorials/sp3.nblink b/doc/tutorials/sp3.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/sp3.ipynb"
+}
diff --git a/doc/tutorials/spacetime.nblink b/doc/tutorials/spacetime.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../examples/primer/spacetime.ipynb"
+}