<!-- remove-after-compile -->

<!-- /remove-after-compile -->

OGRePy: An Object-Oriented General Relativity Package for Python

By Barak Shoshany
Email: baraksh@gmail.com
Website: https://baraksh.com/
GitHub: https://github.com/bshoshany

GitHub repository: https://github.com/bshoshany/OGRePy
PyPi project: https://pypi.org/project/OGRePy/

This is the complete documentation for v1.3.1 of the package, released on 2025-08-03.

<!-- remove-after-compile --> <div style="color: red">

Note: While this Markdown document can be read on its own, it is meant to be compiled into a Jupyter notebook so that the output of the executed statements will be shown. Some parts will not make sense without seeing the output. The files OGRePy/docs/OGRePy_Documentation.ipynb, OGRePy/docs/OGRePy_Documentation.html, and OGRePy/docs/OGRePy_Documentation.pdf are the compiled notebook versions of this Markdown documentation, including all cell outputs.

</div> <!-- /remove-after-compile -->

• Introduction
  • Summary
  • Features
  • The object-oriented design philosophy
• Installing and loading the package
  • Trying the package without installation using OGRePy Live
  • Global installation
  • Installing in a virtual environment
  • Creating a Jupyter notebook
  • Importing the package
  • Getting help
• Creating and displaying tensor objects
  • Defining coordinates
  • Error checking
  • Defining metrics
  • Displaying tensors
  • Changing the output style
  • Line and volume elements
  • Choosing index letters
  • Creating tensors in a given manifold
• Operations on single tensors
  • Changing a tensor's symbol
  • Raising and lowering indices
  • Coordinate transformations
  • Replacing symbols in the tensor components
  • Customizing the simplification function
  • Getting information about tensors
  • Getting the components of a tensor
  • Comparing tensors
• Calculations with tensors
  • Addition of tensors
  • More on index specifications
  • Multiplication of tensor by scalar
  • Taking traces and contracting tensors: theoretical review
  • Taking traces and contracting tensors: OGRePy syntax
• Derivatives and curvature tensors
  • The Christoffel symbols
  • The Riemann tensor
  • Exact sign checks with list()
  • The riemann() method and caching
  • The Kretschmann scalar
  • The Ricci tensor and scalar
  • The Einstein tensor
  • Covariant derivatives
• Curves and geodesics
  • The curve Lagrangian
  • Geodesic equations from the Lagrangian
  • Geodesic equations from the Christoffel symbols
  • Geodesics equations in terms of the time coordinate
  • Changing the curve parameter
• About the project
  • Bug reports and feature requests
  • Contribution and pull request policy
  • Starring the repository
  • Acknowledgements
  • Copyright and citing
  • Other projects to check out

Introduction

Summary

OGRePy is a modern Python 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. OGRePy 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 OGRePy 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.

OGRePy 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 OGRePy will automatically use the same index configuration (upper and lower indices) for both. Similarly, if two tensors are contracted, then OGRePy will automatically ensure that the contracted indices are one upper (contravariant) and one lower (covariant). OGRePy 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 information only needs to be given once and for all when first defining the tensors and coordinate systems, and will be used automatically from that point on.

This also means that there is no room for user error. The user cannot mistakenly perform "illegal" operations such as $2A^{\mu\nu}+B_ {\mu\lambda}C_ {\lambda\nu}$. 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^{\mu\nu}+B^{\mu}{}_ {\lambda}C^{\lambda\nu}$ will be automatically deduced.

OGRePy is a Python port of the popular Mathematica package OGRe, first released in February 2021, used by many general relativity researchers worldwide. The Python port uses the same robust and performance-oriented algorithms, and retains the package's core design principles. It was made to be as flexible and powerful as possible, while also being simple to learn and easy to use, and suitable for both experienced and novice researchers. OGRePy uses SymPy to facilitate symbolic computations and Jupyter as a notebook interface.

The Python port was specifically designed to mimic as much of the original Mathematica package's syntax as possible, while also greatly improving on that syntax in many ways due to the fact that Python, unlike Mathematica, is a truly object-oriented language. The documentation for both packages was also kept as similar in structure and scope as possible, with the same practical examples. This means that anyone who is familiar with the Mathematica version should easily be able to use the Python version, and vice versa.

Features

• Define coordinate syste