Struct StateVectors

Source

pub struct StateVectors {
    pub position: DVec3,
    pub velocity: DVec3,
}

Expand description

A struct representing a position and velocity at a point in the orbit.

The position and velocity vectors are three-dimensional.

The position vector is in meters, while the velocity vector is in meters per second.

State vectors can be used to form an orbit, see to_compact_orbit and to_cached_orbit for more information.

Fields§

§position: DVec3

The 3D position at a point in the orbit, in meters.

§velocity: DVec3

The 3D velocity at a point in the orbit, in meters per second.

Implementations§

Source §

impl StateVectors

Source

pub fn to_compact_orbit(self, mu: f64, time: f64) -> CompactOrbit

Create a new CompactOrbit struct from the state vectors and the given mu and time values.

Mu is also known as the gravitational parameter, and is equal to GM, where G is the gravitational constant, and M is the mass of the parent body.
It can be described as how strongly the parent body pulls on the orbiting body.

Learn more about the gravitational parameter: https://en.wikipedia.org/wiki/Standard_gravitational_parameter

§Time

The time passed into the function is measured in seconds.

§Performance

This function is not too performant as it uses several trigonometric operations.

For single conversions, this is faster than the cached orbit converter.
However, consider using the cached orbit instead if you want to use the same orbit for many calculations, as the caching speed benefits should outgrow the small initialization overhead.

§Reference Frame

This function expects a state vector where the position’s origin (0.0, 0.0, 0.0) is the center of the parent body.

§Parabolic Support

This function does not yet support parabolic trajectories. Non-finite values may be returned for such cases.

§Constraints

The position must not be at the origin, and the velocity must not be at zero.
If this constraint is breached, you may get invalid values such as infinities or NaNs.

§Examples

Simple use-case:

use keplerian_sim::{CompactOrbit, OrbitTrait};

let orbit = CompactOrbit::default();
let mu = orbit.get_gravitational_parameter();
let time = 0.0;

let sv = orbit.get_state_vectors_at_time(time);

let new_orbit = sv.to_compact_orbit(mu, time);

assert_eq!(orbit.get_eccentricity(), new_orbit.get_eccentricity());
assert_eq!(orbit.get_periapsis(), new_orbit.get_periapsis());

To simulate an instantaneous 0.1 m/s prograde burn at periapsis:

use keplerian_sim::{CompactOrbit, OrbitTrait, StateVectors};
use glam::DVec3;

let orbit = CompactOrbit::default();
let mu = orbit.get_gravitational_parameter();
let time = 0.0;

let sv = orbit.get_state_vectors_at_time(time);
assert_eq!(
    sv,
    StateVectors {
        position: DVec3::new(1.0, 0.0, 0.0),
        velocity: DVec3::new(0.0, 1.0, 0.0),
    }
);

let new_sv = StateVectors {
    velocity: sv.velocity + DVec3::new(0.0, 0.1, 0.0),
    ..sv
};

let new_orbit = new_sv.to_compact_orbit(mu, time);

assert_eq!(
    new_orbit,
    CompactOrbit::new(
        0.2100000000000002, // eccentricity
        1.0, // periapsis
        0.0, // inclination
        0.0, // argument of periapsis
        0.0, // longitude of ascending node
        0.0, // mean anomaly
        1.0, // gravitational parameter
    )
)

Source

pub fn to_cached_orbit(self, mu: f64, time: f64) -> Orbit

Create a new Orbit struct from the state vectors and a given mu value.

§Mu

Mu is also known as the gravitational parameter, and is equal to GM, where G is the gravitational constant, and M is the mass of the parent body.
It can be described as how strongly the parent body pulls on the orbiting body.

Learn more about the gravitational parameter: https://en.wikipedia.org/wiki/Standard_gravitational_parameter

§Time

The time passed into the function is measured in seconds.

§Performance

This function is not too performant as it uses several trigonometric operations.

For single conversions, this is slower than the compact orbit converter, as there are some extra values that will be calculated and cached.
However, if you’re going to use this same orbit for many calculations, this should be better off in the long run as the caching performance benefits should outgrow the small initialization cost.

§Reference Frame

This function expects a state vector where the position’s origin (0.0, 0.0, 0.0) is the center of the parent body.

§Parabolic Support

This function does not yet support parabolic trajectories. Non-finite values may be returned for such cases.

§Constraints

The position must not be at the origin, and the velocity must not be at zero.
If this constraint is breached, you may get invalid values such as infinities or NaNs.

§Examples

Simple use-case:

use keplerian_sim::{Orbit, OrbitTrait};

let orbit = Orbit::default();
let mu = orbit.get_gravitational_parameter();
let time = 0.0;

let sv = orbit.get_state_vectors_at_time(time);

let new_orbit = sv.to_cached_orbit(mu, time);

assert_eq!(orbit.get_eccentricity(), new_orbit.get_eccentricity());
assert_eq!(orbit.get_periapsis(), new_orbit.get_periapsis());

To simulate an instantaneous 0.1 m/s prograde burn at periapsis:

use keplerian_sim::{Orbit, OrbitTrait, StateVectors};
use glam::DVec3;

let orbit = Orbit::default();
let mu = orbit.get_gravitational_parameter();
let time = 0.0;

let sv = orbit.get_state_vectors_at_time(time);
assert_eq!(
    sv,
    StateVectors {
        position: DVec3::new(1.0, 0.0, 0.0),
        velocity: DVec3::new(0.0, 1.0, 0.0),
    }
);

let new_sv = StateVectors {
    velocity: sv.velocity + DVec3::new(0.0, 0.1, 0.0),
    ..sv
};

let new_orbit = new_sv.to_cached_orbit(mu, time);

assert_eq!(
    new_orbit,
    Orbit::new(
        0.2100000000000002, // eccentricity
        1.0, // periapsis
        0.0, // inclination
        0.0, // argument of periapsis
        0.0, // longitude of ascending node
        0.0, // mean anomaly
        1.0, // gravitational parameter
    )
)

Source

pub fn to_custom_orbit<O>(self, mu: f64, time: f64) -> O
where O: From<CompactOrbit> + OrbitTrait,

Create a new custom orbit struct from the state vectors and a given mu value.

§Mu

Mu is also known as the gravitational parameter, and is equal to GM, where G is the gravitational constant, and M is the mass of the parent body.
It can be described as how strongly the parent body pulls on the orbiting body.

Learn more about the gravitational parameter: https://en.wikipedia.org/wiki/Standard_gravitational_parameter

§Time

The time passed into the function is measured in seconds.

§Performance

This function is not too performant as it uses several trigonometric operations.

The performance also depends on how fast the specified orbit type can convert between the CompactOrbit form into itself, and so we cannot guarantee any performance behaviors.

§Reference Frame

This function expects a state vector where the position’s origin (0.0, 0.0, 0.0) is the center of the parent body.

§Parabolic Support

This function does not yet support parabolic trajectories. Non-finite values may be returned for such cases.

§Constraints

The position must not be at the origin, and the velocity must not be at zero.
If this constraint is breached, you may get invalid values such as infinities or NaNs.