Table of Contents

Class Spacecraft

Namespace
NominalSystems.Universe
Assembly
NominalSystems.Universe.dll

[Nominal] The spacecraft is a complex object that is used to represent a spacecraft in the simulation. It is a physical object that can be affected by external forces, contain state and dynamic effectors and is able to be integrated.

public class Spacecraft : PhysicalObject, IIntegrable
Inheritance
Spacecraft
Implements
Extension Methods

Constructors

Spacecraft()

Default constructor

protected Spacecraft()

Fields

Body

Stores a reference to the BodyEffector that is added to the object by default.

protected BodyEffector? Body

Field Value

BodyEffector

DynamicEffectors

Stores an array of dynamic effectors

protected List<DynamicEffector> DynamicEffectors

Field Value

List<DynamicEffector>

DynamicType

The type of orbit propagation that is used for this object.

[Metadata(IsAdvanced = true, Category = "Orbit")]
public DynamicType DynamicType

Field Value

DynamicType

In_SpicePlanetStateMsg

A reference to the spice planet state message of the nearest body that the spacecraft is orbiting.

public SpicePlanetStateMessage? In_SpicePlanetStateMsg

Field Value

SpicePlanetStateMessage

InitialOrbit

The initial classical elements of the body if the orbit is set

[Unit(UnitType.NONE)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public double[] InitialOrbit

Field Value

double[]

InitialOrbitTime

The simulation time in which the initial orbit was calculated.

[Unit(UnitType.SECOND)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public double InitialOrbitTime

Field Value

double

InitialPeriod

The orbital period of the body if the initial orbit is set

[Unit(UnitType.SECOND)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public double InitialPeriod

Field Value

double

IntegratePostLookup

A flag for if the body should integrate its state after the lookup is completed

[Metadata(Category = "Orbit")]
public bool IntegratePostLookup

Field Value

bool

IsInitialised

This flag will store whether to initialise the system. This will perform some initial checks on the serialization. This flag will just ensure that OnBegin, the system is all initialised correctly.

[Hidden]
public bool IsInitialised

Field Value

bool

LookupFilePath

The full file path for the CSV file, if it exists. This will ensure that a lookup table can be loaded correctly if the file path is valid and not empty.

[ReadOnly]
[Metadata(Category = "Orbit")]
public string LookupFilePath

Field Value

string

LookupRepeat

A flag for if the body should repeat the lookup data at the end of the data set, making a loop of the data.

[Metadata(Category = "Orbit")]
public bool LookupRepeat

Field Value

bool

LookupRotationType

The type of the rotation used for the orbital trajectories

[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public RotationType LookupRotationType

Field Value

RotationType

LookupTime

The current time on the lookup trajectory

[Unit(UnitType.SECOND)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public double LookupTime

Field Value

double

LookupTrajectoryType

The type of trajectory used for the orbital trajectories

[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public TrajectoryType LookupTrajectoryType

Field Value

TrajectoryType

OrbitedBody

The name of the body that this object is currently orbiting, if it exists. This will be used to calculate the gravitational forces acting around that body.

[ReadOnly]
[Metadata(Category = "Orbit")]
public string OrbitedBody

Field Value

string

Out_BodyMassMsg

The body mass properties message that stores the mass properties from all of the components that are added to this body. This will be the sum of all components and is used by the integrator.

public MassMessage? Out_BodyMassMsg

Field Value

MassMessage

Out_GravityMsg

The gravitational message that describes the gravitational energy of the object at a particular location.

public GravityMessage? Out_GravityMsg

Field Value

GravityMessage

Out_SpacecraftStateMsg

The body states message of the spacecraft contains all the information about the spacecraft's properties, including the position, energy and acceleration.

public SpacecraftStateMessage? Out_SpacecraftStateMsg

Field Value

SpacecraftStateMessage

OverrideMass

A flag whether to override the mass properties with some new custom ones. If this flag is enabled, the local mass values, including Center of Mass and Moment of Inertia, will be used instead of the totals for the mass calculation.

[ReadOnly]
[Metadata(Category = "Mass")]
public bool OverrideMass

Field Value

bool

State

A reference to the state model that exists on the current dynamic body that is able to propagate the state and store the derivatives if required.

[Hidden]
public StateModel? State

Field Value

StateModel

StateEffectors

Stores an array of state effectors

protected List<StateEffector> StateEffectors

Field Value

List<StateEffector>

SumExternalForce_B

[N] Sum of forces given in the body frame. This is reset on each update tick so this does not accumulate.

protected Vector3 SumExternalForce_B

Field Value

Vector3

SumExternalForce_N

[N] Sum of forces given in the inertial frame. This is reset on each update tick so this does not accumulate.

protected Vector3 SumExternalForce_N

Field Value

Vector3

SumTorque_LB_B

[N-m] Total torque about point B in B frame components. This is reset on each update tick so this does not accumulate.

protected Vector3 SumTorque_LB_B

Field Value

Vector3

Properties

Acceleration

The acceleration of the body in the inertial frame

[Unit(UnitType.METRE_PER_SECOND_SQUARED)]
[ReadOnly]
[Metadata(ContainedIn = "Out_SpacecraftStateMsg", Category = "Transform", ContainedName = "Acceleration_BN_N")]
public Vector3 Acceleration { get; }

Property Value

Vector3

Attitude

The attitude of the dynamic body in the form of a Modified Rodriguez Parameter (MRP). This is converted from the transformation of the local frame. This is equivalent to Transform_BN_N.

[Unit(UnitType.NONE)]
[Metadata(ContainedIn = "Out_SpacecraftStateMsg", Category = "Transform", ContainedName = "Sigma_BN")]
public Vector3 Attitude { get; set; }

Property Value

Vector3

AttitudeRate

Stores the current body attitude rate in the body frame

[Unit(UnitType.RADIAN_PER_SECOND)]
[Metadata(ContainedIn = "Out_SpacecraftStateMsg", Category = "Transform", ContainedName = "Omega_BN_B")]
public Vector3 AttitudeRate { get; set; }

Property Value

Vector3

DCM_LP

The DCM matrix of the component in the parent's frame (P), taken from the Component Transform (PL).

public override Matrix3 DCM_LP { get; set; }

Property Value

Matrix3

GeodeticCoordinates

A geodetic coordinates for the spacecraft relative to the orbiting planet. This will be in the form of latitude, longitude and altitude, where the units are in degrees and meters.

[Unit(UnitType.NONE)]
[ReadOnly]
[Metadata(Category = "Orbit")]
public Vector3 GeodeticCoordinates { get; }

Property Value

Vector3

Position

The position of the body in the inertial world state

[Unit(UnitType.METRE)]
[Metadata(ContainedIn = "Out_SpacecraftStateMsg", Category = "Transform", ContainedName = "Position_BN_N")]
public override Vector3 Position { get; set; }

Property Value

Vector3

Position_CN_N

The center of mass inertial position

[Unit(UnitType.METRE)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Transform", ContainedIn = "Out_SpacecraftStateMsg")]
public Vector3 Position_CN_N { get; }

Property Value

Vector3

Position_LP_P

The position of the object relative to the parented object (P). If there is no parent object, then this will be in the inertial frame.

[Hidden]
public override Vector3 Position_LP_P { get; set; }

Property Value

Vector3

TotalCenterOfMassB_B

The total center of mass in the body frame including all components attached

[Unit(UnitType.METRE)]
[Metadata(DisplayName = "Total Center of Mass", Category = "Mass", ContainedIn = "Out_BodyMassMsg", ContainedName = "CenterOfMass_LB_B")]
public Vector3 TotalCenterOfMassB_B { get; set; }

Property Value

Vector3

TotalMass

The total mass of the body including all components

[Unit(UnitType.KILOGRAM)]
[Metadata(ContainedIn = "Out_BodyMassMsg", Category = "Mass", ContainedName = "Mass")]
public double TotalMass { get; set; }

Property Value

double

TotalMomentOfInertiaB_B

The total moment of inertia in the body frame including all components attached

[Unit(UnitType.KILOGRAM_SQUARE_METRE)]
[Metadata(DisplayName = "Total Moment of Inertia", Category = "Mass", ContainedIn = "Out_BodyMassMsg", ContainedName = "MomentOfInertia_LB")]
public Matrix3 TotalMomentOfInertiaB_B { get; set; }

Property Value

Matrix3

Velocity

The velocity of the body in the inertial frame

[Unit(UnitType.METRE_PER_SECOND)]
[Metadata(ContainedIn = "Out_SpacecraftStateMsg", Category = "Transform", ContainedName = "Velocity_BN_N")]
public Vector3 Velocity { get; set; }

Property Value

Vector3

WGSCoordinates

A WGS Accurate Earth model coordinate system with the Earth as the center being used for the position.

[Unit(UnitType.NONE)]
[ReadOnly]
[Metadata(IsAdvanced = true, Category = "Orbit")]
public Vector3 WGSCoordinates { get; }

Property Value

Vector3

Methods

ComputeEffectorEnergy(double, ref Vector3)

Computes the energy and momentum from the effectors.

protected virtual void ComputeEffectorEnergy(double time, ref Vector3 totRotAngMomPntC_B)

Parameters

time double

The current time [s]

totRotAngMomPntC_B Vector3

The current angular momentum data

ComputeEnergyMomentum(double, double)

Computes the total energy and momentum of the object. It finds the total orbital energy, total orbital angular momentum, total rotational energy and total rotational angular momentum. These values are used for validation purposes

public virtual void ComputeEnergyMomentum(double time, double step)

Parameters

time double

The current time [s]

step double

The delta time [s]

GetGeodeticPosition()

Returns the latitude, longitude and altitude value of the body around the currently orbiting body. If there is no orbiting body, this will return an empty set. This assumes a spherical planet model.

public GeodeticElements GetGeodeticPosition()

Returns

GeodeticElements

The LLA of the current body

GetLookupTrajectoryCoordinates(bool, int)

Returns a list of all the lookup data positions from the lookup table, if they exist. These will be in the form of a Geodetic or PCI frame, depending on the input type.

public Vector3[] GetLookupTrajectoryCoordinates(bool geodetic = false, int maxPoints = -1)

Parameters

geodetic bool

[-] A flag whether to output the trajectory as a LLA

maxPoints int

[-] The number of points to add. If is less than 0, it will add all points

Returns

Vector3[]

[m] A list of inertial or geodetic lookup table locations.

GetOrbitalPosition()

Returns the position between the spacecraft and the orbited body. If there is no orbiting body, this will be the spacecraft's inertial position.

public Vector3 GetOrbitalPosition()

Returns

Vector3

[m] The relative position between the body and the planet

GetOrbitalVelocity()

Returns the velocity between the spacecraft and the orbited body. If there is no orbiting body, this will be the spacecraft's inertial velocity.

public Vector3 GetOrbitalVelocity()

Returns

Vector3

[m/s] The relative velocity between the body and the planet

GetRelativePosition(string)

Returns the relative position between the body and another planet.

public Vector3 GetRelativePosition(string planet)

Parameters

planet string

The planet to get the relative position between

Returns

Vector3

[m] The relative position

GetRelativeVelocity(string)

Returns the relative velocity between the body and another planet.

public Vector3 GetRelativeVelocity(string planet)

Parameters

planet string

The planet to get the relative velocity between

Returns

Vector3

[m/s] The relative velocity

GetWGSPosition()

Returns the latitude, longitude and altitude value of the body around the currently orbiting body. If there is no orbiting body, this will return an empty set. This assumes a WGS-84 planet model, typically used for the Earth.

public GeodeticElements GetWGSPosition()

Returns

GeodeticElements

The LLA in the WGS-84 form around Earth

InitialiseBody(double, Vector3, Matrix3, Vector3, Vector3)

Initialises the object with a series of elements from the Vector elements library

public void InitialiseBody(double mass, Vector3 com, Matrix3 moi, Vector3 attitude, Vector3 attitudeRate)

Parameters

mass double

[kg] The mass of the object

com Vector3

[m] The center of mass position of the object

moi Matrix3

[kg/m^2] The Moment of Inertia of the object

attitude Vector3

[rad] The starting attitude of the object

attitudeRate Vector3

[rad/s] The starting attitude rate of the object

LinkEffectorProperties()

Links all the effector properties on the dynamic and state effectors, ensuring access to the properties that may exist from the integrator.

protected void LinkEffectorProperties()

OnBegin(double)

Called when the object is beginning ticking for the first time. This is when the simulation calls the very first tick and will run before the update call.

protected override void OnBegin(double time)

Parameters

time double

[s] Current time of the simulation before the tick

OnCreate()

Called when the 'Component' is created from the controller.

protected override void OnCreate()

OnHierarchyChanged()

An event that is executed when some object within the chain of components in the hierarchy is added or removed from the system. This can be used to recalculate physics or create a new list of objects.

protected override void OnHierarchyChanged()

OnLoad(double)

Called after all of the data has been loaded from a save state on this object. This enables any post-load operations to be performed and extra data to be loaded from the metadata.

protected override void OnLoad(double time)

Parameters

time double

[s] The current clock time of the simulation

OnSave()

Called before the object is saved into the save state. This ensures that any additional metadata can be saved on the object before it is automatically serialized.

protected override void OnSave()

OnUpdate(double, double)

Called when the object should update from the simulation tick. This will take in a time and a step, where the time is the time of the clock before updating the object.

protected override void OnUpdate(double time, double step)

Parameters

time double

[s] Current time of the simulation before the update

step double

[s] The time-step to update during this tick

SetClassicElements(double, double, double, double, double, double, string)

Sets the classic elements of a body to a series of parameters based on all of the required parameters

public void SetClassicElements(double semiMajorAxis, double eccentricity, double inclination, double omegaAscension, double argumentOfPeriapsis, double trueAnomaly, string orbitingBody = "earth")

Parameters

semiMajorAxis double

[m] Semi Major Axis

eccentricity double

[-] The Eccentricity

inclination double

[rad] The Inclination

omegaAscension double

[rad] The Right Ascension

argumentOfPeriapsis double

[rad] The Periapsis Argument Node

trueAnomaly double

[rad] The True Anomaly

orbitingBody string

The name of the body orbiting

SetClassicElementsStruct(ClassicElements, string)

Sets the classic elements of a body to a series of parameters based on the Keplerian elements.

[Hidden]
public void SetClassicElementsStruct(ClassicElements elements, string orbitingBody = "earth")

Parameters

elements ClassicElements

The Classical Elements

orbitingBody string

The name of the body orbiting

SetCustomTrajectory(string, bool, string, bool, bool)

Sets the path to the lookup data to read from. This should be an absolute path to the CSV file with the data from the file. This assumes the file is of the correct format, but will not throw an error if not.

public bool SetCustomTrajectory(string lookupPath, bool integratePostData = true, string orbitingBody = "earth", bool usePointingAttitude = false, bool repeatAtEnd = false)

Parameters

lookupPath string

The path to the lookup data. This is the absolute path to the CSV file.

integratePostData bool

A flag for if the state should be integrated after the data is exhausted.

orbitingBody string

The name of the body orbiting

usePointingAttitude bool

A flag whether to use an attitude that points in the direction of motion

repeatAtEnd bool

A flag whether to repeat the data set at the end of the data sheet

Returns

bool

A successful add flag of lookup data

SetGeodeticElements(double, double, double, string)

Sets the Geodetic Elements of Latitude, Longitude and Altitude to some properties passed in by this function.

public void SetGeodeticElements(double latitude, double longitude, double altitude, string orbitingBody = "earth")

Parameters

latitude double

[deg] The Latitude

longitude double

[deg] The Longitude

altitude double

[m] The Altitude above the surface

orbitingBody string

The name of the body orbiting

SetGeodeticElementsStruct(GeodeticElements, string)

Sets the Geodetic Elements of Latitude, Longitude and Altitude to some properties in the element struct.

[Hidden]
public void SetGeodeticElementsStruct(GeodeticElements elements, string orbitingBody = "earth")

Parameters

elements GeodeticElements

The LLA Geodetic Elements data

orbitingBody string

The name of the body orbiting

SetHillFrame(Vector3, Vector3, Vector3, Vector3)

Sets the orientation of this body relative to another body using the Hill Frame vector.

public void SetHillFrame(Vector3 chiefPosition, Vector3 chiefVelocity, Vector3 hillPosition, Vector3 hillVelocity)

Parameters

chiefPosition Vector3

[m] The Chief Inertial Position

chiefVelocity Vector3

[m/s] The Chief Inertial Velocity

hillPosition Vector3

[m] The Hill Frame Position

hillVelocity Vector3

[m/s] The Hill Frame Velocity

SetTwoLineElements(string, string, string, string)

Sets the Two Line Elements (TLE) data of a particular craft with some individual lines of the TLE.

public void SetTwoLineElements(string line1, string line2, string line3, string orbitingBody = "earth")

Parameters

line1 string

The first line - usually the body information

line2 string

The second line for the TLE

line3 string

The third line for the TLE

orbitingBody string

The name of the body orbiting

SetTwoLineElementsFile(string, int, string)

Sets the Two Line Elements (TLE) data of a particular craft to some data.

[Hidden]
public string SetTwoLineElementsFile(string path, int index, string orbitingBody = "earth")

Parameters

path string

The full file path to the file that exists with the TLEs.

index int

The index of the orbiting body being initialised

orbitingBody string

The name of the body orbiting

Returns

string

SetTwoLineElementsStruct(TwoLineElements, string)

Sets the Two Line Elements (TLE) data of a particular craft to a specific position stored in the struct.

[Hidden]
public void SetTwoLineElementsStruct(TwoLineElements elements, string orbitingBody = "earth")

Parameters

elements TwoLineElements

The TLE elements data

orbitingBody string

The name of the body orbiting

SetVectorElements(Vector3, Vector3, string)

Sets the position and velocity of a body to a series of parameters.

public void SetVectorElements(Vector3 position, Vector3 velocity, string orbitingBody = "earth")

Parameters

position Vector3

[m] The position of the body

velocity Vector3

[m/s] The velocity of the body

orbitingBody string

The name of the body orbiting

SetVectorElementsStruct(VectorElements, string)

Sets the position and velocity of a body to a series of parameters based on the Vector Elements. This is just a position and velocity, with an optional orbiting body.

[Hidden]
public void SetVectorElementsStruct(VectorElements elements, string orbitingBody = "earth")

Parameters

elements VectorElements

The position and velocity of the body

orbitingBody string

The name of the body orbiting

UpdateEffectorEquations(double)

Updates the Effector Equations of state

protected virtual void UpdateEffectorEquations(double time)

Parameters

time double

The current time [s]

UpdateEquationsOfMotion(double, double)

Updates all of the State Equations with their correct derivatives

public virtual void UpdateEquationsOfMotion(double time, double step)

Parameters

time double

The current time [s]

step double

The current delta time [s]

UpdateLookup(double, double)

Attempts to use a lookup table for the body based on positions and rotations from the lookup table. This must have been initialised correctly otherwise no lookup parameters will be computed.

protected virtual void UpdateLookup(double time, double step)

Parameters

time double

[s] The current simulation time at this point

step double

[s] The current time-step

UpdateMassProperties(double, double)

Updates the Mass Properties of the body and all components. This will also attempt to cache the data on the components that exist on the hierarchy tree (in the body [B] frame) in a transform state for multiple use. This is the dirty flag.

public override void UpdateMassProperties(double time, double step)

Parameters

time double

The current time [s]

step double

The timestep between each

UpdateOrbit(double, double)

Attempts to adjust the position of the body by propagating the orbit around the current orbiting body. This assumes no other sources of dynamics or physics models.

protected virtual void UpdateOrbit(double time, double step)

Parameters

time double

[s] The current simulation time at this point

step double

[s] The current time-step

UpdateStates(double, double)

Updates the state of the dynamic body including updating the messages, properties and mass of the components. This does not perform the integration.

protected virtual void UpdateStates(double time, double step)

Parameters

time double

The current time [s]

step double

The delta time [s]

WriteOutputMessages(double)

Writes data to output messages that are able to store the state of data.

public virtual void WriteOutputMessages(double time)

Parameters

time double