Home

Awesome

Author: Barak Shoshany DOI: 10.21105/joss.03416 arXiv:2109.04193 License: MIT Language: Mathematica 13 GitHub stars GitHub forks GitHub release Open in Visual Studio Code

OGRe: An Object-Oriented General Relativity Package for Mathematica

Barak Shoshany
Department of Physics, Brock University,
1812 Sir Isaac Brock Way, St. Catharines, Ontario, L2S 3A1, Canada
bshoshany@brocku.ca | https://baraksh.com/
DOI: 10.21105/joss.03416

Important Update 2024-09-04: The Python port of this package, OGRePy, is finally out! Install it with pip install OGRePy, and try it out in a Jupyter notebook in Visual Studio Code or JupyterLab. The development of OGRePy is one of the main reasons I have not released a new version of OGRe in almost 3 years, but now that it's done, I hope to finally release v2.0.0 of OGRe in the coming months. Stay tuned!

Overview

OGRe is a modern Mathematica package for differential geometry and tensor calculus, designed to be both powerful and user-friendly. It can be used in a variety of contexts where tensor calculations are needed, in both mathematics and physics, but it is especially suitable for general relativity.

Tensors are abstract objects, which can be represented as multi-dimensional arrays once a choice of index configuration and coordinate system is made. OGRe stays true to this definition, but takes away the complexities that come with combining tensors in different representations. This is done using an object-oriented programming approach, taking advantage of principles such as encapsulation and class invariants to eliminate the possibility of user error.

The user initially defines each tensor in OGRe using its explicit components in any single representation. Operations on this tensor are then done abstractly, without needing to specify which representation to use. Possible operations include addition of tensors, multiplication of tensor by scalar, trace, contraction, and partial and covariant derivatives.

OGRe will automatically choose which representation to use for each tensor based on how the tensors are combined. For example, if two tensors are added, then OGRe will automatically use the same index configuration for both. Similarly, if two tensors are contracted, then OGRe will automatically ensure that the contracted indices are one upper (contravariant) and one lower (covariant). OGRe will also automatically transform all tensors being operated on to the same coordinate system.

Transformations between representations are done behind the scenes; all the user has to do is specify which metric to use for raising and lowering indices, and how to transform between the coordinate systems being used. This also means that there is no room for user error. The user cannot mistakenly perform "illegal" operations such as 2A<sup>μν</sup>+B<sub>μλ</sub>C<sub>λν</sub>. Instead, the user simply inputs the names of the tensors, the order (but not the configuration) of indices for each, and the operations to perform - and the correct combination 2A<sup>μν</sup>+B<sup>μ</sup><sub>λ</sub>C<sup>λν</sup> will be automatically deduced.

I initially created OGRe for use in my own research, so I made it as flexible and powerful as possible. I also wanted my students to be able to use it easily and efficiently, even if they only have minimal experience with Mathematica and/or general relativity, so I made it simple to learn and easy to use. As a result, this package is equally suitable for both experienced and novice researchers.

Features

Installing and loading the package

This package is compatible with Mathematica 12.0 or newer. It consists of only one file, OGRe.m. There are several different ways to load the package:

To uninstall the package, just delete the file from the Applications directory, which can be done from within Mathematica using the command DeleteFile[FileNameJoin[{$UserBaseDirectory, "Applications", "OGRe.m"}]].

Documentation

The full and detailed documentation for this package may be found in the following repository files:

Once the package is loaded, the documentation can be easily accessed by executing the command TDocs[], which automatically downloads the file OGRe_Documentation.nb from GitHub and opens it in Mathematica.

Issue and pull request policy

This package is under continuous and active development. If you encounter any bugs, or if you would like to request any additional features, please feel free to open a new issue on GitHub and I will look into it as soon as I can.

Contributions are always welcome. However, I release my projects in cumulative updates after editing and testing them locally on my system, so my policy is not to accept any pull requests. If you open a pull request, and I decide to incorporate your suggestion into the project, I will first modify your code to comply with the project's coding conventions (formatting, syntax, naming, comments, programming practices, etc.), and perform some tests to ensure that the change doesn't break anything. I will then merge it into the next release of the project, possibly together with some other changes. The new release will also include a note in CHANGELOG.md with a link to your pull request, and modifications to the documentation in README.md as needed.

Copyright and citing

Copyright (c) 2021 Barak Shoshany. Licensed under the MIT license.

If you use this package in published research, please cite it as follows:

You can also use the following BibTeX entry:

@article{Shoshany2021_OGRe,
    author    = {Barak Shoshany},
    doi       = {10.21105/joss.03416},
    journal   = {Journal of Open Source Software},
    number    = {65},
    pages     = {3416},
    publisher = {The Open Journal},
    title     = {OGRe: An Object-Oriented General Relativity Package for Mathematica},
    url       = {https://doi.org/10.21105/joss.03416},
    volume    = {6},
    year      = {2021}
}