agi.foundation.routedesign.advanced

(agi.foundation.routedesign-2024r3.jar)

Class StandardTransitionProfileSegment

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.routedesign.advanced.ProfileSegment

agi.foundation.routedesign.advanced.StandardTransitionProfileSegment

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

public final class StandardTransitionProfileSegment
extends ProfileSegment

A profile segment that connects a straight line between the initial height, initial height rate, initial speed, final height, final height rate, and final speed. The profile segment will attempt to conserve the total initial speed (combined horizontal and vertical) through the incline, accelerating or decelerating along the incline to match the final total speed (combined horizontal and vertical).

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(ProfileSegment other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
Object	clone(CopyContext context) Clones this object using the specified context.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
static StandardTransitionProfileSegment	getConstrainedInclinedSegment(double h0, double hf, double a0, double af, double v0, double vf, double g0, double gf, double sf, TerrainProvider heightReference) Get a segment without specifying the intermediate flight path angle.
static StandardTransitionProfileSegment	getDegenerateSegment(double height, double heightRate, double horizontalSpeed, TerrainProvider heightReference) Creates a segment which represents an instantaneous height and height rate for degenerate surface geometry.
double	getFinalAngle() Gets the final flight path angle with respect to the reference surface, in radians.
Duration	getFinalDuration() Gets the time it takes for the segment to transition from the inclined slope to the final conditions.
double	getFinalHeight() Gets the final height above the reference surface, in meters.
double	getFinalHeightRate() Gets the final vertical velocity, in meters per second.
double	getFinalSurfaceSpeed() Gets the value for the horizontal surface speed at the start of the profile, in meters per second.
double	getHeight(Duration time) Get the value for the height above the TerrainProvider height reference specified by the StandardTransitionProfileSegment.getHeightReference(agi.foundation.time.Duration) method at the given time.
Motion1<Double>	getHeight(Duration time, int order) Get the value for the height above the TerrainProvider height reference specified by the StandardTransitionProfileSegment.getHeightReference(agi.foundation.time.Duration) method at the given time.
TerrainProvider	getHeightReference(Duration time) Get the TerrainProvider height reference for the profile height at the given time.
double	getInitialAngle() Gets the initial flight path angle with respect to the reference surface, in radians.
Duration	getInitialDuration() Gets the time it takes for the segment to transition from the initial conditions to the inclined slope.
double	getInitialHeight() Gets the initial height above the reference surface, in meters.
double	getInitialHeightRate() Gets the initial vertical velocity, in meters per second.
double	getInitialSurfaceSpeed() Gets the value for the horizontal surface speed at the start of the profile, in meters per second.
double	getIntermediateAccelerationAlongSlope() Gets the total acceleration along the climb or descent plane measured positive along the direction of motion, in meters per second squared.
Duration	getIntermediateDuration() Gets the time it takes for the segment to transition along the inclined slope while ascending or descending.
double	getIntermediateHorizontalAcceleration() Gets the horizontal acceleration during the climb or descent measured positive along the direction of motion, in meters per second squared.
double	getIntermediateHorizontalRate() Gets the horizontal velocity during the climb or descent, in meters per second.
double	getIntermediateInclineAngle() Gets the intermediate flight path angle with respect to the corresponding reference surface, in radians.
double	getIntermediateVerticalAcceleration() Gets the vertical acceleration during the climb or descent measured positive along the direction of motion, in meters per second squared.
double	getIntermediateVerticalRate() Gets the vertical velocity during the climb or descent, in meters per second.
double	getMaximumIntermediateVerticalRate() Gets the maximum rate of change of the height, in meters per second, when transitioning from one height to the next.
static StandardTransitionProfileSegment	getSegmentAtAngle(double startHeight, double stopHeight, double initialAngle, double finalAngle, double inclineAngle, double initialHorizontalSpeed, double finalHorizontalSpeed, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment with an incline at a given flight path angle.
static StandardTransitionProfileSegment	getSegmentAtAngleWithoutFinalHeight(double startHeight, double initialAngle, double finalAngle, double inclineAngle, double initialHorizontalSpeed, double finalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment with an incline at a given flight path angle.
static StandardTransitionProfileSegment	getSegmentAtAngleWithoutInitialHeight(double finalHeight, double initialAngle, double finalAngle, double inclineAngle, double initialHorizontalSpeed, double finalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment with an incline at a given flight path angle.
static StandardTransitionProfileSegment	getSegmentUsingSurfaceSpeed(double startHeight, double startRate, double stopHeight, double stopRate, double initialHorizontalSpeed, double finalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height along with the vehicle dynamics.
static StandardTransitionProfileSegment	getSegmentWithoutFinalConditions(double startHeight, double initialAngle, double finalAngle, double heightRate, double initialHorizontalSpeed, double targetFinalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment with an incline at a given flight path angle.
static StandardTransitionProfileSegment	getSegmentWithoutFinalConditions(double startHeight, double initialAngle, double heightRate, double initialHorizontalSpeed, double targetFinalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment with an incline at a given flight path angle.
static StandardTransitionProfileSegment	getSegmentWithPrescribedAcceleration(double startHeight, double startRate, double stopHeight, double stopRate, double initialHorizontalSpeed, double thrustAcceleration, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height and the thrust acceleration determines the final speed.
static StandardTransitionProfileSegment	getSegmentWithPrescribedAcceleration(double startHeight, double startRate, double stopHeight, double initialHorizontalSpeed, double thrustAcceleration, double surfaceDistance, TerrainProvider heightReference, ProfileDynamics dynamics) Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height and the thrust acceleration determines the final speed.
static StandardTransitionProfileSegment	getStraightSegment(double startHeight, double stopHeight, double initialHorizontalSpeed, double targetFinalHorizontalSpeed, double maxThrustAcceleration, double surfaceDistance, TerrainProvider heightReference) Creates a straight line from the initial height to the final height without any pitching maneuvers, with the additional constraint that the thrust acceleration along the slope can't exceed a specified value.
static StandardTransitionProfileSegment	getStraightSegment(double startHeight, double stopHeight, double initialHorizontalSpeed, double finalHorizontalSpeed, double surfaceDistance, TerrainProvider heightReference) Creates a straight line from the initial height to the final height without any pitching maneuvers.
static StandardTransitionProfileSegment	getStraightSegmentWithPrescribedAcceleration(double startHeight, double stopHeight, double initialHorizontalSpeed, double acceleration, double surfaceDistance, TerrainProvider heightReference) Creates a straight line from the initial height to the final height without any pitching maneuvers but also applies the acceleration to determine the final speed.
double	getSurfaceMotion(Duration time) Get the value for the arc length along the surface path, in meters.
Motion1<Double>	getSurfaceMotion(Duration time, int order) Get the value for the arc length and its derivatives along the surface path, in meters and seconds.
double	getTotalDistance() Gets the total horizontal distance traverse by the profile segment, in meters.
Duration	getTotalDuration() Gets the total time it takes for the segment to complete the transition from the initial conditions through an ascent or descent maneuver and then to connect with the final conditions.
Duration	getTotalTime() Gets the total time elapsed over the course of this segment.
Duration	getTotalTime(double arcLength) Get the time required to travel the specified arc length.
static boolean	isValidIncline(double startHeight, double startRate, double stopHeight, double stopRate, double startHorizontalSpeed, double stopHorizontalSpeed, double surfaceDistance, ProfileDynamics dynamics) Checks to see whether the given incline is feasible without violating the boundary conditions and dynamics.

Methods inherited from class agi.foundation.routedesign.advanced.ProfileSegment

checkForSameDefinition, isSameDefinition

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, enumerateDependencies, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

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

Method Detail

isValidIncline

public static boolean isValidIncline(double startHeight,
                                     double startRate,
                                     double stopHeight,
                                     double stopRate,
                                     double startHorizontalSpeed,
                                     double stopHorizontalSpeed,
                                     double surfaceDistance,
                                     ProfileDynamics dynamics)

Checks to see whether the given incline is feasible without violating the boundary conditions and dynamics.

Parameters:

startHeight - The initial height, in meters.

startRate - The initial vertical velocity, in meters per second.

stopHeight - The final height, in meters.

stopRate - The final vertical velocity, in meters per second.

startHorizontalSpeed - The initial horizontal velocity, in meters per second.

stopHorizontalSpeed - The final horizontal velocity, in meters per second.

surfaceDistance - The total horizontal distance along the surface path, in meters.

dynamics - The dynamical properties along the profile, including the vertical acceleration values, the maximum and minimum values for the ascent and descent rates, and the thrust acceleration and deceleration.

Returns:

True if the resulting incline is feasible for the given conditions.

getSegmentAtAngle

public static StandardTransitionProfileSegment getSegmentAtAngle(double startHeight,
                                                                 double stopHeight,
                                                                 double initialAngle,
                                                                 double finalAngle,
                                                                 double inclineAngle,
                                                                 double initialHorizontalSpeed,
                                                                 double finalHorizontalSpeed,
                                                                 TerrainProvider heightReference,
                                                                 ProfileDynamics dynamics)

Creates an inclined profile segment with an incline at a given flight path angle. The total distance is unspecified.

Parameters:

startHeight - The initial height, in meters.

stopHeight - The final height, in meters.

initialAngle - The initial flight path angle, in radians.

finalAngle - The final flight path angle, in radians.

inclineAngle - The flight path angle along the incline, in radians.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

finalHorizontalSpeed - The final horizontal velocity, in meters per second.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline at the specified flight path angle.

getSegmentAtAngleWithoutFinalHeight

@Nullable
public static StandardTransitionProfileSegment getSegmentAtAngleWithoutFinalHeight(double startHeight,
                                                                                              double initialAngle,
                                                                                              double finalAngle,
                                                                                              double inclineAngle,
                                                                                              double initialHorizontalSpeed,
                                                                                              double finalHorizontalSpeed,
                                                                                              double surfaceDistance,
                                                                                              TerrainProvider heightReference,
                                                                                              ProfileDynamics dynamics)

Creates an inclined profile segment with an incline at a given flight path angle. The final height is unspecified.

Parameters:

startHeight - The initial height, in meters.

initialAngle - The initial flight path angle, in radians.

finalAngle - The final flight path angle, in radians.

inclineAngle - The flight path angle along the incline, in radians.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

finalHorizontalSpeed - The final horizontal velocity, in meters per second.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline at the specified flight path angle.

getSegmentAtAngleWithoutInitialHeight

@Nullable
public static StandardTransitionProfileSegment getSegmentAtAngleWithoutInitialHeight(double finalHeight,
                                                                                                double initialAngle,
                                                                                                double finalAngle,
                                                                                                double inclineAngle,
                                                                                                double initialHorizontalSpeed,
                                                                                                double finalHorizontalSpeed,
                                                                                                double surfaceDistance,
                                                                                                TerrainProvider heightReference,
                                                                                                ProfileDynamics dynamics)

Creates an inclined profile segment with an incline at a given flight path angle. The initial height is unspecified.

Parameters:

finalHeight - The final height, in meters.

initialAngle - The initial flight path angle, in radians.

finalAngle - The final flight path angle, in radians.

inclineAngle - The flight path angle along the incline, in radians.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

finalHorizontalSpeed - The final horizontal velocity, in meters per second.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline at the specified flight path angle.

getSegmentWithoutFinalConditions

@Nullable
public static StandardTransitionProfileSegment getSegmentWithoutFinalConditions(double startHeight,
                                                                                           double initialAngle,
                                                                                           double heightRate,
                                                                                           double initialHorizontalSpeed,
                                                                                           double targetFinalHorizontalSpeed,
                                                                                           double surfaceDistance,
                                                                                           TerrainProvider heightReference,
                                                                                           ProfileDynamics dynamics)

Creates an inclined profile segment with an incline at a given flight path angle. The final height and final speed are unspecified. The intermediate incline angle is determined such that the intermediate rate of change of height is at or below the specified heightRate. There is no final pitch maneuver so the final angle is the same as the intermediate angle.

Parameters:

startHeight - The initial height, in meters.

initialAngle - The initial flight path angle, in radians.

heightRate - The intermediate rate of change of the height, in meters per second.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

targetFinalHorizontalSpeed - The target final horizontal velocity, in meters per second. This determines whether to accelerate or decelerate during the segment.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline with the specified characteristics.

getSegmentWithoutFinalConditions

@Nullable
public static StandardTransitionProfileSegment getSegmentWithoutFinalConditions(double startHeight,
                                                                                           double initialAngle,
                                                                                           double finalAngle,
                                                                                           double heightRate,
                                                                                           double initialHorizontalSpeed,
                                                                                           double targetFinalHorizontalSpeed,
                                                                                           double surfaceDistance,
                                                                                           TerrainProvider heightReference,
                                                                                           ProfileDynamics dynamics)

Creates an inclined profile segment with an incline at a given flight path angle. The final height and final speed are unspecified. The intermediate incline angle is determined such that the intermediate rate of change of height is at or below the specified heightRate.

Parameters:

startHeight - The initial height, in meters.

initialAngle - The initial flight path angle, in radians.

finalAngle - The final flight path angle, in radians.

heightRate - The intermediate rate of change of the height, in meters per second.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

targetFinalHorizontalSpeed - The target final horizontal velocity, in meters per second. This determines whether to accelerate or decelerate during the segment.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline with the specified characteristics.

getSegmentUsingSurfaceSpeed

public static StandardTransitionProfileSegment getSegmentUsingSurfaceSpeed(double startHeight,
                                                                           double startRate,
                                                                           double stopHeight,
                                                                           double stopRate,
                                                                           double initialHorizontalSpeed,
                                                                           double finalHorizontalSpeed,
                                                                           double surfaceDistance,
                                                                           TerrainProvider heightReference,
                                                                           ProfileDynamics dynamics)

Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height along with the vehicle dynamics.

Parameters:

startHeight - The initial height, in meters.

startRate - The initial vertical velocity, in meters per second.

stopHeight - The final height, in meters.

stopRate - The final vertical velocity, in meters per second.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

finalHorizontalSpeed - The final horizontal velocity, in meters per second.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values and the thrust acceleration and deceleration.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline matching the given conditions.

getSegmentWithPrescribedAcceleration

public static StandardTransitionProfileSegment getSegmentWithPrescribedAcceleration(double startHeight,
                                                                                    double startRate,
                                                                                    double stopHeight,
                                                                                    double stopRate,
                                                                                    double initialHorizontalSpeed,
                                                                                    double thrustAcceleration,
                                                                                    double surfaceDistance,
                                                                                    TerrainProvider heightReference,
                                                                                    ProfileDynamics dynamics)

Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height and the thrust acceleration determines the final speed.

Parameters:

startHeight - The initial height, in meters.

startRate - The initial vertical velocity, in meters per second.

stopHeight - The final height, in meters.

stopRate - The final vertical velocity, in meters per second.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

thrustAcceleration - The acceleration along the flight path angle, in meters per second squared.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values. The acceleration and deceleration specified here are overridden by the specified thrustAcceleration in this case.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline matching the given conditions.

getSegmentWithPrescribedAcceleration

public static StandardTransitionProfileSegment getSegmentWithPrescribedAcceleration(double startHeight,
                                                                                    double startRate,
                                                                                    double stopHeight,
                                                                                    double initialHorizontalSpeed,
                                                                                    double thrustAcceleration,
                                                                                    double surfaceDistance,
                                                                                    TerrainProvider heightReference,
                                                                                    ProfileDynamics dynamics)

Creates an inclined profile segment where the intermediate flight path angle is defined by the initial and final height and the thrust acceleration determines the final speed.

Parameters:

startHeight - The initial height, in meters.

startRate - The initial vertical velocity, in meters per second.

stopHeight - The final height, in meters.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

thrustAcceleration - The acceleration along the flight path angle, in meters per second squared.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

dynamics - The dynamical properties along the profile, including the vertical acceleration values. The acceleration and deceleration specified here are overridden by the specified thrustAcceleration in this case.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline matching the given conditions.

getStraightSegmentWithPrescribedAcceleration

@Nullable
public static StandardTransitionProfileSegment getStraightSegmentWithPrescribedAcceleration(double startHeight,
                                                                                                       double stopHeight,
                                                                                                       double initialHorizontalSpeed,
                                                                                                       double acceleration,
                                                                                                       double surfaceDistance,
                                                                                                       TerrainProvider heightReference)

Creates a straight line from the initial height to the final height without any pitching maneuvers but also applies the acceleration to determine the final speed.

Parameters:

startHeight - The initial height, in meters.

stopHeight - The final height, in meters.

initialHorizontalSpeed - The initial horizontal velocity, in meters per second.

acceleration - The acceleration along the flight path angle, in meters per second squared.

surfaceDistance - The total horizontal distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

Returns:

If the segment is infeasible, this returns null. Otherwise, it returns the incline matching the given conditions.

getStraightSegment

@Nullable
public static StandardTransitionProfileSegment getStraightSegment(double startHeight,
                                                                             double stopHeight,
                                                                             double initialHorizontalSpeed,
                                                                             double finalHorizontalSpeed,
                                                                             double surfaceDistance,
                                                                             TerrainProvider heightReference)

Creates a straight line from the initial height to the final height without any pitching maneuvers.

Parameters:

startHeight - The initial height, in meters.

stopHeight - The final height, in meters.

initialHorizontalSpeed - The initial horizontal speed, in meters per second.

finalHorizontalSpeed - The final horizontal speed, in meters per second.

surfaceDistance - The total distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

Returns:

The requested straight inclined segment.

getStraightSegment

@Nullable
public static StandardTransitionProfileSegment getStraightSegment(double startHeight,
                                                                             double stopHeight,
                                                                             double initialHorizontalSpeed,
                                                                             double targetFinalHorizontalSpeed,
                                                                             double maxThrustAcceleration,
                                                                             double surfaceDistance,
                                                                             TerrainProvider heightReference)

Creates a straight line from the initial height to the final height without any pitching maneuvers, with the additional constraint that the thrust acceleration along the slope can't exceed a specified value.

Parameters:

startHeight - The initial height, in meters.

stopHeight - The final height, in meters.

initialHorizontalSpeed - The initial horizontal speed, in meters per second.

targetFinalHorizontalSpeed - The final horizontal speed, in meters per second.

maxThrustAcceleration - The maximum thrust acceleration along the slope, in meters per second squared.

surfaceDistance - The total distance along the surface, in meters.

heightReference - The reference surface above which to define the height.

Returns:

The requested straight inclined segment.

getDegenerateSegment

@Nonnull
public static StandardTransitionProfileSegment getDegenerateSegment(double height,
                                                                              double heightRate,
                                                                              double horizontalSpeed,
                                                                              TerrainProvider heightReference)

Creates a segment which represents an instantaneous height and height rate for degenerate surface geometry.

Parameters:

height - The height, in meters.

heightRate - The rate of change of the height, in meters per second.

horizontalSpeed - The horizontal speed, in meters per second.

heightReference - The reference surface above which to define the height.

Returns:

The requested degenerate segment.

getConstrainedInclinedSegment

public static StandardTransitionProfileSegment getConstrainedInclinedSegment(double h0,
                                                                             double hf,
                                                                             double a0,
                                                                             double af,
                                                                             double v0,
                                                                             double vf,
                                                                             double g0,
                                                                             double gf,
                                                                             double sf,
                                                                             TerrainProvider heightReference)

Get a segment without specifying the intermediate flight path angle.

Parameters:

h0 - The initial height, in meters.

hf - The final height, in meters.

a0 - The initial pitch acceleration, in meters per second squared.

af - The final pitch acceleration, in meters per second squared

v0 - The initial total speed, in meters per second.

vf - The final total speed, in meters per second.

g0 - The initial flight path angle, in radians.

gf - The final flight path angle, in radians.

sf - The total arc length along the surface, in meters.

heightReference - The reference surface above which to define the height.

Returns:

The inclined segment or null if the profile is infeasible.

clone

public Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Specified by:

clone in class DefinitionalObject

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

checkForSameDefinition

protected final boolean checkForSameDefinition(ProfileSegment other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class ProfileSegment

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the StandardTransitionProfileSegment.checkForSameDefinition(agi.foundation.routedesign.advanced.ProfileSegment) method.

Overrides:

computeCurrentDefinitionHashCode in class ProfileSegment

Returns:

The computed hash code.

getHeight

public double getHeight(@Nonnull
                        Duration time)

Get the value for the height above the TerrainProvider height reference specified by the StandardTransitionProfileSegment.getHeightReference(agi.foundation.time.Duration) method at the given time.

Overrides:

getHeight in class ProfileSegment

Parameters:

time - The time elapsed since the beginning of this segment.

Returns:

The height above the reference, in meters.

getHeight

@Nonnull
public Motion1<Double> getHeight(@Nonnull
                                           Duration time,
                                           int order)

Get the value for the height above the TerrainProvider height reference specified by the StandardTransitionProfileSegment.getHeightReference(agi.foundation.time.Duration) method at the given time.

Specified by:

getHeight in class ProfileSegment

Parameters:

time - The time elapsed since the beginning of this segment.

order - The requested order of the height where zero is the height and higher orders specify the number of derivatives. Depending on the type of profile and underlying geometry, the resulting order may not match the requested order.

Returns:

The height above the reference, in meters, and its derivatives.

getSurfaceMotion

public double getSurfaceMotion(@Nonnull
                               Duration time)

Get the value for the arc length along the surface path, in meters.

Overrides:

getSurfaceMotion in class ProfileSegment

Parameters:

time - The time elapsed since the beginning of this segment.

Returns:

The arc length along the surface path, in meters.

getSurfaceMotion

@Nonnull
public Motion1<Double> getSurfaceMotion(@Nonnull
                                                  Duration time,
                                                  int order)

Get the value for the arc length and its derivatives along the surface path, in meters and seconds.

Specified by:

getSurfaceMotion in class ProfileSegment

Parameters:

time - The time elapsed since the beginning of this segment.

order - The requested order of the arc length where zero is the arc length and higher orders specify the number of derivatives. Depending on the type of profile and underlying geometry, the resulting order may not match the requested order.

Returns:

The arc length along the surface, in meters, and its derivatives.

getTotalTime

@Nonnull
public Duration getTotalTime()

Gets the total time elapsed over the course of this segment.

Specified by:

getTotalTime in class ProfileSegment

getHeightReference

public TerrainProvider getHeightReference(@Nonnull
                                          Duration time)

Get the TerrainProvider height reference for the profile height at the given time.

Specified by:

getHeightReference in class ProfileSegment

Parameters:

time - The elapsed time since the beginning of this segment.

Returns:

The terrain reference surface above which the height is defined.

getTotalTime

@Nonnull
public Duration getTotalTime(double arcLength)

Get the time required to travel the specified arc length.

Specified by:

getTotalTime in class ProfileSegment

Parameters:

arcLength - The arc length to travel, in meters.

Returns:

The elapsed time at the specified point along the surface path.

getTotalDistance

public final double getTotalDistance()

Gets the total horizontal distance traverse by the profile segment, in meters.

getIntermediateInclineAngle

public final double getIntermediateInclineAngle()

Gets the intermediate flight path angle with respect to the corresponding reference surface, in radians.

getIntermediateVerticalRate

public final double getIntermediateVerticalRate()

Gets the vertical velocity during the climb or descent, in meters per second.

getMaximumIntermediateVerticalRate

public final double getMaximumIntermediateVerticalRate()

Gets the maximum rate of change of the height, in meters per second, when transitioning from one height to the next. If the IntermediateVerticalAcceleration (get) is zero, then this is the same as the IntermediateVerticalRate (get). Otherwise, the value depends on the acceleration and whether the segment is accelerating or decelerating.

getIntermediateHorizontalRate

public final double getIntermediateHorizontalRate()

Gets the horizontal velocity during the climb or descent, in meters per second.

getIntermediateVerticalAcceleration

public final double getIntermediateVerticalAcceleration()

Gets the vertical acceleration during the climb or descent measured positive along the direction of motion, in meters per second squared.

getIntermediateHorizontalAcceleration

public final double getIntermediateHorizontalAcceleration()

Gets the horizontal acceleration during the climb or descent measured positive along the direction of motion, in meters per second squared.

getIntermediateAccelerationAlongSlope

public final double getIntermediateAccelerationAlongSlope()

Gets the total acceleration along the climb or descent plane measured positive along the direction of motion, in meters per second squared.

getInitialDuration

@Nonnull
public final Duration getInitialDuration()

Gets the time it takes for the segment to transition from the initial conditions to the inclined slope.

getIntermediateDuration

@Nonnull
public final Duration getIntermediateDuration()

Gets the time it takes for the segment to transition along the inclined slope while ascending or descending.

getFinalDuration

@Nonnull
public final Duration getFinalDuration()

Gets the time it takes for the segment to transition from the inclined slope to the final conditions.

getTotalDuration

@Nonnull
public final Duration getTotalDuration()

Gets the total time it takes for the segment to complete the transition from the initial conditions through an ascent or descent maneuver and then to connect with the final conditions.

getInitialHeight

public final double getInitialHeight()

Gets the initial height above the reference surface, in meters.

getFinalHeight

public final double getFinalHeight()

Gets the final height above the reference surface, in meters.

getInitialHeightRate

public final double getInitialHeightRate()

Gets the initial vertical velocity, in meters per second.

getFinalHeightRate

public final double getFinalHeightRate()

Gets the final vertical velocity, in meters per second.

getInitialAngle

public final double getInitialAngle()

Gets the initial flight path angle with respect to the reference surface, in radians.

getFinalAngle

public final double getFinalAngle()

Gets the final flight path angle with respect to the reference surface, in radians.

getInitialSurfaceSpeed

public final double getInitialSurfaceSpeed()

Gets the value for the horizontal surface speed at the start of the profile, in meters per second.

getFinalSurfaceSpeed

public final double getFinalSurfaceSpeed()

Gets the value for the horizontal surface speed at the start of the profile, in meters per second.