agi.foundation.celestial

(agi.foundation.orbitpropagation-2023r2.jar)

Class SphericalHarmonicGravityField

java.lang.Object

agi.foundation.celestial.SphericalHarmonicGravityField

public class SphericalHarmonicGravityField
extends Object

The immutable class that describes the chosen subset and configuration of spherical harmonic gravitational model.

Constructor Summary

Constructors

Constructor and Description
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, CentralBody centralBody, int degree, int order, boolean includeTwoBody, SolidTideModel tideModel) Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, CentralBody centralBody, int degree, int order, boolean includeTwoBody, SphericalHarmonicsTideType tideType) Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, CentralBody centralBody, int degree, int order, int partialsDegree, int partialsOrder, boolean includeTwoBody, SolidTideModel tideModel) Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, CentralBody centralBody, int degree, int order, int partialsDegree, int partialsOrder, boolean includeTwoBody, SphericalHarmonicsTideType tideType) Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, int degree, int order, boolean includeTwoBody, SolidTideModel tideModel) Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, int degree, int order, boolean includeTwoBody, SphericalHarmonicsTideType tideType) Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, int degree, int order, int partialsDegree, int partialsOrder, boolean includeTwoBody, SolidTideModel tideModel) Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.
SphericalHarmonicGravityField(SphericalHarmonicGravityModel gravityModel, int degree, int order, int partialsDegree, int partialsOrder, boolean includeTwoBody, SphericalHarmonicsTideType tideType) Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.

Method Summary

Modifier and Type	Method and Description
CentralBody	getCentralBody() Gets the CentralBody (get) of this gravity field.
int	getDegree() Gets the degree of the subset of the model this gravitational field uses.
double	getGravitationalParameter() Gets the gravitational parameter of the central body described by this gravity field.
SphericalHarmonicGravityModel	getGravityModel() Gets the SphericalHarmonicGravityModel that is used to model the primary gravity field.
boolean	getIncludeTwoBodyGravity() Gets a value indicating whether to include the effects of (two-body) gravity of zero degree and order or to instead simply return the higher order perturbations.
int	getOrder() Gets the order of the subset of the model this gravitational field uses.
int	getPartialsDegree() Gets the degree of the subset of the model this gravitational field uses to calculate partial derivatives.
int	getPartialsOrder() Gets the order of the subset of the model this gravitational field uses to calculate partial derivatives.
double	getReferenceRadius() Gets the reference radius of the central body described by this gravity field.
SolidTideModel	getTideModel() Gets the SolidTideModel that is optionally used to add solid tides to a SphericalHarmonicGravityModel.
SphericalHarmonicsTideType	getTideType() Deprecated. The SphericalHarmonicsTideType enumeration is deprecated due to the addition of SolidTideModel classes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SphericalHarmonicGravityField

@Deprecated
public SphericalHarmonicGravityField(@Nonnull
                                                  SphericalHarmonicGravityModel gravityModel,
                                                  int degree,
                                                  int order,
                                                  boolean includeTwoBody,
                                                  @Nonnull
                                                  SphericalHarmonicsTideType tideType)

Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.

Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces.

If the inferred central body is Earth and the desired tideType is not automatically satisfied by the IncludesPermanentTides (get / set) property of the gravityModel, the tideType will be satisfied by adding or removing permanent tides from the gravityModel using the default IERS 2003 Earth permanent tide values (if needed).

Parameters:

gravityModel - The full gravity model to configure.

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideType - The type of tidal effects this field should include.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when the inferred central body is not Earth and the tideType requires permanent or time-varying tides to be added or removed from the gravityModel. In that case, use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,int,int,boolean,SolidTideModel).

IllegalStateException - Thrown if the CentralBodyName (get / set) in model does not refer to the Earth, Sun, or Moon. In that case use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,boolean,SphericalHarmonicsTideType)

SphericalHarmonicGravityField

@Deprecated
public SphericalHarmonicGravityField(@Nonnull
                                                  SphericalHarmonicGravityModel gravityModel,
                                                  CentralBody centralBody,
                                                  int degree,
                                                  int order,
                                                  boolean includeTwoBody,
                                                  @Nonnull
                                                  SphericalHarmonicsTideType tideType)

Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.

Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces. ///

If the centralBody is Earth and the desired tideType is not automatically satisfied by the IncludesPermanentTides (get / set) property of the gravityModel, the tideType will be satisfied by adding or removing permanent tides from the gravityModel using the default IERS 2003 Earth permanent tide values (if needed).

Parameters:

gravityModel - The full gravity model to configure.

centralBody - The central body to use for this gravity field instead of referencing CentralBodyName (get / set)

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideType - The type of tidal effects this field should include.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when the centralBody is not Earth and the tideType requires permanent or time-varying tides to be added or removed from the gravityModel. In that case, use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,boolean,SolidTideModel).

SphericalHarmonicGravityField

@Deprecated
public SphericalHarmonicGravityField(@Nonnull
                                                  SphericalHarmonicGravityModel gravityModel,
                                                  int degree,
                                                  int order,
                                                  int partialsDegree,
                                                  int partialsOrder,
                                                  boolean includeTwoBody,
                                                  @Nonnull
                                                  SphericalHarmonicsTideType tideType)

Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.

Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.

If the inferred central body is Earth and the desired tideType is not automatically satisfied by the IncludesPermanentTides (get / set) property of the gravityModel, the tideType will be satisfied by adding or removing permanent tides from the gravityModel using the default IERS 2003 Earth permanent tide values (if needed).

Parameters:

gravityModel - The full gravity model to configure.

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

partialsDegree - The degree to use for calculating partial derivatives.

partialsOrder - The order to use for calculating partial derivatives.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideType - The type of tidal effects this field should include.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when the inferred central body is not Earth and the tideType requires permanent or time-varying tides to be added or removed from the gravityModel. In that case, use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,int,int,int,int,boolean,SolidTideModel).

IllegalStateException - Thrown if the CentralBodyName (get / set) in model does not refer to the Earth, Sun, or Moon. In that case use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,int,int,boolean,SphericalHarmonicsTideType)

SphericalHarmonicGravityField

@Deprecated
public SphericalHarmonicGravityField(@Nonnull
                                                  SphericalHarmonicGravityModel gravityModel,
                                                  CentralBody centralBody,
                                                  int degree,
                                                  int order,
                                                  int partialsDegree,
                                                  int partialsOrder,
                                                  boolean includeTwoBody,
                                                  @Nonnull
                                                  SphericalHarmonicsTideType tideType)

Deprecated. Any constructor with tideType is deprecated and needs to be replaced with a constructor that includes a tideModel.

Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.

If the centralBody is Earth and the desired tideType is not automatically satisfied by the IncludesPermanentTides (get / set) property of the gravityModel, the tideType will be satisfied by adding or removing permanent tides from the gravityModel using the default IERS 2003 Earth permanent tide values (if needed).

Parameters:

gravityModel - The full gravity model to configure.

centralBody - The central body to use for this gravity field instead of referencing CentralBodyName (get / set)

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

partialsDegree - The degree to use for calculating partial derivatives.

partialsOrder - The order to use for calculating partial derivatives.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideType - The type of tidal effects this field should include.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when the centralBody is not Earth and the tideType requires permanent or time-varying tides to be added or removed from the gravityModel. In that case, use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,int,int,boolean,SolidTideModel).

SphericalHarmonicGravityField

public SphericalHarmonicGravityField(@Nonnull
                                     SphericalHarmonicGravityModel gravityModel,
                                     int degree,
                                     int order,
                                     boolean includeTwoBody,
                                     @Nullable
                                     SolidTideModel tideModel)

Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces.

Parameters:

gravityModel - The full gravity model to configure.

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideModel - The solid tide model that incorporates the effects of tides upon the gravity model.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when gravityModel includes permanent tides and tideModel is not null. In this case, the solid tide effects would be double counted. This exception can be mitigated by using SphericalHarmonicGravityModel.withoutEarthPermanentTides() or SphericalHarmonicGravityModel.withoutPermanentTides(agi.foundation.celestial.SphericalHarmonicCoefficients) to remove the permanent tides from gravityModel or to set tideModel to be null.

IllegalStateException - Thrown if the CentralBodyName (get / set) in gravityModel does not refer to one of the supported central bodies. In that case use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,boolean,SolidTideModel)

SphericalHarmonicGravityField

public SphericalHarmonicGravityField(@Nonnull
                                     SphericalHarmonicGravityModel gravityModel,
                                     CentralBody centralBody,
                                     int degree,
                                     int order,
                                     boolean includeTwoBody,
                                     @Nullable
                                     SolidTideModel tideModel)

Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, and a boolean representing whether or not to include two body forces.

Parameters:

gravityModel - The full gravity model to configure.

centralBody - The central body to use for this gravity field instead of referencing CentralBodyName (get / set)

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideModel - The solid tide model that incorporates the effects of tides upon the gravity model.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when gravityModel includes permanent tides and tideModel is not null. In this case, the solid tide effects would be double counted. This exception can be mitigated by using SphericalHarmonicGravityModel.withoutEarthPermanentTides() or SphericalHarmonicGravityModel.withoutPermanentTides(agi.foundation.celestial.SphericalHarmonicCoefficients) to remove the permanent tides from gravityModel or to set tideModel to be null.

SphericalHarmonicGravityField

public SphericalHarmonicGravityField(@Nonnull
                                     SphericalHarmonicGravityModel gravityModel,
                                     int degree,
                                     int order,
                                     int partialsDegree,
                                     int partialsOrder,
                                     boolean includeTwoBody,
                                     @Nullable
                                     SolidTideModel tideModel)

Initializes a new instance from a SphericalHarmonicGravityModel, the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.

Parameters:

gravityModel - The full gravity model to configure.

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

partialsDegree - The degree to use for calculating partial derivatives.

partialsOrder - The order to use for calculating partial derivatives.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideModel - The solid tide model that incorporates the effects of tides upon the gravity model.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when gravityModel includes permanent tides and tideModel is not null. In this case, the solid tide effects would be double counted. This exception can be mitigated by using SphericalHarmonicGravityModel.withoutEarthPermanentTides() or SphericalHarmonicGravityModel.withoutPermanentTides(agi.foundation.celestial.SphericalHarmonicCoefficients) to remove the permanent tides from gravityModel or to set tideModel to be null.

IllegalStateException - Thrown if the CentralBodyName (get / set) in gravityModel does not refer to the one of the supported central bodies. In that case use SphericalHarmonicGravityField.SphericalHarmonicGravityField(SphericalHarmonicGravityModel,agi.foundation.celestial.CentralBody,int,int,int,int,boolean,SolidTideModel).

SphericalHarmonicGravityField

public SphericalHarmonicGravityField(@Nonnull
                                     SphericalHarmonicGravityModel gravityModel,
                                     CentralBody centralBody,
                                     int degree,
                                     int order,
                                     int partialsDegree,
                                     int partialsOrder,
                                     boolean includeTwoBody,
                                     @Nullable
                                     SolidTideModel tideModel)

Initializes a new instance from a SphericalHarmonicGravityModel, a CentralBody (get), the degree and order of the subset of the model that this field represents, the degree and order to use when calculating partial derivatives, and a boolean representing whether or not to include two body forces.

Parameters:

gravityModel - The full gravity model to configure.

centralBody - The central body to use for this gravity field instead of referencing CentralBodyName (get / set)

degree - The desired degree. The configured gravity field will have this degree if FileDegree (get / set) allows it.

order - The desired order. The configured gravity field will have this degree if FileDegree (get / set), FileOrder (get / set) and degree allow it.

partialsDegree - The degree to use for calculating partial derivatives.

partialsOrder - The order to use for calculating partial derivatives.

includeTwoBody - The flag representing whether a force model using this field should include two body gravity, or just the higher order perturbations.

tideModel - The solid tide model that incorporates the effects of tides upon the gravity model.

Throws:

ArgumentNullException - Thrown when gravityModel is null.

ArgumentException - Thrown when gravityModel includes permanent tides and tideModel is not null. In this case, the solid tide effects would be double counted. This exception can be mitigated by using SphericalHarmonicGravityModel.withoutEarthPermanentTides() or SphericalHarmonicGravityModel.withoutPermanentTides(agi.foundation.celestial.SphericalHarmonicCoefficients) to remove the permanent tides from gravityModel or to set tideModel to be null.

Method Detail

getGravitationalParameter

public final double getGravitationalParameter()

Gets the gravitational parameter of the central body described by this gravity field.

getReferenceRadius

public final double getReferenceRadius()

Gets the reference radius of the central body described by this gravity field.

getCentralBody

public final CentralBody getCentralBody()

Gets the CentralBody (get) of this gravity field.

getTideType

@Nonnull
 @Deprecated
public final SphericalHarmonicsTideType getTideType()

Deprecated. The SphericalHarmonicsTideType enumeration is deprecated due to the addition of SolidTideModel classes.

Gets the SphericalHarmonicsTideType to use when calculating gravitational force. If this force model is set to use permanent tides and the gravity field does not include permanent tides, then they are modeled as defined in the IERS 2003 Convention and updated in 2006.

getGravityModel

@Nonnull
public final SphericalHarmonicGravityModel getGravityModel()

Gets the SphericalHarmonicGravityModel that is used to model the primary gravity field.

getTideModel

@Nullable
public final SolidTideModel getTideModel()

Gets the SolidTideModel that is optionally used to add solid tides to a SphericalHarmonicGravityModel. Can be null if there are no solid tides added to the gravity model.

getIncludeTwoBodyGravity

public final boolean getIncludeTwoBodyGravity()

Gets a value indicating whether to include the effects of (two-body) gravity of zero degree and order or to instead simply return the higher order perturbations.

getDegree

public final int getDegree()

Gets the degree of the subset of the model this gravitational field uses.

getOrder

public final int getOrder()

Gets the order of the subset of the model this gravitational field uses.

getPartialsDegree

public final int getPartialsDegree()

Gets the degree of the subset of the model this gravitational field uses to calculate partial derivatives.

getPartialsOrder

public final int getPartialsOrder()

Gets the order of the subset of the model this gravitational field uses to calculate partial derivatives.