# Struct nyx_space::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>>,
}``````
Expand description

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

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

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

Creates a new Orbit and initializes its STM.

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

Units: km, km, km

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.

Returns the magnitude of the radius vector in km

Returns the magnitude of the velocity vector in km/s

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

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

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.

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

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

Returns the unit vector in the direction of the state radius

Returns the unit vector in the direction of the state velocity

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.

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

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

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

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.

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.

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

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

Note that the time is not returned in the vector.

Returns the orbital momentum vector

Returns the orbital momentum value on the X axis

Returns the orbital momentum value on the Y axis

Returns the orbital momentum value on the Z axis

Returns the norm of the orbital momentum

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

Returns a copy of the state with a new radius

Returns a copy of the state with a new radius

Returns the semi-major axis in km

Mutates this orbit to change the SMA

Returns a copy of the state with a new SMA

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

Returns the SMA altitude in km

Returns the period in seconds

Returns the eccentricity vector (no unit)

Returns the eccentricity (no unit)

Mutates this orbit to change the ECC

Returns a copy of the state with a new ECC

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

Returns the inclination in degrees

Mutates this orbit to change the INC

Returns a copy of the state with a new INC

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

Returns the argument of periapsis in degrees

Mutates this orbit to change the AOP

Returns a copy of the state with a new AOP

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

Returns the right ascension of ther ascending node in degrees

Mutates this orbit to change the RAAN

Returns a copy of the state with a new RAAN

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

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.

Mutates this orbit to change the TA

Returns a copy of the state with a new TA

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

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

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

Returns the true longitude in degrees

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.

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

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

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

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

Returns the eccentric anomaly in degrees

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

Returns the flight path angle in degrees

Returns the mean anomaly in degrees

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

Returns the semi parameter (or semilatus rectum)

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).

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

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

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

Returns the geodetic height in km.

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

Returns the right ascension of this orbit in degrees

Returns the declination of this orbit in degrees

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

Returns the velocity declination of this orbit in degrees

Returns the \$C_3\$ of this orbit

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

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

Returns the hyperbolic anomaly in degrees between 0 and 360.0

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;

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.

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

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

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

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

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.

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.

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

Disable the STM of this state

Copies the current state but sets the STM to identity

Copies the current state but disables the STM

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

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

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.

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

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

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

The resulting type after applying the `+` operator.

Adds the provided state deviation to this orbit

The resulting type after applying the `+` operator.

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

The resulting type after applying the `+` operator.

Performs the `+=` operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from `source`. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Formats the value using the given formatter. Read more

From the state extract the state to be estimated

From the state extract the state to be estimated

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

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

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

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

Initialize a new OrbitDual from an orbit, no other initializers

Return the parameters in order

Return the requested parameter and its time derivative

Sets the requested parameter

Return the time derivative requested parameter

Formats the value using the given formatter.

Formats the value using the given formatter.

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

Returns the nominal state as computed by the dynamics

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

The resulting type after applying the `-` operator.

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

The resulting type after applying the `-` operator.

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

This method tests for `!=`.

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

Implementation of Orbit as a State for orbital dynamics with STM

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

Size of the state and its STM

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. Read more

Return this state as a vector for the propagation/estimation

Set this state

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. Read more

Retrieve the Epoch

Set the Epoch

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

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

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!) Read more

Reconstruct a new State from the provided delta time in seconds compared to the current state and with the provided vector. Read more

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

The resulting type after applying the `-` operator.

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

The resulting type after applying the `-` operator.

Performs the `-=` operation. Read more

Formats the value using the given formatter.

Formats the value using the given formatter.

## Blanket Implementations

Gets the `TypeId` of `self`. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Method to serialize generic items, slices, and slices of Vecs. Adds square brackets around Vecs (prettier lists). Implementation code is in `printing.rs`. Read more

Method to serialize generic items, slices, and slices of Vecs. Implementation code is in `printing.rs`. Read more

Printable in red

Printable in green

Printable in blue

Printable in yellow

Printable in magenta

Printable in cyan

Method to write vector(s) to file f (space separated, without brackets). Passes up io errors Read more

Method to print vector(s) to stdout (space separated,without brackets).

Should always be `Self`

The inverse inclusion map: attempts to construct `self` from the equivalent element of its superset. Read more

Checks if `self` is actually part of its subset `T` (and can be converted to it).

Use with care! Same as `self.to_subset` but without any property checks. Always succeeds.

The inclusion map: converts `self` to the equivalent element of its superset.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a `String`. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.