/ README.md
README.md
1 GAlgebra 2 ========================================= 3 4 Symbolic Geometric Algebra/Calculus package for SymPy. 5 6 [](https://deepwiki.com/pygae/galgebra) 7 [](https://pypi.org/project/galgebra/) 8 [](https://pypi.org/project/galgebra/) 9 [](https://github.com/pygae/galgebra/actions/workflows/ci.yml) 10 [](https://galgebra.readthedocs.io/en/latest/?badge=latest) 11 [](https://zenodo.org/badge/latestdoi/113447311) 12 13  14 15 Development Status 16 -------------------- 17 18  19  20 [](https://codecov.io/gh/pygae/galgebra) 21 [](https://codeclimate.com/github/pygae/galgebra/maintainability) 22 23 [brombo/galgebra](https://github.com/brombo/galgebra) was originally written by Alan Bromborsky, but was no longer actively maintained, and as of 2019-11-25 no longer exists. 24 25 [pygae/galgebra](https://github.com/pygae/galgebra) is a community fork, maintained by [Pythonic Geometric Algebra Enthusiasts](https://github.com/pygae). 26 27 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). 28 29 For information on how GAlgebra is used in other projects, see [Used by](https://github.com/pygae/galgebra/blob/master/doc/used_by.md). 30 31 > [!IMPORTANT] 32 > 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. 33 > 34 > 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) (unlikely nowadays), please check out section the old [Migration Guide](https://github.com/pygae/galgebra/blob/master/doc/old_migration_guide.md). 35 36 Features 37 -------------------- 38 39 ### Geometric Algebra 40 41 - Arbitrary Vector Basis and Metric 42 - Scalar, Vector, Bivector, Multivector, Pseudoscalar, Spinor, Blade 43 - Basic Geometric Algebra Operations 44 - Sum, Difference 45 - Geometric Product 46 - Outer and Inner Products 47 - Left and Right Contractions 48 - Reverse, Dual, Undual, Grade Involution, Clifford Conjugation 49 - Commutator 50 - Projection, Reflection, Rotation 51 - Reciprocal Frames 52 - Multivector Functions 53 - Exponential, Inverse, Norm, Magnitude 54 - Scalar Product, Quadratic Form 55 - Grade Selection, Even/Odd Parts 56 - Blade Coefficients, Components 57 - Inspecting Base/Blade Representation 58 - Symbolic Manipulations 59 - `expand`, `factor`, `simplify`, `subs`, `trigsimp` etc. 60 61 #### Overloaded Python operators for GA operations 62 63 | Operation | Python | Description | 64 |-----------|--------|-------------| 65 | `A + B` | `A + B` | Sum | 66 | `A - B` | `A - B` | Difference | 67 | `AB` | `A * B` | Geometric product | 68 | `A ^ B` | `A ^ B` | Outer (wedge) product | 69 | `A . B` | `A \| B` | Inner (dot) product | 70 | `A ⌋ B` | `A < B` | Left contraction | 71 | `A ⌊ B` | `A > B` | Right contraction | 72 | `A / B` | `A / B` | Division (A times B inverse) | 73 | `s / A` | `s / A` | Scalar divided by multivector | 74 | `~A` | `~A` | Reverse | 75 | `abs(A)` | `abs(A)` | Norm | 76 | `A[k]` | `A[k]` | Grade-k part | 77 78 #### Multivector methods and functions 79 80 | Method | Function | Description | 81 |--------|----------|-------------| 82 | `A.rev()` | `rev(A)` | Reverse | 83 | `A.dual()` | `dual(A)` | Dual | 84 | `A.undual()` | `undual(A)` | Undual | 85 | `A.g_invol()` | `g_invol(A)` | Grade involution | 86 | `A.ccon()` | `ccon(A)` | Clifford conjugation | 87 | `A.exp()` | `exp(A)` | Exponential | 88 | `A.inv()` | `inv(A)` | Inverse | 89 | `A.norm()` | `norm(A)` | Norm | 90 | `A.norm2()` | `norm2(A)` | Norm squared | 91 | `A.mag()` | `mag(A)` | Magnitude | 92 | `A.mag2()` | `mag2(A)` | Magnitude squared | 93 | `A.sp(B)` | `sp(A, B)` | Scalar product | 94 | `A.qform()` | `qform(A)` | Quadratic form | 95 | `A.even()` | `even(A)` | Even-grade part | 96 | `A.odd()` | `odd(A)` | Odd-grade part | 97 | `A.scalar()` | `scalar(A)` | Scalar (grade-0) part | 98 | `A.grade(k)` | -- | Grade-k part | 99 | `A.proj(blades)` | `proj(A, B)` | Projection | 100 | `A.blade_coefs()` | -- | Blade coefficients | 101 | `A.components()` | -- | List of single-blade components | 102 | `A.get_coefs(k)` | -- | Grade-k coefficients | 103 104 ### Geometric Calculus 105 106 - Geometric Derivative 107 - Submanifolds 108 - Linear Transformations 109 - Differential Operators 110 111 The various derivatives of a multivector function is accomplished by multiplying the gradient operator vector with the function: 112 113 ```math 114 \begin{aligned} 115 \nabla F &= \texttt{grad*F} \\ 116 F \bar{\nabla} &= \texttt{F*rgrad} \\ 117 \nabla {\wedge}F &= \mathtt{grad \verb!^! F} \\ 118 F {\wedge}\bar{\nabla} &= \mathtt{F \verb!^! rgrad} \\ 119 \nabla \cdot F &= \texttt{grad|F} \\ 120 F \cdot \bar{\nabla} &= \texttt{F|rgrad} \\ 121 \nabla \rfloor F &= \mathtt{grad \lt F} \\ 122 F \rfloor \bar{\nabla} &= \mathtt{F \lt rgrad} \\ 123 \nabla \lfloor F &= \mathtt{grad \gt F} \\ 124 F \lfloor \bar{\nabla} &= \mathtt{F \gt rgrad} 125 \end{aligned} 126 ``` 127 128 ```math 129 \begin{aligned} 130 F \nabla &= \texttt{F*grad} \\ 131 \bar{\nabla} F &= \texttt{rgrad*F} \\ 132 F {\wedge}\nabla &= \mathtt{F \verb!^! grad} \\ 133 \bar{\nabla} {\wedge}F &= \mathtt{rgrad \verb!^! F} \\ 134 F \cdot \nabla &= \texttt{F|grad} \\ 135 \bar{\nabla}\cdot F &= \texttt{rgrad|F} \\ 136 F \rfloor \nabla &= \mathtt{F \lt grad} \\ 137 \bar{\nabla} \rfloor F &= \mathtt{rgrad \lt F} \\ 138 F \lfloor \nabla &= \mathtt{F \gt grad} \\ 139 \bar{\nabla} \lfloor F &= \mathtt{rgrad \gt F} 140 \end{aligned} 141 ``` 142 143 Tip: an example for getting `grad` and `rgrad` of a 3-d Euclidean geometric algebra in rectangular coordinates: 144 145 ```python 146 from sympy import symbols 147 from galgebra.ga import Ga 148 149 o3d = Ga('e', g=[1,1,1], coords=symbols('x,y,z',real=True)) 150 (grad,rgrad) = o3d.grads() 151 ``` 152 153 ### Printing 154 155 - Enhanced Console Printing 156 - Latex Printing 157 - out-of-the-box support for Jupyter Notebook 158 - PDF generation and croping support if you have `pdflatex`/`pdfcrop` installed 159 160 <!-- Note: These comments are parsed by our sphinx documentation --> 161 162 <!-- begin: getting-started --> 163 164 Getting Started 165 --------------------- 166 167 After installing GAlgebra (see section [Installing GAlgebra](#installing-galgebra) below), in a Jupyter Notebook: 168 169 ```python 170 from sympy import symbols 171 from galgebra.ga import Ga 172 173 from galgebra.printer import Format 174 Format(Fmode = False, Dmode = True) 175 176 st4coords = (t,x,y,z) = symbols('t x y z', real=True) 177 st4 = Ga('e', 178 g=[1,-1,-1,-1], 179 coords=st4coords) 180 181 M = st4.mv('M','mv',f = True) 182 183 M.grade(3).Fmt(3,r'\langle \mathbf{M} \rangle _3') 184 ``` 185 186 You will see: 187 188 ```math 189 \begin{aligned} \langle \mathbf{M} \rangle _3 =& M^{txy} \boldsymbol{e}_{t}\wedge \boldsymbol{e}_{x}\wedge \boldsymbol{e}_{y} \\ & + M^{txz} \boldsymbol{e}_{t}\wedge \boldsymbol{e}_{x}\wedge \boldsymbol{e}_{z} \\ & + M^{tyz} \boldsymbol{e}_{t}\wedge \boldsymbol{e}_{y}\wedge \boldsymbol{e}_{z} \\ & + M^{xyz} \boldsymbol{e}_{x}\wedge \boldsymbol{e}_{y}\wedge \boldsymbol{e}_{z} \end{aligned} 190 ``` 191 192 You may also check out more examples [here](https://github.com/pygae/galgebra/blob/master/examples/). 193 194 For detailed documentation, please visit https://galgebra.readthedocs.io/ . 195 196 <!-- end: getting-started --> 197 <!-- begin: installation --> 198 199 Installing GAlgebra 200 --------------------- 201 202 ### Prerequisites 203 204 - Works on Linux, Windows, Mac OSX 205 - [Python](https://www.python.org/) >= 3.10 (3.10, 3.11, 3.12 tested via CI) 206 - 0.6.0 was the last supported release for Python 3.8/3.9 207 - 0.5.0 was the last supported release for Python 3.5-3.7 208 - 0.4.x was the last supported release series for Python 2.7 209 - [SymPy](https://www.sympy.org) >= 1.3 210 - Only SymPy 1.12 is tested via CI, see `.github/workflows/ci.yml` for more details 211 - 0.5.0 was the last supported release for SymPy 1.7 212 213 ### Installing GAlgebra From PyPI (Recommended for users) 214 215 ```bash 216 pip install galgebra 217 ``` 218 219 Then you are all set! 220 221 ### Installing GAlgebra From Source (Recommended for developers) 222 223 To install from the latest source code of GAlgebra: 224 225 ```bash 226 git clone https://github.com/pygae/galgebra.git 227 cd galgebra 228 pip install -e . 229 ``` 230 231 Note that the optional `-e` argument is used here for a developer install so modifying the source will take effect immediately without the need of reinstallation. 232 233 Now you may run tests to verify the installation, run from the root of the repository: 234 235 ```bash 236 pip install pytest 237 pytest test 238 ``` 239 240 Further, to run the complete test suite including the ones using [nbval](https://github.com/computationalmodelling/nbval), just run: 241 242 ```bash 243 pip install nbval 244 pytest --nbval examples/ipython/ --nbval examples/primer/ test --nbval-current-env --nbval-sanitize-with test/.nbval_sanitize.cfg 245 ``` 246 247 This could take more than 10 minutes, please be patient. 248 249 <!-- end: installation --> 250 <!-- begin: migration --> 251 252 Migration Guide 253 ---------------- 254 255 ### Migrating guide for readers of LAGA&VAGC 256 257 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 September 15, 2023, accessed April 2, 2026) 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. 258 259 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. Instead, you may follow the following steps: 260 261 ```bash 262 pip install galgebra 263 ``` 264 265 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: 266 267 - `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. 268 - Some notebooks from the zip are included in GAlgebra in `examples/primer`. 269 270 <!-- end: migration --> 271 272 <!-- begin: bundled-resources --> 273 274 Bundled Resources 275 ------------------ 276 277 Note that in the [doc/books](https://github.com/pygae/galgebra/blob/master/doc/books/) directory there are: 278 279 - `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. 280 - `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. 281 - `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. 282 - Particularly, `GAlgebraPrimer.pdf` is an archived version of [GAlgebra Primer](http://www.faculty.luther.edu/~macdonal/GAlgebraPrimer.pdf) by Alan Macdonald, last updated on September 15, 2023. 283 284 <!-- end: bundled-resources --> 285 286 Star History 287 ------------------- 288 289 <a href="https://star-history.com/#pygae/galgebra&Date"> 290 <picture> 291 <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=pygae/galgebra&type=Date&theme=dark" /> 292 <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=pygae/galgebra&type=Date" /> 293 <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=pygae/galgebra&type=Date" /> 294 </picture> 295 </a> 296 297 Contributors 298 ------------------- 299 300 <a href="https://github.com/pygae/galgebra/graphs/contributors"> 301 <img src="https://contrib.rocks/image?repo=pygae/galgebra" /> 302 </a> 303 304 Made with [contrib.rocks](https://contrib.rocks). 305 306 Citing This Library 307 ------------------- 308 309 For citation information, see [our `CITATION.md` file](https://github.com/pygae/galgebra/blob/master/CITATION.md).