einsteinpy / einsteinpy

Repository for the EinsteinPy core package :rocket:

Name

EinsteinPy

Website

https://einsteinpy.org/

Version

0.5.dev0

EinsteinPy is an open-source pure Python package dedicated to the study of problems arising in General Relativity and gravitational physics. Using EinsteinPy, it is possible to approach problems symbolically as well as numerically. On the symbolic side, EinsteinPy provides a robust API, which allows users to access several predefined metrics or to define custom metrics and perform symbolic calculations on them. Computation of quantities, such as terms of metric tensors, Christoffel symbols, Riemann Curvature tensor, Ricci tensor, stress-energy tensor and more are all supported and extensible, since the symbolic modules are built on top of SymPy. On the numerical side, EinsteinPy provides tools to calculate and visualize geodesics, metric singularities and hypersurface embeddings in certain spacetimes. We hope to extend the package to include more features in the future. EinsteinPy is released under the MIT license.

Documentation

Complete documentation, including a user guide and an API reference, can be perused on the wonderful Read the Docs.

Examples

Several tutorial Jupyter notebooks on specific applications of EinsteinPy can be found in the examples directory. You can launch a Jupyter notebook instance in the cloud using binder to run and edit these notebooks without installing anything. Try it out!

Requirements

EinsteinPy requires the following Python packages:

• NumPy, for basic numerical routines
• SciPy, for solving ordinary differential equations
• SymPy, for symbolic calculations
• Astropy, for handling conversion between physical units
• Matplotlib, for producing static visualizations
• Plotly, for producing interactive visualizations
• Numba, for accelerating the code

EinsteinPy is currently tested on Linux, Windows and macOS on Python 3.7 and 3.8, against the latest NumPy.

Platform	Site	Status
Linux	CircleCI
macOS	Github Actions
Windows x64	Appveyor

Installation

Currently, the recommended way to install EinsteinPy is using pip from PyPI:

$ pip install einsteinpy

Or, you can install the package using conda:

$ conda install einsteinpy --channel conda-forge

Note that the package on conda-forge is currently a version behind PyPI. We are working on updating it.

For Debian/Ubuntu/Mint users, the package is installable via apt (Ubuntu 19.04 onwards):

$ sudo apt install python3-einsteinpy

If you prefer to install from source to stay on the latest but likely unstable version, you can do so using the method described here.

Problems

If the installation fails or you find something that doesn't work as expected, please open an issue in the issue tracker.

Contributing

EinsteinPy is a community project. Hence, all contributions are more than welcome! For more information, head to CONTRIBUTING or see the developer guide.

Support

Please join our [matrix] channel or Gitter chat room for general discussions and further queries.

Release announcements take place on our mailing list. Feel free to join!

If you still have a doubt, write to us directly at [email protected].

Citing

If you use EinsteinPy in your project, please drop us a line. You can also use the DOI to cite it in your publications. This is the latest one:

And this is an example citation format:

Shreyas Bapat et al (2021). EinsteinPy 0.4.0 (v0.4.0). Zenodo. https://doi.org/10.5281/zenodo.2582387

License

EinsteinPy is released under the MIT license, thereby allowing commercial use of the library. Please refer to COPYING for more details.

FAQ

Why "EinsteinPy"?

EinsteinPy borrows the name of the famous physicist, Nobel laureate and revolutionary human, Dr. Albert Einstein. This is a small tribute on our part for the amazing work he did for humanity!

Can I do <insert nerdy thing> with EinsteinPy?

EinsteinPy is focused on general relativity. One can always discuss probable features in discussion forums and the mailing list and also work with the maintainers to try to implement them. We welcome every contribution to EinsteinPy. Please see CONTRIBUTING for more details.

What's the future of the project?

EinsteinPy is actively maintained and we hope to receive an influx of new contributors. The best way to get an idea about the roadmap is to view the milestones of the project.

Inspiration

The documentation and code structure is shamelessly inspired by poliastro. We wholeheartedly thank the poliastro developers that made this possible. EinsteinPy is nothing without its supporters and community.

einsteinpy's Issues

Robertson-Walker flat metric

Implement detailed features for expanding universe metric and simulate geodesics for the same. Along with geodesics calculation, show signature plots for energy shifts.

Coding the right event horizon for Kerr & Kerr-Newman space-time

🐞 Problem
As of now, in calculation of time-like trajectory in Kerr metric stops and raises a warning on reaching schwarzschild radius. But event horizon in kerr spacetime is smaller than schwarzschild radius. But the exact values need to be researched.

🎯 Goal

• Research about the problem and specify the correct radius after which computation should stop in metric/kerr.py.

• Kerr

• Kerr-Newman

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #109
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Make a utility file for BL/Spherical coordinate conversion

🐞 Problem
The title is self-explanatory.

💡 Possible solutions

• Direct conversion formulas can be written
• or, In order to make coder's life easy, conversions can be done using Cartesian in between. That is Spherical->Cartesian->Boyer Lindqiuist and vice versa.
• Code it in the lines of utils/coord_transforms.py and
  utils/bl_coord_transforms.py

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #118>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Implement "kerr" Metric

Calculating the geodesics of rotating charged black holes (kerr geometry). It can be thought as a generalisation of Schwarzschild geometry.

Idea 💡 : We can create a parent class for Schwarzschild if that's possible.

Leverage numba jit

🐞 Problem

As of now, very simple computations take a lot of time to run. We can use @jit decorator provided by numba.

🎯 Goal

Make einsteinpy faster.

💡 Possible solutions

http://numba.pydata.org/numba-doc/latest/user/jit.html

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Implement the event horizon and ergosphere of Kerr black holes

🐞 What bugs you?
Event horizon is the point of no return in a black hole from which object can escape only with a speed greater than that of light. Ergosphere is an region around black hole where objects are forced to co-rotate with the black hole due to frame dragging. In kerr black holes:

• Formula for event horizon : R_H = 0.5(Rs + sqrt(Rs² - 4*a²))
  • See https://en.wikipedia.org/wiki/Kerr_metric#Important_surfaces
• Formula for ergosphere : 0.5(Rs + sqrt(Rs² - 4*a²*cos(theta)²))
  • See https://en.wikipedia.org/wiki/Kerr_metric#Important_surfaces

We can plot the erogosphere after the implementation.

🎯 Goal

• Implement event_horizon() in utils/kerr_utils.py as a function of r, Rs, a and give option to return in radius in BL(Boyer-Lindquist) as well as Spherical Coordinates. BL->spherical can be implemented by doing BL->cartesian->spherical
• Implement ergosphere() in utils/kerr_utils.py as a function of r, theta, Rs, a and give option to return radius in BL & spherical coordinates where Rs is schwarzschild radius.

Coordinate conversion utils are already implemented
The above formulas returns values in BL coordinates

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #114
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Migrate to bqplot for animations

https://github.com/bloomberg/bqplot

Worth exploring! Or not?

Implement Adaptive Mesh Refinement

🎯 Goal

implement basic Adaptive Mesh Refinement (AMR) in EinsteinPy which would lay the foundation for planned future black hole simulations. Lot of open source work exists for AMR which can be used as a reference. The student should port some of the AMR techniques from these existing solutions into EinsteinPy.

Release 0.1 checklist

Before release

• Rerun notebooks

• Complete Changelog

• Add future branch to CI scripts

• New branch

• Bump version in:

  • README.rst
  • __init__.py
  • Sphinx conf.py
  • AppVeyor CI script

• Check that the release branch will be tested on CI

• Check all the badges in README point to the appropriate git branch (replace master by new branch sed -i 's/master/.../g' README.rst)

• Check that docs badges and URLs point to appropriate tag (replace latest by new tag, without sed!)

• Commit

• Generate sdist and bdist_wheel

• twine upload dist/* --repository-url https://test.pypi.org/legacy/

• Tag

• Bump master to next development version

• Cherry pick the changelog with the release date

Release

• Push branch to GitHub and tags

• Upload sdist and bdist_wheel to PyPI - this step cannot be undone if the release is removed! twine upload dist/* --repository-url https://upload.pypi.org/legacy/

• Build conda-forge feedstock

• Create GitHub release

• Check Read the Docs (might take a while)

• Add Zenodo badge to GitHub release

• Send announcement email

• Add link to announcement email in GitHub release

• Close milestone

Import Mismatch Errors in CircleCI Build

https://circleci.com/gh/einsteinpy/einsteinpy/75?utm_campaign=vcs-integration-link&utm_medium=referral&utm_source=github-build-link

See this!

Simulation for Relativistic Kinematics of an electron.

For a theoritical understanding, please refer :
https://www.phys.hawaii.edu/~teb/phys481l/relkin.pdf

To get a rough idea, have a look at the relativistic particle-in-cell simulation of laser particle acceleration in an underdense hydrogen plasma :
https://youtu.be/5XCYbWH4Ys0

Using numpy.vectorize instead of for loops for a better code

https://github.com/einsteinpy/einsteinpy/blob/master/src/einsteinpy/utils/coord_transforms.py#L199-L204
For loop can be replaced by np.vectorize by vectorizing the functions used in the for loop

Add proper Documentation

• API Docs

• Readme

• User Guide

• Getting Started

EinsteinPy Logo in ReadTheDocs too large (2 MB).

🐞 Problem
As the logo is too large, it takes a long time to load as well as significant data usage :( . A smaller logo, probably 50-200 KB is feasible.

💡 Possible solutions
Supply with a smaller logo, docs/source/_static and change the logo in docs/source/conf.py .

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

jit all the functions which are slow

🐞 Problem

Some methods are tooo slow! For which we brought einsteinpy.ijit.jit
🎯 Goal
Make einsteinpy fast!

💡 Possible solutions
Identify the slow methods, and

from einsteinpy.ijit import jit

@jit
def ..

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

P.S : See #98 (comment)

Add functions for symbolic manipulations required in GR

We can use sympy to write functions which can act as utilities, and can return relevant expressions in symbolic form only. It can be nice cool addition to the library.

Add jupyter notebook examples

As the theory is quite rigorous, and a lack of documentation as of now, creating examples would help people use the library.

Add a 7th or 8th order ODE Solver

Resources are available on internet. Also, they can be shared later on this thread.

Implement "pp-wave" Metric

Implement pp-wave metric and solve geodesics equation. Further improve upon this implementation to simulate for gravitational waves metric and their characteristic signatures for simple matter distribution.

Add a 3D Plotting Module

Options: plotly, mayavi, mpl_3D

Visualise orbits from JPLHorizons and JPLEphem

This will be a nice feature to add as most users won't be bothering about finding the actual velocity and distance metrics. Hope we can get that from here?

No API Docs for EinsteinPy

🐞 Problem

There is no API Docs for the project which is bad :/

🎯 Goal

Subset of #10

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Evolve symbolic calculations related to GR as a seperate module within the library

🐞 What bugs you?
Along with being a library for numerical relativity, the library should support calculation of core GR related quantities in their symbolic form using Sympy. Currently, some symbolic functions reside in christoffel.py in utils.

🎯 Goal

• Move functions to a separate module and make this a full fledged feature of the library.
• Add many more useful quantities.
• Make the library one-stop solution for GR problems.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #70
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Badges in Documentation and README don't match

🐞 Problem

🎯 Goal
These two set of badges should match!

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Leverage the symmetry of christoffel symbols to ease it's calculation for Kerr Metric

🐞 Problem
Kerr Metric is symmetric over its lower indices. That is Yⁱ_kl = Yⁱ_lk. However this is not being leveraged for faster computation as of now.

🎯 Goal
Re-implement function christoffels() in utils/kerr_utils.py to make it faster

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #108
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Add code for hypersurface embedding in schwarzschild geometry

🐞 Problem
The code is ready but not pushed yet!

🎯 Goal

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Null Geodesics for Kerr & Schwarzschild Geometry

🐞 What bugs you?
Null-geodesics is the path traced by light rays in 4-D space-time. We aim to calculate null geodesics around non-rotating (Schwarzschild) and rotating (Kerr) massive bodies given the initial conditions.
This feature would support the one of the celebrated phenomenons in GR, gravitational lensing.

🎯 Goal

• Null geodesic in Kerr/Schwarzschild space-time
• Plotting class for both Kerr and Schwarzschild null geodesics.

💡 Possible solutions
Papers for references :

• https://arxiv.org/abs/1601.02063
• https://www.aanda.org/articles/aa/abs/2004/36/aa0814/aa0814.html
• http://www.math.mcgill.ca/gantumur/math599w17/project-kerr.pdf

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Link to Jupyter Notebooks in Getting Started is old

🐞 Problem
In https://einsteinpy-project.readthedocs.io/en/latest/getting_started.html#contribute

Running your first code using the library
Various examples can be found in the examples folder.

As we know, the sphinx beautifully generates the jupyter notebooks in documentation.
We should link it to that.
A very easy fix

🎯 Goal
We should focus on consistency in docs.

💡 Possible solutions
Just change the link of examples to: https://einsteinpy-project.readthedocs.io/en/latest/jupyter.html

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Create an Example Gallery Notebook

🐞 Problem
We must have something like this:
https://github.com/poliastro/poliastro/blob/master/index.ipynb

🎯 Goal

Ease in navigating through the notebook gallery.

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Clean the Messed up utils!

🐞 Problem

The utils module is currently too messed up.

🎯 Goal

💡 Possible solutions

Make necessary changes to clean it. Refactor modules, code.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Change indexing style in numpy arrays

🐞 Problem
To access an element of a 3-d array a, we have been doing a[i][j][k] which is slow as a copy of a[i] and a[i][j] is being created and discarded. Same for 2-d arrays where things are accessed by a[i][j]. I believe things are becoming slow for the reason

🎯 Goal

• convert 3-d array indexing from a[i][j][k] to a[i, j, k] wherever applicable.
• convert 2-d array indexing from a[i][j] to a[i, j] wherever applicable.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #116
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Resolve Units in Schwartzschild Metric

🐞 Problem
There is a lot of confusion about units and input values in this.

🎯 Goal
Getting the whole module consistent with astropy units

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Implement a basic ray tracer using schwarzschild geometry

A simple ray-tracer for visualizing how objects behind a massive object is made visible due to gravitational lensing. A bare-bones model could work initially.

Proper Testing Framework

Add tests for every written module.

BL and Normal Coordinate Transformation : Confusion in Names!

🐞 Problem

There is lot of confusion in coordinates transformation!
bl_coord_transforms and coord_transforms are not good names as in the coord_transforms does not specify the type of coordinates it works on while bl_coord_transforms clearly tells user what the module does! There is a need to make the coord transforms more intuitive.

🎯 Goal

Make coordinate transformations more intuitive in EinsteinPy

💡 Possible solutions

• Rename coord_transforms.py
• Merge both files into one
• Think of some other solution?

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #115
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Implementation of functionalities for gravitational lensing simulation

Improve upon an existing code for hypersurface embedding in schwarzschild geometry and implement methods to add features like:

• Plots to include asymptotically large radial distance to visualise gravitational lensing effects from distant source.
• Solve numerically geodesics equation on the 3d embedding surface to obtain null trajectory for light rays in spacial dimensions.
• Plot trajectories on the embedding to give an essence of the bending effect of light rays.
• Implement some basic calculations related to deviation angles for the sake of completeness of the module.

Add save methods in plotting classes

🐞 Problem

The plots, as of now can't be saved in png/jpg format
🎯 Goal

💡 Possible solutions

Add a save method to all the *GeodesicPlotters

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

More tests for Boyer-Lindquist coordinates where a!=0

🐞 Problem
As of now, Boyer-Lindquist coordinates utils are tested against values where a=0, which essentially makes it normal Spherical Coordinates.

🎯 Goal

• Writing tests for a!=0. The util is in utils/bl_coord_transforms.py and tests are in tests/test_utils/test_bl_coord_transforms.py .
• It would validate the module for a!=0 cases which would be frequently used in Kerr Metric related calculations.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #89
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Markdown in Jupyter Notebook not rendering properly in Sphinx Documentation

🐞 Markdown in Jupyter Notebook not rendering properly in Sphinx Documentation

See https://einsteinpy-project.readthedocs.io/en/latest/examples/Analysing%20Earth%20using%20EinsteinPy!.html

Add proper docstrings in Integrators module

🐞 Problem
proper docstrings are absent in integrator/runge_kutta.py.

🎯 Goal

• Adding proper docstrings
• It's important so that API is reflected correctly in ReadTheDocs.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Add cartesian coordinate system in schwarzschild.py

Currently the module is only accepting spherical coordinates.
It would be better if there is an option of using cartesian coordinates.
New Classmethod : Schwarzschild.from_cartesian()

Refactor some functions in Schwarzschild and Kerr class

🐞 Problem
calculate_trajectory() and calculate_trajectory_iterator() in both metric/schwarzschild.py and metric/kerr.py have become a mess. Refactoring is required.

🎯 Goal

• Refactor them such that both cyclometic and cognitive complexity remains low.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #113
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Simulation of orbits - Animations

Simulating orbits with coordinate time running and correspondingly plot radial and angular coordinates and showing plots in animation format

Add a plotting utility for Kerr Black holes

🐞 Problem

As in https://github.com/einsteinpy/einsteinpy/blob/master/docs/source/examples/Visualizing%20event%20horizon%20and%20ergosphere%20of%20Kerr%20black%20hole.ipynb

It clearly lacks plotting support from einsteinpy side.

🎯 Goal

Make a better plotting module for it

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Simulation for arbitrarily complicated matter fields

The implementation of numerical methods that would be used to simulate and solve Einstein's field equation for arbitrary stress-energy-momentum tensor field and obtain numerical values of metric tensor on a finite grid field.

website URL not working

🐞 Problem
website url for github.io not working

while follow the link, I am getting 404 error

Make Plotting Module more intuitive

Right now, one can only plot a single plot per code. Improve it 🚀

Benchmark and Validate the core Schwarzschild and Kerr Algorithms

🐞 Problem

Perform benchmark testing for both the algorithms. Because how do anyone know that the algorithms are correct?

🎯 Goal

To get clear understanding on performance of algorithm and its validation.

💡 Possible solutions

Validate against the industry standard or the books etc. Publish clear cut benchmarking results.

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Further Leverage the symmetry of christoffel symbols to ease it's calculation for Kerr Metric

🐞 Problem

Kerr Metric is symmetric over its lower indices. That is Yikl = Yilk. However this is not being leveraged enough for faster computation as of now.

🎯 Goal

Re-implement function christoffels() in utils/kerr_utils.py to make it faster

💡 Possible solutions

📋 Steps to solve the problem

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request and add this in comments - Addresses #<put issue number here>
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

Add badge for "chat on riot"

A "chat on riot" badge can be added to readme.rst just like "chat on gitter" badge.
See https://shields.io/category/chat

riot chat link : https://riot.im/app/#/room/#einsteinpy:matrix.org