Physics Functions

This page covers the various functions defined to compute specific physical quantities, and are largely defined for convenience. Also included on this page are the two functions related to making patched-conic approximations when a simulated satellite crosses a celestial body's gravitational sphere of influence (SOI).

• Conic patching functions
  • Escaping a SOI
  • Entering a SOI
• Physical quantities
  • Sphere of influence
  • Reduced mass
  • Gravitational potential
  • Centrifugal potential
  • Standard gravitational parameter
  • Radial velocity
  • Semi-latus rectum
  • Eccentricity vector
  • Mean angular motion

Conic patching functions

The conic patching functions are defined to streamline the otherwise tedious process of copying a system and computing the new trajectory of a satellite which has crossed a massive object's SOI.

For sake of clarity, we will refer to the dominant gravitational source as a star ($\odot$), the secondary gravitational source as a planet ($\oplus$), and the object on an escape trajectory is the satellite ($\oslash$). Despite being referred to as planets/stars, the function produces similar results with a satellite escaping the SOI of a moon, a moon's moon, etc.

Escaping a SOI

The escape function takes two Satellite objects (one is the object on an escape trajectory (the satellite), the other is the initial primary of the former (the planet)) and computes the new state of the system at the time of a satellite escaping a more massive satellite's SOI, and finally returns a new System object with the relevant conic sections patched.

Making the patched conic approximation for a satellite escaping a SOI is pretty straightforward vector addition, though admittedly, it is difficult to represent mathematically in a neat fashion:

$$\begin{align} \vec{r}_{\oslash \text{ wrt } \odot} &= \vec{r} _{\oslash \text{ wrt } \odot} + \vec{r} _{\oslash \text{ wrt } \oplus} \tag{1.1} \end{align}$$

$$\begin{align} \vec{v}_{\oslash \text{ wrt } \odot} &= \vec{v} _{\oslash \text{ wrt } \odot} + \vec{v} _{\oslash \text{ wrt } \oplus} \tag{1.2} \end{align}$$

Translated to English, the position of the satellite with respect to (abbr. wrt) the star is the sum of the position of the planet to the star and the position of the satellite with respect to the planet, and same goes for finding the velocity vector. From here, the trajectory parameters are calculated using the cartesian_2_keplerian function, which returns the six Keplerian orbital elements of the satellite in its trajectory relative to the star.

Entering a SOI

When it comes to a satellite on a trajectory around a star, when the satellite enters (encounters) the SOI of a planet, the patched conic approximation dictates that the satellite is only influenced by the gravitational force of the planet. In reality, this is inaccurate; any object with mass experiences the gravitational force from another object with mass regardless of the distance between the two. In practice, the scale of the numbers we're working with is so great that the force of gravity from a more distant, more massive body is effectively negligible for short-term considerations. Conversely, this discrepancy does play a role in the long-term evolution of a multiple-body system, like those resulting in the evolution of planetary orbits over the course of millions of years, or the very gradual increase of the Moon's semi-major axis in it orbit around Earth.

Similar to the previous function, determination of the satellite's new trajectory about the encountered planet can be determined via basic vector operations, transforming the relative position and velocity vectors from the star's reference frame to the planet's:

$$\begin{align} \vec{r}_{\oslash \text{ wrt } \oplus} &= \vec{r} _{\oslash \text{ wrt } \odot} - \vec{r} _{\oplus \text{ wrt } \odot} \tag{2.1} \end{align}$$

$$\begin{align} \vec{v}_{\oslash \text{ wrt } \oplus} &= \vec{v} _{\oslash \text{ wrt } \odot} - \vec{v} _{\oplus \text{ wrt } \odot} \tag{2.2} \end{align}$$

In English, the position of the satellite with respect to (abbr. wrt) the planet is the difference between the satellite's position relative to the star and the position of the planet relative to the star. From here, the trajectory parameters are calculated using the cartesian_2_keplerian function, which returns the six Keplerian orbital elements of the satellite in its trajectory relative to the encountered planet.

Physical quantities

Sphere of influence

A body's sphere of influence (abbr. SOI) is a measure of the radius away from a source of gravitation where the force of gravity from a planet is equivalent in magnitude to the force of gravity from an even more massive object like a star. This radius is particularly important for determining where a satellite is subjected to the most powerful acceleration and is especially useful in making patched conic approximations. While there is a more precise expression for finding this radius, the r_soi function uses the more common, general relation to determine the radius of the SOI $r_{\text{SOI}}$:

$$\begin{align} r_{\text{SOI}} &= r \left( \frac{m}{M} \right)^{\frac{2}{5}} \tag{3} \end{align}$$

Where $m$ is the mass of the secondary object (like a planet), $M$ is the mass of the primary object (like a star), and $r$ is the distance between the two bodies.

Reduced mass

The reduced mass of a two-body system $\rho$, (often $\mu$) is evaluated by the reduced_mass function and is exclusively utilized in one of the plotting functions and is given by:

$$\begin{align} \rho &= \frac{Mm}{M + m} \tag{4} \end{align}$$

Where again, $m$ is the mass of the secondary object (like a planet) and $M$ is the mass of the primary object (like a star).

Gravitational potential

The U_gravitational function takes a value for a radial distance, and the masses of two bodies and computes the gravitational potential energy at the given radial distance:

$$\begin{align} U_{\text{grav}}&= - \frac{GMm}{r} \tag{5} \end{align}$$

Centrifugal potential

The U_centrifugal function takes the same arguments as U_gravitational along with one more for the object's specific angular momentum $h$. The reduced mass of the system is internally computed and is represented as $\rho$:

$$\begin{align} U_{\text{cf}} &= \frac{\left(\rho h \right)^2}{2 \rho r^2} \tag{6} \end{align}$$

Standard gravitational parameter

The grav_param function takes two arguments, both for the masses of each body in a two-body system and returns the standard gravitational parameter $\mu$ of that two-body system in units of $\text{m}^3 \text{s}^{-2}$:

$$\begin{align} \mu &= G \left( M + m \right) \tag{7} \end{align}$$

When $\mu$ is computed through the Satellite class, if the less-massive body was created with negligible=True, the value returned will instead be given as: $\mu \approx\ GM$.

Radial velocity

The radial_velocity function takes position $\vec{r}$ and velocity $\vec{v}$ vectors and returns the magnitude of the radial velocity vector $v_r$:

$$\begin{align} v_r &= \vec{v} \cdot \hat{r} \tag{8} \end{align}$$

Where $\hat{r}$ is the unit position vector, and the sign of $v_r$ corresponds to the direction of the relative motion, where a positive radial velocity indicates the bodies are moving away from one another and a negative velocity indicates a decreasing radial distance between the two.

Semi-latus rectum

Caution

This function is currently incompatible with parabolic orbits ($e=1$), and will raise a NotImplementedError.

The semi_latus_rectum function takes two arguments, one for the semi-major axis $a$ and the other for the eccentricity $e$, and computes the relevant semi-latus rectum $\ell$:

$$\begin{align} \tag{9} \ell &= \begin{cases} a & \text{if } e = 1 \\ a (1 - e^2) & \text{if } e < 1 \\ -a (e^2 - 1) & \text{if } e > 1 \end{cases} \end{align}$$

Eccentricity vector

The eccentricity_vector function takes the same arguments as radial_velocity along with one more for the system's standard gravitational parameter $\mu$, and returns the eccentricity in vector form:

$$\begin{align} \vec{e} &= \frac{1}{\mu} \left( \vec{v} \times \left( \vec{r} \times \vec{v} \right)\right) - \hat{r} \tag{10} \end{align}$$

Mean angular motion

The mean_angular_motion function takes the standard gravitational parameter of a two-body system and an optional argument for the semi-major axis. If the semi-major axis is not provided, it is assumed that the trajectory is parabolic and therefore $n=\sqrt{\mu}$. Otherwise:

$$\begin{align} n &= \sqrt{\frac{\mu}{|a|^3}} \tag{11} \end{align}$$

True anomaly from state vectors

The true_anom_from_vectors function takes the same arguments as the eccentricity_vector function, and returns the true anomaly of a satellite at the given position. The first step to determine the true anomaly $\nu$ is to compute the eccentricity vector $\vec{e}$ to determine the un-adjusted angle $\theta$:

$$\begin{align} \theta &= \arccos \left( \frac{\vec{e} \cdot \vec{r}}{|\vec{e}||\vec{r}|} \right) \tag{12} \end{align}$$

Then, the angle is interpreted in the context of the eccentricity and radial velocity $v_r$:

$$\begin{align} \tag{13} \nu &= \begin{cases} \theta & \text{if } v_r > 0 \\ 360\degree - \theta & \text{if } v_r < 0 \text{ and } |\vec{e}| < 1 \\ -\theta & \text{if } v_r < 0 \text{ and } |\vec{e}| \ge 1 \end{cases} \end{align}$$