agi.foundation.segmentpropagation

(agi.foundation.models-2024r2.jar)

Class SegmentDefinition

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.segmentpropagation.SegmentDefinition

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

BasicLaunchSegment, ImpulsiveManeuverSegment, InitialStateSegment, PropagateSegment, ReturnSegment, SegmentList, StopSegment, SwitchableSegment, UpdateSegment

public abstract class SegmentDefinition
extends DefinitionalObject

The base class for segments used with the Segment Propagation Library. These segments define how an ITimeBasedState will be propagated. The initial state will be passed into the propagator's PropagateSegment method. Multiple segments can be linked together in a simple sequential manner, or in a more complex manner dictated by the control flow segments. When linked together the state elements are fed in to the next logical segment via the manner described in the property, StateForNextSegmentBehavior.

When designing custom segments, the segment should support being the first segment in a sequence, if it makes logical and physical sense. If it does not, then a detailed RuntimeException should be thrown when SegmentDefinition.getSegmentPropagator() is called and no previous segment is included.

Custom segments should have a corresponding custom configuration type that goes along with it. This configuration object will store mutable values that the segment propagation system could modify. The configuration object does not need to have every single property of the segment; only the ones that are required during propagation.

See the Segments topic in the documentation for more detail.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SegmentDefinition() Initializes a new instance.
protected	SegmentDefinition(SegmentDefinition existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
abstract void	addPropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value) An event that gets raised when propagation is complete.
protected boolean	checkForSameDefinition(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(SegmentDefinition other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
boolean	containsElement(String element) Checks to see if there is a StateElementAdapterDefinition for the provided element.
protected abstract SegmentPropagator	createSegmentPropagator(EvaluatorGroup group, SegmentDefinition previousSegment) Creates, configures, and returns the SegmentPropagator for this segment.
Object	getDefinedIn(String element) Gets the object (for example, a ReferenceFrame, an Axes, etc.) in which the specified element is defined in.
StateElementAdapterDefinition	getElementAdapter(String element) Returns the adapter for the given state element.
List<String>	getElements() Gets the names of all of the elements that this segment is propagating.
String	getName() Gets a name to describe the segment.
StateForNextSegmentBehavior	getNextStateBehavior() Gets the behavior for passing states to the next segment.
boolean	getPassAllElementsToNextSegment() Gets a value indicating whether the segment is such that it will not define any Elements (get) or StateElementAdapters.
IntegrationSense	getPropagationDirection() Gets the direction that this segment will be initially propagated.
SegmentPropagator	getSegmentPropagator() Creates, configures, and returns the SegmentPropagator for this segment.
SegmentPropagator	getSegmentPropagator(EvaluatorGroup group) Creates, configures, and returns the SegmentPropagator for this segment.
SegmentPropagator	getSegmentPropagator(EvaluatorGroup group, SegmentDefinition previousSegment) Creates, configures, and returns the SegmentPropagator for this segment.
SegmentPropagator	getSegmentPropagator(SegmentDefinition previousSegment) Creates, configures, and returns the SegmentPropagator for this segment.
boolean	removeElement(String element) Removes the StateElementAdapterDefinition for the specified element.
abstract void	removePropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value) An event that gets raised when propagation is complete.
boolean	setElementAndAdapter(StateElementAdapterDefinition adapter) Add or sets an adapter for an element in this segment.
void	setName(String value) Sets a name to describe the segment.
void	setNextStateBehavior(StateForNextSegmentBehavior value) Sets the behavior for passing states to the next segment.
void	setPropagationDirection(IntegrationSense value) Sets the direction that this segment will be initially propagated.
String	toString() Returns a string representation of the object.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, 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, wait, wait, wait

Constructor Detail

SegmentDefinition

protected SegmentDefinition()

Initializes a new instance.

SegmentDefinition

protected SegmentDefinition(@Nonnull
                            SegmentDefinition existingInstance,
                            @Nonnull
                            CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

checkForSameDefinition

protected final boolean checkForSameDefinition(DefinitionalObject 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 DefinitionalObject

Parameters:

other - The other instance to compare to this one.

Returns:

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

checkForSameDefinition

protected abstract boolean checkForSameDefinition(SegmentDefinition 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).

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 SegmentDefinition.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

getElementAdapter

@Nullable
public StateElementAdapterDefinition getElementAdapter(String element)

Returns the adapter for the given state element. The StateElementAdapters handle the various transformations of the propagated elements between segments (for example, if the integration frame of a point being propagated changes from one segment to another, the adapter is what handles that transformation between segment). All elements propagated by this segment must have an adapter returned by this method (even if that adapter simply returns the original state). If multiple segments are being propagated by this segment (as a SegmentList would), this must return the adapter of the StateElementAdapter of the element for the final known segment getting propagated.

In general, the concrete SegmentDefinition should have a list of the adapter factory instances that are valid for this segment, and then this method would get the element definition object from this segments configuration.

Parameters:

element - The element whose StateElementAdapter is needed.

Returns:

The adapter with the element defined-in set, or null if there is no such factory.

toString

public String toString()

Description copied from class: java.lang.Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:

toString in class Object

Returns:

a string representation of the object.

getDefinedIn

public Object getDefinedIn(String element)

Gets the object (for example, a ReferenceFrame, an Axes, etc.) in which the specified element is defined in. This can return null if there is no such object. When overriding this method, you generally should not call the base method, instead the derived segment should keep track of the elements and defined in objects itself.

Parameters:

element - The identification of the element.

Returns:

The defined in object for the element.

containsElement

public final boolean containsElement(@Nonnull
                                     String element)

Checks to see if there is a StateElementAdapterDefinition for the provided element.

Parameters:

element - The state element of interest.

Returns:

true if the element has an associated StateElementAdapterDefinition registered with this segment; otherwise false.

Throws:

ArgumentNullException - Thrown when element is null.

removeElement

public final boolean removeElement(@Nonnull
                                   String element)

Removes the StateElementAdapterDefinition for the specified element.

Parameters:

element - The propagation element to attempt to remove.

Returns:

true if the element was successfully removed; otherwise false.

Throws:

ArgumentNullException - Thrown when element is null.

setElementAndAdapter

public boolean setElementAndAdapter(@Nonnull
                                    StateElementAdapterDefinition adapter)

Add or sets an adapter for an element in this segment.

Note that many types of derived segments will automatically handle their adapters by interrogating properties specific to the derived segment. Also some segments whose PassAllElementsToNextSegment (get) property is true do not require adapters or elements to be set.

These adapters have the responsibility of processing the initial state that the propagator will start propagating from. They will modify the initial state passed to this segment so that the state is in a form that the propagator can process.

Parameters:

adapter - An instance of the factory that makes the adapter. This must be configured with the current defined in object (if appropriate) and with the element identification.

Returns:

true if the element was added or set successfully; otherwise false. false does not indicate an error; it means that this segment does not need elements and adapters explicitly set.

getSegmentPropagator

@Nonnull
public final SegmentPropagator getSegmentPropagator()

Creates, configures, and returns the SegmentPropagator for this segment. This method assumes that no previous segment is needed to configure this segment's propagator.

Returns:

The propagator for this segment.

getSegmentPropagator

@Nonnull
public final SegmentPropagator getSegmentPropagator(@Nonnull
                                                              EvaluatorGroup group)

Creates, configures, and returns the SegmentPropagator for this segment. This method assumes that no previous segment is needed to configure this segment's propagator.

Parameters:

group - The group to use during creation.

Returns:

The propagator for this segment.

getSegmentPropagator

@Nonnull
public final SegmentPropagator getSegmentPropagator(SegmentDefinition previousSegment)

Creates, configures, and returns the SegmentPropagator for this segment.

Parameters:

previousSegment - The previous segment. Some segments require that the previous segment not be null, whereas others will only use information from it if provided.

Returns:

The propagator for this segment.

getSegmentPropagator

@Nonnull
public final SegmentPropagator getSegmentPropagator(@Nonnull
                                                              EvaluatorGroup group,
                                                              SegmentDefinition previousSegment)

Creates, configures, and returns the SegmentPropagator for this segment.

Parameters:

group - The group to use during creation.

previousSegment - The previous segment. Some segments require that the previous segment not be null, whereas others will only use information from it if provided.

Returns:

The propagator for this segment.

createSegmentPropagator

@Nonnull
protected abstract SegmentPropagator createSegmentPropagator(@Nonnull
                                                                       EvaluatorGroup group,
                                                                       SegmentDefinition previousSegment)

Creates, configures, and returns the SegmentPropagator for this segment. This method should check that all of the required properties on the concrete instance are configured properly before constructing the SegmentPropagator to be returned.

Parameters:

group - The group to use during creation.

previousSegment - The previous segment. Some segments will require the previousSegment to be set, whereas other will require that the previous segment not be null, whereas others will only use information from it if provided. It is up to you writing a concrete type to enforce what makes sense for your particular segment in this method.

Returns:

The propagator for this segment.

getElements

public List<String> getElements()

Gets the names of all of the elements that this segment is propagating.

Unless the logic of a derived segment requires it, there is no requirement that the same elements get propagated from segment to segment (for example, you can propagate a satellite and the booster that got it into orbit. When the booster reenters the atmosphere, you do not have to keep that element around in later segments). However values that you want to be propagated from segment to segment must have the same name (continuing the example, the name of the satellite getting propagated needs to be consistent from segment to segment).

getName

public final String getName()

Gets a name to describe the segment. This is optional.

setName

public final void setName(String value)

Sets a name to describe the segment. This is optional.

getPropagationDirection

@Nonnull
public final IntegrationSense getPropagationDirection()

Gets the direction that this segment will be initially propagated. If this segment propagates multiple segments, the child segments will be propagated in the direction that they are configured with. If the overall list is going forward, segments that go back in time will override the immediate previous segments ephemeris, but if another segment going forward follows the backwards segment, that backwards segment will be ignored when the overall trajectory is resolved into a single ephemeris set. If you are using a StoppingCondition that depends on time, the time span of those stopping conditions must match this property (for example, a DurationStoppingCondition must have a negative threshold if this is set to IntegrationSense.DECREASING, otherwise, the condition will never be tripped).

setPropagationDirection

public final void setPropagationDirection(@Nonnull
                                          IntegrationSense value)

Sets the direction that this segment will be initially propagated. If this segment propagates multiple segments, the child segments will be propagated in the direction that they are configured with. If the overall list is going forward, segments that go back in time will override the immediate previous segments ephemeris, but if another segment going forward follows the backwards segment, that backwards segment will be ignored when the overall trajectory is resolved into a single ephemeris set. If you are using a StoppingCondition that depends on time, the time span of those stopping conditions must match this property (for example, a DurationStoppingCondition must have a negative threshold if this is set to IntegrationSense.DECREASING, otherwise, the condition will never be tripped).

addPropagationFinishedEvent

public abstract void addPropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value)

An event that gets raised when propagation is complete.

removePropagationFinishedEvent

public abstract void removePropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value)

An event that gets raised when propagation is complete.

getPassAllElementsToNextSegment

public boolean getPassAllElementsToNextSegment()

Gets a value indicating whether the segment is such that it will not define any Elements (get) or StateElementAdapters. Such a segment typically affects the control flow of multiple segments instead of propagating state elements. By default this is false, but if the specific derived segment can use the previous segment's adapters, override this property to always return true. Even if this is true some segments may require adapters to be set with the SegmentDefinition.setElementAndAdapter(agi.foundation.coordinates.StateElementAdapterDefinition) method.

getNextStateBehavior

@Nonnull
public final StateForNextSegmentBehavior getNextStateBehavior()

Gets the behavior for passing states to the next segment. See StateForNextSegmentBehavior for more information.

setNextStateBehavior

public final void setNextStateBehavior(@Nonnull
                                       StateForNextSegmentBehavior value)

Sets the behavior for passing states to the next segment. See StateForNextSegmentBehavior for more information.