agi.foundation.segmentpropagation

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

Class SegmentListPropagator

java.lang.Object

agi.foundation.segmentpropagation.SegmentPropagator

agi.foundation.segmentpropagation.SegmentListPropagator

All Implemented Interfaces:

IDisposable, ICloneWithContext, IThreadAware, AutoCloseable

public class SegmentListPropagator
extends SegmentPropagator

The SegmentPropagator for SegmentList. Each SegmentPropagator in the list will be propagated sequentially and a SegmentListResults will be returned. Note that there are several virtual methods on this type that must be overridden if you are extending this type.

Constructor Summary

Constructors

Modifier	Constructor and Description
	SegmentListPropagator(SegmentDefinition previousSegment, SegmentList segmentDefinition, EvaluatorGroup group) Initializes a new instance.
protected	SegmentListPropagator(SegmentListPropagator existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
void	applyResults(SegmentResults results) This method sets propagator's state via the input results.
Object	clone(CopyContext context) Clones this object using the specified context.
protected SegmentListConfiguration	createNewConfiguration() Creates a new configuration for this segment.
List<SegmentPropagator>	getSegments() Gets the SegmentPropagators that will be propagated.
protected SegmentResults	propagateSegment(SegmentListResults cumulativeResults, SegmentConfiguration editedConfiguration, ITrackCalculationProgress progressTracker) The method that actually propagates the segment.
SegmentListResults	propagateSegmentList() Propagates the segments in this SegmentListPropagator.
SegmentListResults	propagateSegmentList(ITimeBasedState initialState) Propagates this starting from the initialState.
SegmentListResults	propagateSegmentList(SegmentListResults cumulativeResults, SegmentListConfiguration configuration, ITrackCalculationProgress progressTracker) Propagates this propagator's list of segments.
static void	propagateSegments(SegmentListResults cumulativeResults, List<SegmentPropagator> segmentsToPropagate, SegmentListConfiguration configuration, ITrackCalculationProgress progressTracker) Propagates a list of segments.
ITimeBasedState	propagateTo(SegmentResults results, JulianDate dateToPropagateTo) Propagates a segment to the time or independent variable specified in the dateToPropagateTo.

Methods inherited from class agi.foundation.segmentpropagation.SegmentPropagator

addPropagationFinishedEvent, defaultStateAdaptation, dispose, dispose, getAdapters, getIdentifier, getIsThreadSafe, getName, getOriginalConfiguration, getPropagationDirection, getStateForNextSegmentBehavior, propagate, propagate, propagate, propagate, propagate, propagate, propagate, removePropagationFinishedEvent, setOriginalConfiguration, toString, updateProgressTrackerAndReturnIfCanceled

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

SegmentListPropagator

public SegmentListPropagator(SegmentDefinition previousSegment,
                             @Nonnull
                             SegmentList segmentDefinition,
                             @Nonnull
                             EvaluatorGroup group)

Initializes a new instance.

Parameters:

previousSegment - The previous segment.

segmentDefinition - The SegmentList that is making this.

group - The EvaluatorGroup to use in making any evaluators needed by the segmentDefinition.

SegmentListPropagator

protected SegmentListPropagator(@Nonnull
                                SegmentListPropagator 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

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 SegmentPropagator

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

propagateSegments

public static void propagateSegments(SegmentListResults cumulativeResults,
                                     @Nonnull
                                     List<SegmentPropagator> segmentsToPropagate,
                                     SegmentListConfiguration configuration,
                                     @Nullable
                                     ITrackCalculationProgress progressTracker)

Propagates a list of segments. Instead of returning some set of SegmentListResults, this method will add the results to cumulativeResults.

Parameters:

cumulativeResults - The results of the SegmentListPropagator that is calling this static method. These results must have the ParentResults (get / set) and Propagator (get) set.

segmentsToPropagate - The SegmentPropagators that should be propagated.

configuration - The segment configuration that some other segment has determined that this segment should run. If it is null then the OriginalConfiguration (get / set) of the Propagator (get) of the cumulativeResults will be used.

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. But you can cancel propagation with the tracker.

propagateSegmentList

@Nonnull
public final SegmentListResults propagateSegmentList()

Propagates the segments in this SegmentListPropagator.

Returns:

The SegmentListResults of the propagation.

propagateSegmentList

@Nonnull
public SegmentListResults propagateSegmentList(ITimeBasedState initialState)

Propagates this starting from the initialState.

Parameters:

initialState - The state to propagation from.

Returns:

The SegmentListResults of this propagation.

propagateSegmentList

@Nonnull
public SegmentListResults propagateSegmentList(@Nullable
                                                         SegmentListResults cumulativeResults,
                                                         SegmentListConfiguration configuration,
                                                         @Nullable
                                                         ITrackCalculationProgress progressTracker)

Propagates this propagator's list of segments.

Parameters:

cumulativeResults - The overall results of propagation up to this point. This may be null if this segment is the top level segment.

configuration - The segment configuration that some other segment has determined that this segment should run. If it is null then the OriginalConfiguration (get / set) will be used.

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. A tracker is useful to cancel propagation if such an operation is desired.

Returns:

The SegmentListResults of this propagation.

propagateSegment

protected SegmentResults propagateSegment(SegmentListResults cumulativeResults,
                                          SegmentConfiguration editedConfiguration,
                                          ITrackCalculationProgress progressTracker)

The method that actually propagates the segment. This should never be called directly; instead call whatever SegmentPropagator.propagate() method most appropriate to your problem.

Specified by:

propagateSegment in class SegmentPropagator

Parameters:

cumulativeResults - The results of the SegmentListPropagator that contains this segment. This may be null if this segment is being propagated independent of a SegmentListPropagator. In the simple case, this is only needed to provide the StateForNextSegment (get) that this SegmentPropagator should start propagating from. However, if the concrete SegmentPropagator will propagate multiple segments, then the StateForNextSegment (get) must be set after each individual SegmentPropagator is propagated. You may also need to maintain the SegmentResults (get) collection to avoid having the same SegmentResults included twice (the SegmentResults for each SegmentPropagator gets added automatically to the cumulativeResults when it is propagated). Also, if there is even the possibility of the SegmentPropagator needing to back up into a previous segment, the SegmentListResults.regenerateEphemerisForOverallTrajectory() method after each child SegmentPropagator is propagated.

editedConfiguration - The segment configuration that some other segment has determined that this segment should run. If it is null then use the segments OriginalConfiguration (get / set).

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. However you can cancel propagation with the tracker.

Returns:

This segments propagation results. This method must fill in all of the relevant properties in the returned results. See the documentation of the derived type to determine if these SegmentResults may be cast to a more specific type.

propagateTo

public ITimeBasedState propagateTo(SegmentResults results,
                                   @Nonnull
                                   JulianDate dateToPropagateTo)

Propagates a segment to the time or independent variable specified in the dateToPropagateTo. This method is needed to assist the case when segments might overlap. If a later segment realizes that it needs to find a different final state from this SegmentPropagator, this method should be used to find that new final state.

Consider calling SegmentListResults.propagateToAssumingTimeBasedStates(agi.foundation.time.JulianDate, agi.foundation.segmentpropagation.SegmentResults, agi.foundation.segmentpropagation.SegmentListResults) instead of this method directly.

For segments that happen instantaneously then this should just return the state computed (although generally this method should never need to be called on such segments since there is no "when" to propagate to, you can pull the state from the results directly). For a segment that produces an ephemeris, this should find the state right before the offset's independent variable and take one step to that independent variable. If the segment returns two states at the same time, PropagationDirection (get) should be checked, and if propagation is IntegrationSense#INCREASING the final state should be returned, or the initial state if propagation is backwards.

Specified by:

propagateTo in class SegmentPropagator

Parameters:

results - The results previously computed by this SegmentPropagator. When used with a SegmentListPropagator, the results of the actual nested SegmentPropagator should be passed in.

dateToPropagateTo - The date of the returned state.

Returns:

The state at dateToPropagateTo.

applyResults

public void applyResults(SegmentResults results)

This method sets propagator's state via the input results. For SegmentPropagators that have state, there may be times when that state should be manually set (sometimes for performance considerations, when the propagator will be called multiple times and it should start from where it left off).

Overrides:

applyResults in class SegmentPropagator

Parameters:

results - The results to apply.

createNewConfiguration

@Nonnull
protected SegmentListConfiguration createNewConfiguration()

Creates a new configuration for this segment. Derived types should override this and return their configuration that inherits from SegmentListConfiguration.

Returns:

A new instance of the configuration for this segment.

getSegments

@Nonnull
public final List<SegmentPropagator> getSegments()

Gets the SegmentPropagators that will be propagated.