Struct nyx_space::cosmic::eclipse::Orbit

pub struct Orbit {
    pub x: f64,
    pub y: f64,
    pub z: f64,
    pub vx: f64,
    pub vy: f64,
    pub vz: f64,
    pub dt: Epoch,
    pub frame: Frame,
    pub stm: Option<Matrix6<f64>>,
}

Orbit defines an orbital state

Unless noted otherwise, algorithms are from GMAT 2016a StateConversionUtil.cpp. Regardless of the constructor used, this struct stores all the state information in Cartesian coordinates as these are always non singular. Note: although not yet supported, this struct may change once True of Date or other nutation frames are added to the toolkit.

Fields

x: f64

in km

y: f64

in km

z: f64

in km

vx: f64

in km/s

vy: f64

in km/s

vz: f64

in km/s

dt: Epoch

frame: Frame

Frame contains everything we need to compute state information

stm: Option<Matrix6<f64>>

Optionally stores the state transition matrix from the start of the propagation until the current time (i.e. trajectory STM, not step-size STM)

Implementations

impl Orbit

pub fn cartesian(
    x: f64,
    y: f64,
    z: f64,
    vx: f64,
    vy: f64,
    vz: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit in the provided frame at the provided Epoch.

Units: km, km, km, km/s, km/s, km/s

pub fn cartesian_stm(
    x: f64,
    y: f64,
    z: f64,
    vx: f64,
    vy: f64,
    vz: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit and initializes its STM.

pub fn from_position(x: f64, y: f64, z: f64, dt: Epoch, frame: Frame) -> Self

Creates a new Orbit in the provided frame at the provided Epoch in time with 0.0 velocity.

Units: km, km, km

pub fn cartesian_vec(state: &Vector6<f64>, dt: Epoch, frame: Frame) -> Self

Creates a new Orbit around in the provided frame from the borrowed state vector

The state vector must be x, y, z, vx, vy, vz. This function is a shortcut to cartesian and as such it has the same unit requirements.

pub fn rmag(&self) -> f64

Returns the magnitude of the radius vector in km

pub fn vmag(&self) -> f64

Returns the magnitude of the velocity vector in km/s

pub fn radius(&self) -> Vector3<f64>

Returns the radius vector of this Orbit in [km, km, km]

pub fn velocity(&self) -> Vector3<f64>

Returns the velocity vector of this Orbit in [km/s, km/s, km/s]

pub fn to_cartesian_vec(self) -> Vector6<f64>

Returns this state as a Cartesian Vector6 in [km, km, km, km/s, km/s, km/s]

Note that the time is not returned in the vector.

pub fn distance_to(&self, other: &Orbit) -> f64

Returns the distance in kilometers between this state and another state. Will panic is the frames are different

pub fn distance_to_point(&self, other: &Vector3<f64>) -> f64

Returns the distance in kilometers between this state and a point assumed to be in the same frame.

pub fn r_hat(&self) -> Vector3<f64>

Returns the unit vector in the direction of the state radius

pub fn v_hat(&self) -> Vector3<f64>

Returns the unit vector in the direction of the state velocity

pub fn keplerian(
    sma: f64,
    ecc: f64,
    inc: f64,
    raan: f64,
    aop: f64,
    ta: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit around the provided Celestial or Geoid frame from the Keplerian orbital elements.

Units: km, none, degrees, degrees, degrees, degrees

WARNING: This function will panic if the singularities in the conversion are expected. NOTE: The state is defined in Cartesian coordinates as they are non-singular. This causes rounding errors when creating a state from its Keplerian orbital elements (cf. the state tests). One should expect these errors to be on the order of 1e-12.

pub fn keplerian_altitude(
    sma_altitude: f64,
    ecc: f64,
    inc: f64,
    raan: f64,
    aop: f64,
    ta: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit from the provided semi-major axis altitude in kilometers

pub fn keplerian_apsis_radii(
    r_a: f64,
    r_p: f64,
    inc: f64,
    raan: f64,
    aop: f64,
    ta: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit from the provided radii of apoapsis and periapsis, in kilometers

pub fn keplerian_apsis_altitude(
    a_a: f64,
    a_p: f64,
    inc: f64,
    raan: f64,
    aop: f64,
    ta: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit from the provided altitudes of apoapsis and periapsis, in kilometers

pub fn keplerian_vec(state: &Vector6<f64>, dt: Epoch, frame: Frame) -> Self

Creates a new Orbit around the provided frame from the borrowed state vector

The state vector must be sma, ecc, inc, raan, aop, ta. This function is a shortcut to cartesian and as such it has the same unit requirements.

pub fn from_geodesic(
    latitude: f64,
    longitude: f64,
    height: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit from the geodetic latitude (φ), longitude (λ) and height with respect to the ellipsoid of the frame.

Units: degrees, degrees, km NOTE: This computation differs from the spherical coordinates because we consider the flattening of body. Reference: G. Xu and Y. Xu, “GPS”, DOI 10.1007/978-3-662-50367-6_2, 2016 WARNING: This uses the rotational rates known to Nyx. For other objects, use from_altlatlong for other celestial bodies.

pub fn from_altlatlong(
    latitude: f64,
    longitude: f64,
    height: f64,
    angular_velocity: f64,
    dt: Epoch,
    frame: Frame
) -> Self

Creates a new Orbit from the latitude (φ), longitude (λ) and height with respect to the frame’s ellipsoid.

Units: degrees, degrees, km, rad/s NOTE: This computation differs from the spherical coordinates because we consider the flattening of body. Reference: G. Xu and Y. Xu, “GPS”, DOI 10.1007/978-3-662-50367-6_2, 2016

pub fn to_keplerian_vec(self) -> Vector6<f64>

Returns this state as a Keplerian Vector6 in [km, none, degrees, degrees, degrees, degrees]

Note that the time is not returned in the vector.

pub fn hvec(&self) -> Vector3<f64>

Returns the orbital momentum vector

pub fn hx(&self) -> f64

Returns the orbital momentum value on the X axis

pub fn hy(&self) -> f64

Returns the orbital momentum value on the Y axis

pub fn hz(&self) -> f64

Returns the orbital momentum value on the Z axis

pub fn hmag(&self) -> f64

Returns the norm of the orbital momentum

pub fn energy(&self) -> f64

Returns the specific mechanical energy in km^2/s^2

pub fn with_radius(self, new_radius: &Vector3<f64>) -> Self

Returns a copy of the state with a new radius

pub fn with_velocity(self, new_velocity: &Vector3<f64>) -> Self

Returns a copy of the state with a new radius

pub fn sma(&self) -> f64

Returns the semi-major axis in km

pub fn set_sma(&mut self, new_sma_km: f64)

Mutates this orbit to change the SMA

pub fn with_sma(self, new_sma_km: f64) -> Self

Returns a copy of the state with a new SMA

pub fn add_sma(self, delta_sma: f64) -> Self

Returns a copy of the state with a provided SMA added to the current one

pub fn sma_altitude(&self) -> f64

Returns the SMA altitude in km

pub fn period(&self) -> Duration

Returns the period in seconds

pub fn evec(&self) -> Vector3<f64>

Returns the eccentricity vector (no unit)

pub fn ecc(&self) -> f64

Returns the eccentricity (no unit)

pub fn set_ecc(&mut self, new_ecc: f64)

Mutates this orbit to change the ECC

pub fn with_ecc(self, new_ecc: f64) -> Self

Returns a copy of the state with a new ECC

pub fn add_ecc(self, delta_ecc: f64) -> Self

Returns a copy of the state with a provided ECC added to the current one

pub fn inc(&self) -> f64

Returns the inclination in degrees

pub fn set_inc(&mut self, new_inc: f64)

Mutates this orbit to change the INC

pub fn with_inc(self, new_inc: f64) -> Self

Returns a copy of the state with a new INC

pub fn add_inc(self, delta_inc: f64) -> Self

Returns a copy of the state with a provided INC added to the current one

pub fn aop(&self) -> f64

Returns the argument of periapsis in degrees

pub fn set_aop(&mut self, new_aop: f64)

Mutates this orbit to change the AOP

pub fn with_aop(self, new_aop: f64) -> Self

Returns a copy of the state with a new AOP

pub fn add_aop(self, delta_aop: f64) -> Self

Returns a copy of the state with a provided AOP added to the current one

pub fn raan(&self) -> f64

Returns the right ascension of ther ascending node in degrees

pub fn set_raan(&mut self, new_raan: f64)

Mutates this orbit to change the RAAN

pub fn with_raan(self, new_raan: f64) -> Self

Returns a copy of the state with a new RAAN

pub fn add_raan(self, delta_raan: f64) -> Self

Returns a copy of the state with a provided RAAN added to the current one

pub fn ta(&self) -> f64

Returns the true anomaly in degrees between 0 and 360.0

NOTE: This function will emit a warning stating that the TA should be avoided if in a very near circular orbit Code from https://github.com/ChristopherRabotin/GMAT/blob/80bde040e12946a61dae90d9fc3538f16df34190/src/gmatutil/util/StateConversionUtil.cpp#L6835

LIMITATION: For an orbit whose true anomaly is (very nearly) 0.0 or 180.0, this function may return either 0.0 or 180.0 with a very small time increment. This is due to the precision of the cosine calculation: if the arccosine calculation is out of bounds, the sign of the cosine of the true anomaly is used to determine whether the true anomaly should be 0.0 or 180.0. In other words, there is an ambiguity in the computation in the true anomaly exactly at 180.0 and 0.0.

pub fn set_ta(&mut self, new_ta: f64)

Mutates this orbit to change the TA

pub fn with_ta(self, new_ta: f64) -> Self

Returns a copy of the state with a new TA

pub fn add_ta(self, delta_ta: f64) -> Self

Returns a copy of the state with a provided TA added to the current one

pub fn with_apoapsis_periapsis(self, new_ra: f64, new_rp: f64) -> Self

Returns a copy of this state with the provided apoasis and periapse

pub fn add_apoapsis_periapsis(self, delta_ra: f64, delta_rp: f64) -> Self

Returns a copy of this state with the provided apoasis and periapse added to the current values

pub fn tlong(&self) -> f64

Returns the true longitude in degrees

pub fn aol(&self) -> f64

Returns the argument of latitude in degrees

NOTE: If the orbit is near circular, the AoL will be computed from the true longitude instead of relying on the ill-defined true anomaly.

pub fn periapsis(&self) -> f64

Returns the radius of periapsis (or perigee around Earth), in kilometers.

pub fn apoapsis(&self) -> f64

Returns the radius of apoapsis (or apogee around Earth), in kilometers.

pub fn periapsis_altitude(&self) -> f64

Returns the altitude of periapsis (or perigee around Earth), in kilometers.

pub fn apoapsis_altitude(&self) -> f64

Returns the altitude of apoapsis (or apogee around Earth), in kilometers.

pub fn ea(&self) -> f64

Returns the eccentric anomaly in degrees

This is a conversion from GMAT’s StateConversionUtil::TrueToEccentricAnomaly

pub fn fpa(&self) -> f64

Returns the flight path angle in degrees

pub fn ma(&self) -> f64

Returns the mean anomaly in degrees

This is a conversion from GMAT’s StateConversionUtil::TrueToMeanAnomaly

pub fn semi_parameter(&self) -> f64

Returns the semi parameter (or semilatus rectum)

pub fn is_brouwer_short_valid(&self) -> bool

Returns whether this state satisfies the requirement to compute the Mean Brouwer Short orbital element set.

This is a conversion from GMAT’s StateConversionUtil::CartesianToBrouwerMeanShort. The details are at the log level info. NOTE: Mean Brouwer Short are only defined around Earth. However, nyx does not check the main celestial body around which the state is defined (GMAT does perform this verification).

pub fn geodetic_longitude(&self) -> f64

Returns the geodetic longitude (λ) in degrees. Value is between 0 and 360 degrees.

Although the reference is not Vallado, the math from Vallado proves to be equivalent. Reference: G. Xu and Y. Xu, “GPS”, DOI 10.1007/978-3-662-50367-6_2, 2016

pub fn geodetic_latitude(&self) -> f64

Returns the geodetic latitude (φ) in degrees. Value is between -180 and +180 degrees.

Reference: Vallado, 4th Ed., Algorithm 12 page 172.

pub fn geodetic_height(&self) -> f64

Returns the geodetic height in km.

Reference: Vallado, 4th Ed., Algorithm 12 page 172.

pub fn right_ascension(&self) -> f64

Returns the right ascension of this orbit in degrees

pub fn declination(&self) -> f64

Returns the declination of this orbit in degrees

pub fn semi_minor_axis(&self) -> f64

Returns the semi minor axis in km, includes code for a hyperbolic orbit

pub fn velocity_declination(&self) -> f64

Returns the velocity declination of this orbit in degrees

pub fn b_plane(&self) -> Result<BPlane, NyxError>

pub fn c3(&self) -> f64

Returns the $C_3$ of this orbit

pub fn vinf_periapsis(&self, turn_angle_degrees: f64) -> Result<f64, NyxError>

Returns the radius of periapse in kilometers for the provided turn angle of this hyperbolic orbit.

pub fn vinf_turn_angle(&self, periapsis_km: f64) -> Result<f64, NyxError>

Returns the turn angle in degrees for the provided radius of periapse passage of this hyperbolic orbit

pub fn hyperbolic_anomaly(&self) -> Result<f64, NyxError>

Returns the hyperbolic anomaly in degrees between 0 and 360.0

pub fn dcm_from_traj_frame(&self, from: Frame) -> Result<Matrix3<f64>, NyxError>

Returns the direct cosine rotation matrix to convert to this state’s frame (inertial or otherwise).

Example

let dcm_vnc2inertial = orbit.dcm_from_traj_frame(Frame::VNC)?; let vector_inertial = dcm_vnc2inertial * vector_vnc;

pub fn dcm6x6_from_traj_frame(
    &self,
    from: Frame
) -> Result<Matrix6<f64>, NyxError>

Returns a 6x6 DCM to convert to this inertial state. WARNING: This DCM does NOT contain the corrections needed for the transport theorem, and therefore the velocity rotation is wrong.

pub fn apply_dv(&mut self, dv: Vector3<f64>)

Apply the provided delta-v (in km/s)

pub fn with_dv(self, dv: Vector3<f64>) -> Self

Copies this orbit after applying the provided delta-v (in km/s)

pub fn rotate_by(&mut self, dcm: Matrix6<f64>)

Rotate this state provided a direct cosine matrix of position and velocity

pub fn with_rotation_by(&self, dcm: Matrix6<f64>) -> Self

Rotate this state provided a direct cosine matrix of position and velocity

pub fn position_rotated_by(&mut self, dcm: Matrix3<f64>)

Rotate the position and the velocity of this state provided a direct cosine matrix of position and velocity WARNING: You only want to use this if you’ll only be using the position components of the rotated state. This does not account for the transport theorem and therefore is physically WRONG.

pub fn with_position_rotated_by(&self, dcm: Matrix3<f64>) -> Self

Rotate the position of this state provided a direct cosine matrix of position and velocity WARNING: You only want to use this if you’ll only be using the position components of the rotated state. This does not account for the transport theorem and therefore is physically WRONG.

pub fn enable_stm(&mut self)

Sets the STM of this state of identity, which also enables computation of the STM for spacecraft navigation

pub fn disable_stm(&mut self)

Disable the STM of this state

pub fn with_stm(self) -> Self

Copies the current state but sets the STM to identity

pub fn without_stm(self) -> Self

Copies the current state but disables the STM

pub fn rss(&self, other: &Self) -> (f64, f64)

Returns the root sum square error between this state and the other, in kilometers for the position and kilometers per second in velocity

pub fn eq_within(&self, other: &Self, radial_tol: f64, velocity_tol: f64) -> bool

Returns whether this orbit and another are equal within the specified radial and velocity absolute tolerances

pub fn to_objectives(
    &self,
    params: &[StateParameter]
) -> Result<Vec<Objective>, NyxError>

Use the current orbit as a template to generate mission design objectives. Note: this sets the objective tolerances to be quite tight, so consider modifying them.

pub fn disperse(
    &self,
    mean: Vector6<f64>,
    cov: Matrix6<f64>
) -> Result<MultivariateNormal<Orbit>, NyxError>

Create a multivariate normal dispersion structure from this orbit with the provided mean and covariance, specified as {X, Y, Z, VX, VY, VZ} in km and km/s

pub fn disperse_zero_mean(
    &self,
    cov: Matrix6<f64>
) -> Result<MultivariateNormal<Orbit>, NyxError>

Create a multivariate normal dispersion structure from this orbit with the provided covariance, specified as {X, Y, Z, VX, VY, VZ} in km and km/s

Trait Implementations

impl Add<&Orbit> for &Orbit

fn add(self, other: &Orbit) -> Orbit

Add one state from another. Frame must be manually changed if needed. STM will be copied from &self.

type Output = Orbit

The resulting type after applying the + operator.

impl Add<Matrix<f64, Const<6>, Const<1>, <DefaultAllocator as Allocator<f64, Const<6>, Const<1>>>::Buffer>> for Orbit

fn add(self, other: OVector<f64, Const<6>>) -> Self

Adds the provided state deviation to this orbit

type Output = Orbit

The resulting type after applying the + operator.

impl Add<Orbit> for Orbit

fn add(self, other: Orbit) -> Orbit

Add one state from another. Frame must be manually changed if needed. STM will be copied from &self.

type Output = Orbit

The resulting type after applying the + operator.

impl AddAssign<Orbit> for Orbit

fn add_assign(&mut self, other: Self)

Performs the += operation.

impl Clone for Orbit

fn clone(&self) -> Orbit

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Orbit

fn default() -> Self

Returns the “default value” for a type.

impl Display for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl EstimateFrom<BaseSpacecraft<GuidanceMode>> for Orbit

fn extract(from: Spacecraft) -> Self

From the state extract the state to be estimated

impl EstimateFrom<Orbit> for Orbit

fn extract(from: Orbit) -> Self

From the state extract the state to be estimated

impl EventEvaluator<Orbit> for Event

fn epoch_precision(&self) -> Duration

fn value_precision(&self) -> f64

fn eval(&self, state: &Orbit) -> f64

fn eval_crossing(&self, prev_state: &S, next_state: &S) -> bool

impl EventEvaluator<Orbit> for PenumbraEvent

fn epoch_precision(&self) -> Duration

Stop searching when the time has converged to less than 0.1 seconds

fn value_precision(&self) -> f64

Finds the slightest penumbra within 2%(i.e. 98% in visibility)

fn eval(&self, observer: &Orbit) -> f64

fn eval_crossing(&self, prev_state: &S, next_state: &S) -> bool

impl EventEvaluator<Orbit> for UmbraEvent

fn epoch_precision(&self) -> Duration

Stop searching when the time has converged to less than 0.1 seconds

fn value_precision(&self) -> f64

Finds the darkest part of an eclipse within 2% of penumbra (i.e. 98% in shadow)

fn eval(&self, observer: &Orbit) -> f64

fn eval_crossing(&self, prev_state: &S, next_state: &S) -> bool

impl From<Orbit> for OrbitDual

fn from(orbit: Orbit) -> Self

Initialize a new OrbitDual from an orbit, no other initializers

impl InterpState for Orbit

fn params() -> Vec<StateParameter>

Return the parameters in order

fn value_and_deriv(&self, param: &StateParameter) -> Result<(f64, f64), NyxError>

Return the requested parameter and its time derivative

fn set_value_and_deriv(
    &mut self,
    param: &StateParameter,
    value: f64,
    _: f64
) -> Result<(), NyxError>

Sets the requested parameter

fn deriv(&self, param: &StateParameter) -> Result<f64, NyxError>

Return the time derivative requested parameter

impl LowerExp for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl LowerHex for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MdHdlr<Orbit> for OrbitStateOutput

fn handle(&mut self, state: &Orbit)

impl MeasurementDevice<Orbit, StdMeasurement> for GroundStation

fn measure(&self, rx: &Orbit) -> Option<StdMeasurement>

Perform a measurement from the ground station to the receiver (rx).

impl NavSolution<Orbit> for KfEstimate<Orbit>

fn orbital_state(&self) -> Orbit

fn expected_state(&self) -> Orbit

Returns the nominal state as computed by the dynamics

impl Neg for &Orbit

fn neg(self) -> Self::Output

Subtract one state from another. STM will be copied form &self.

type Output = Orbit

The resulting type after applying the - operator.

impl Neg for Orbit

fn neg(self) -> Self::Output

Subtract one state from another. STM will be copied from &self.

type Output = Orbit

The resulting type after applying the - operator.

impl PartialEq<Orbit> for Orbit

fn eq(&self, other: &Orbit) -> bool

Two states are equal if their position are equal within one centimeter and their velocities within one centimeter per second.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Orbit

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>where
    S: Serializer,

NOTE: This is not part of unit testing because there is no deseralization of Orbit (yet)

impl State for Orbit

Implementation of Orbit as a State for orbital dynamics with STM

fn zeros() -> Self

Returns a state whose position, velocity and frame are zero, and STM is I_{6x6}.

type Size = Const<6>

Size of the state and its STM

type VecLength = Const<42>

fn reset_stm(&mut self)

Return this state as a vector for the propagation/estimation By default, this is not implemented. This function must be implemented when filtering on this state.

fn as_vector(&self) -> Result<OVector<f64, Const<42>>, NyxError>

Return this state as a vector for the propagation/estimation

fn set(
    &mut self,
    epoch: Epoch,
    vector: &OVector<f64, Const<42>>
) -> Result<(), NyxError>

Set this state

fn stm(&self) -> Result<Matrix6<f64>, NyxError>

Return this state as a vector for the propagation/estimation By default, this is not implemented. This function must be implemented when filtering on this state.

fn epoch(&self) -> Epoch

Retrieve the Epoch

fn set_epoch(&mut self, epoch: Epoch)

Set the Epoch

fn add(self, other: OVector<f64, Self::Size>) -> Self

By default, this is not implemented. This function must be implemented when filtering on this state.

fn value(&self, param: &StateParameter) -> Result<f64, NyxError>

Return the value of the parameter, returns an error by default

fn set_value(&mut self, param: &StateParameter, val: f64) -> Result<(), NyxError>

Allows setting the value of the given parameter. NOTE: Most paramaters where the value is available CANNOT be also set for that parameter (it’s a much harder problem!)

impl Sub<&Orbit> for &Orbit

fn sub(self, other: &Orbit) -> Orbit

Subtract one state from another. STM will be copied from &self.

type Output = Orbit

The resulting type after applying the - operator.

impl Sub<Orbit> for Orbit

fn sub(self, other: Orbit) -> Orbit

Subtract one state from another. STM will be copied from &self.

type Output = Orbit

The resulting type after applying the - operator.

impl SubAssign<Orbit> for Orbit

fn sub_assign(&mut self, other: Self)

Performs the -= operation.

impl UpperExp for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl UpperHex for Orbit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Copy for Orbit