Orbit

class kerrgeopy.orbit.Orbit(a, initial_position, initial_velocity, M=None, mu=None)

Bases: object

Class representing an orbit in Kerr spacetime defined using initial conditions.

Parameters:

• a (double) – spin parameter

• initial_position (tuple(double,double,double,double)) – initial position of the orbit \((t_0,r_0,\theta_0,\phi_0)\)

• initial_velocity (tuple(double,double,double,double)) – initial four-velocity of the orbit \((u^t_0,u^r_0,u^\theta_0,u^\phi_0)\)

• M (double, optional) – mass of the primary in solar masses

• mu (double, optional) – mass of the smaller body in solar masses

Variables:

• a – spin parameter

• initial_position – initial position of the orbit \((t_0,r_0,\theta_0,\phi_0)\)

• initial_velocity – initial four-velocity of the orbit \((u^t_0,u^r_0,u^\theta_0,u^\phi_0)\)

• E – dimensionless energy

• L – dimensionless angular momentum

• Q – dimensionless carter constant

• stable – boolean indicating whether the orbit is stable

• upsilon_r – dimensionless radial orbital frequency in Mino time

• upsilon_theta – dimensionless polar orbital frequency in Mino time

__init__(a, initial_position, initial_velocity, M=None, mu=None)

Methods

__init__(a, initial_position, initial_velocity)
animate(filename[, lambda0, lambda1, ...])	Saves an animation of the orbit as an mp4 file.
constants_of_motion([units])	Computes the energy, angular momentum, and carter constant for the orbit.
four_velocity([initial_phases])	Computes the four velocity of the orbit as a function of Mino time using the geodesic equation.
is_visible(points, elevation, azimuth)	Determines if a point is visible from a given viewing angle or obscured by the black hole.
numerical_four_velocity([dx, initial_phases])	Computes the four velocity of the orbit as a function of Mino time using numerical differentiation.
plot([lambda0, lambda1, elevation, azimuth, ...])	Creates a plot of the orbit
trajectory([initial_phases, distance_units, ...])	Computes the components of the trajectory as a function of Mino time
trajectory_deltas([initial_phases])	Computes the trajectory deltas \(t_r(q_r)\), \(t_\theta(q_\theta)\), \(\phi_r(q_r)\) and \(\phi_\theta(q_\theta)\)

animate(filename, lambda0=0, lambda1=10, elevation=30, azimuth=- 60, initial_phases=None, grid=True, axes=True, color='red', tau=2, tail_length=5, lw=2, azimuthal_pan=None, elevation_pan=None, roll=None, speed=1, background_color=None, axis_limit=None, plot_components=False)

Saves an animation of the orbit as an mp4 file. Note that this function requires ffmpeg to be installed and may take several minutes to run depending on the length of the animation.

Parameters:

• filename (str) – filename to save the animation to

• lambda0 (double, optional) – starting mino time, defaults to 0

• lambda1 (double, optional) – ending mino time, defaults to 10

• elevation (double, optional) – camera elevation angle in degrees, defaults to 30

• azimuth (double, optional) – camera azimuthal angle in degrees, defaults to -60

• initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)

• grid (bool, optional) – sets visibility of the grid, defaults to True

• axes (bool, optional) – sets visibility of axes, defaults to True

• color (str, optional) – color of the orbital tail, defaults to “red”

• tau (double, optional) – time constant for the exponential decay in the opacity of the tail, defaults to 2

• tail_length (double, optional) – length of the tail in units of mino time, defaults to 5

• lw (double, optional) – linewidth of the orbital trajectory, defaults to 2

• azimuthal_pan (function, optional) – function defining the azimuthal angle of the camera in degrees as a function of mino time, defaults to None

• elevation_pan (function, optional) – function defining the elevation angle of the camera in degrees as a function of mino time, defaults to None

• roll (function, optional) – function defining the roll angle of the camera in degrees as a function of mino time, defaults to None

• axis_limit (function, optional) – sets the axis limit as a function of mino time, defaults to None

• speed (double, optional) – playback speed of the animation in units of mino time per second (must be a multiple of 1/8), defaults to 1

• background_color (str, optional) – color of the background, defaults to None

• plot_components (bool, optional) – if true, plots the components of the trajectory in addition to the trajectory itself, defaults to False

constants_of_motion(units='natural')

Computes the energy, angular momentum, and carter constant for the orbit. Computes dimensionless constants in geometried units by default. M and mu must be defined in order to convert to physical units.

Parameters:

units (str, optional) – units to return the constants of motion in (options are “natural”, “mks” and “cgs”), defaults to “natural”

Returns:

tuple of the form (E, L, Q)

Return type:

tuple(double, double, double)

four_velocity(initial_phases=None)

Computes the four velocity of the orbit as a function of Mino time using the geodesic equation.

Parameters:

initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)

Returns:

components of the four velocity (i.e. \(u^t,u^r,u^\theta,u^\phi\))

Return type:

tuple(function, function, function, function)

is_visible(points, elevation, azimuth)

Determines if a point is visible from a given viewing angle or obscured by the black hole. Viewing angles are defined as in https://matplotlib.org/stable/api/toolkits/mplot3d/view_angles.html and black hole is centered at the origin.

Parameters:

• points (array_like) – list of points given in cartesian coordinates

• elevation (double) – camera elevation angle in degrees

• azimuth (double) – camera azimuthal angle in degrees

Returns:

boolean array indicating whether each point is visible

Return type:

np.array

numerical_four_velocity(dx=1e-06, initial_phases=None)

Computes the four velocity of the orbit as a function of Mino time using numerical differentiation.

Parameters:

• dx (double, optional) – step size, defaults to 1e-6

• initial_phases (tuple(double,double,double,double), optional) – initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\), defaults to None

Returns:

components of the four velocity (i.e. \(u^t,u^r,u^\theta,u^\phi\))

Return type:

tuple(function, function, function, function)

plot(lambda0=0, lambda1=10, elevation=30, azimuth=- 60, initial_phases=None, grid=True, axes=True, lw=1, color='red', tau=inf, point_density=200)

Creates a plot of the orbit

Parameters:

• lambda0 (double, optional) – starting mino time

• lambda1 (double, optional) – ending mino time

• elevation (double, optional) – camera elevation angle in degrees, defaults to 30

• azimuth (double, optional) – camera azimuthal angle in degrees, defaults to -60

• initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)

• grid (bool, optional) – if true, grid lines are shown on plot

• axes (bool, optional) – if true, axes are shown on plot

• lw (double, optional) – linewidth of the orbital trajectory, defaults to 1

• color (str, optional) – color of the orbital trajectory, defaults to “red”

• tau (double, optional) – time constant for the exponential decay of the linewidth, defaults to infinity

• point_density (int, optional) – number of points to plot per unit of mino time, defaults to 200

Returns:

matplotlib figure and axes

Return type:

matplotlib.figure.Figure, matplotlib.axes._subplots.AxesSubplot

trajectory(initial_phases=None, distance_units='natural', time_units='natural')

Computes the components of the trajectory as a function of Mino time

Parameters:

• initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)

• distance_units (str, optional) – units to compute the radial component of the trajectory in (options are “natural”, “mks”, “cgs”, “au” and “km”), defaults to “natural”

• time_units (str, optional) – units to compute the time component of the trajectory in (options are “natural”, “mks”, “cgs”, and “days”), defaults to “natural”

Returns:

tuple of functions \((t(\lambda), r(\lambda), \theta(\lambda), \phi(\lambda))\)

Return type:

tuple(function, function, function, function)

trajectory_deltas(initial_phases=None)

Computes the trajectory deltas \(t_r(q_r)\), \(t_\theta(q_\theta)\), \(\phi_r(q_r)\) and \(\phi_\theta(q_\theta)\)

Parameters:

initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)

Returns:

tuple of trajectory deltas \((t_r(q_r), t_\theta(q_\theta), \phi_r(q_r),\phi_\theta(q_\theta))\)

Return type:

tuple(function, function, function, function)