StableOrbit#
- class kerrgeopy.stable.StableOrbit(a, p, e, x, initial_phases=(0, 0, 0, 0), M=None, mu=None)[source]#
Bases:
Orbit
Class representing a stable bound orbit in Kerr spacetime.
- Parameters:
a (double) – dimensionless angular momentum
p (double) – semi-latus rectum
e (double) – orbital eccentricity
x (double) – cosine of the orbital inclination
initial_phases (tuple, optional) – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\), defaults to (0,0,0,0)
M (double) – mass of the primary in solar masses, optional
mu (double) – mass of the smaller body in solar masses, optional
- Variables:
a – dimensionless angular momentum
p – semi-latus rectum
e – orbital eccentricity
x – cosine of the orbital inclination
M – mass of the primary in solar masses
mu – mass of the smaller body in solar masses
E – dimensionless energy
L – dimensionless angular momentum
Q – dimensionless carter constant
initial_phases – tuple of initial phases \((q_{t_0},q_{r_0},q_{\theta_0},q_{\phi_0})\)
stable – boolean indicating whether the orbit is stable
initial_position – tuple of initial position coordinates \((t_0, r_0, \theta_0, \phi_0)\)
initial_velocity – tuple of initial four-velocity components \((u^t_0, u^r_0, u^\theta_0, u^\phi_0)\)
upsilon_r – dimensionless radial orbital frequency in Mino time
upsilon_theta – dimensionless polar orbital frequency in Mino time
upsilon_phi – dimensionless azimuthal orbital frequency in Mino time
gamma – dimensionless time dilation factor
omega_r – dimensionless radial orbital frequency in Boyer-Lindquist time
omega_theta – dimensionless polar orbital frequency in Boyer-Lindquist time
omega_phi – dimensionless azimuthal orbital frequency in Boyer-Lindquist time
Methods
__init__
(a, p, e, x[, initial_phases, M, mu])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.
from_constants
(a, E, L, Q[, initial_phases, ...])Alternative constructor method that takes the constants of motion as arguments.
fundamental_frequencies
([units])Computes orbital frequencies in Boyer-Lindquist time.
is_visible
(points, elevation, azimuth)Determines if a point is visible from a given viewing angle or obscured by the black hole.
mino_frequencies
([units])Computes orbital frequencies in Mino time.
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 time, radial, polar, and azimuthal coordinates of the orbit 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)
- classmethod from_constants(a, E, L, Q, initial_phases=(0, 0, 0, 0), M=None, mu=None)[source]#
Alternative constructor method that takes the constants of motion as arguments.
- Parameters:
a (double) – spin parameter
E (double) – dimensionless energy
L (double) – dimensionless angular momentum
Q (double) – dimensionless Carter constant
M (double, optional) – mass of the primary in solar masses
mu (double, optional) – mass of the smaller body in solar masses
- fundamental_frequencies(units='natural')[source]#
Computes orbital frequencies in Boyer-Lindquist time. Returns dimensionless frequencies in geometrized units by default. M and mu must be defined in order to convert to physical units.
- Parameters:
units (str, optional) – units to return the frequencies in (options are “natural”, “mks”, “cgs” and “mHz”), defaults to “natural”
- Returns:
tuple of orbital frequencies \((\Omega_r, \Omega_\theta, \Omega_\phi)\)
- Return type:
tuple(double, double, double)
- 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
- mino_frequencies(units='natural')[source]#
Computes orbital frequencies in Mino time. Returns dimensionless frequencies in geometrized units by default. M and mu must be defined in order to convert to physical units.
- Parameters:
units (str, optional) – units to return the frequencies in (options are “natural”, “mks” and “cgs”), defaults to “natural”
- Returns:
tuple of orbital frequencies \((\Upsilon_r, \Upsilon_\theta, \Upsilon_\phi, \Gamma)\)
- Return type:
tuple(double, double, double, double)
- 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')[source]#
Computes the time, radial, polar, and azimuthal coordinates of the orbit 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)[source]#
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)