agi.foundation.segmentpropagation

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

Class PropagateSegment

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.segmentpropagation.SegmentDefinition

agi.foundation.segmentpropagation.PropagateSegment

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

FollowSegment, HoldSegment, NumericalPropagatorSegment

public class PropagateSegment
extends SegmentDefinition

A segment that will run a StoppablePropagator until a StoppingCondition is satisfied. Each StoppingCondition in the StoppingConditions (get) can have an optional SegmentDefinition associated with it that get propagated if that StoppingCondition is the one that stops the propagation of this segment's propagator.

Consider deriving from this type when the specific StoppablePropagatorDefinition can be used to handle the configuration of the StateElementAdapters or other book-keeping needed for the segment. Note that although the derived definition can limit what type of StoppablePropagatorDefinition is used, you should still use the SegmentPropagator that the PropagateSegment creates.

The results returned when this segments propagator is propagated will always be a PropagateSegmentResults.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PropagateSegment(PropagateSegment existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
	PropagateSegment(StoppablePropagatorDefinition stoppablePropagator) Initializes a new instance with a StoppablePropagator.

Method Summary

Modifier and Type	Method and Description
void	addPropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value) An event that gets raised when propagation is complete.
void	addStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value) An event that will be raised every time a step is taken by the underlying StoppablePropagator.
protected boolean	checkForSameDefinition(PropagateSegment other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected boolean	checkForSameDefinition(SegmentDefinition other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
boolean	clearStoppingConditionsAutoSegment(StoppingCondition stoppingCondition) Removes the optional segment that would have been run if the specified StoppingCondition would stop propagation.
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.
protected SegmentPropagator	createSegmentPropagator(EvaluatorGroup group, SegmentDefinition previousSegment) Creates, configures, and returns the SegmentPropagator for this segment.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
protected void	freezeAggregatedObjects() Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
protected boolean	getAllowZeroElements() Gets a value indicating whether if it is acceptable for this type of PropagateSegment to have no elements.
Duration	getMaximumDuration() Gets the maximum Duration that this segment may propagate before being stopped.
int	getNumberOfTimesToExecuteStoppingConditionsAutoSegment(StoppingCondition stoppingCondition) Returns the number of times the auto-segment associated with the stoppingCondition is set to execute.
int	getOutputSparsity() Gets the interval at which to produce output samples.
MaximumDurationBehavior	getStopOnMaximumDurationBehavior() Gets what should be done if the span of propagation exceeds the MaximumDuration (get / set).
StoppablePropagatorDefinition	getStoppablePropagator() Gets the StoppablePropagatorDefinition that will be propagated by this segment.
List<StoppingCondition>	getStoppingConditions() Gets the stopping conditions that may stop this segment.
SegmentDefinition	getStoppingConditionsAutoSegment(StoppingCondition stoppingCondition) Returns the SegmentDefinition that is set to be run if the specified stoppingCondition stops propagation, or null if there has not been such a segment specified.
void	removePropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value) An event that gets raised when propagation is complete.
void	removeStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value) An event that will be raised every time a step is taken by the underlying StoppablePropagator.
void	setMaximumDuration(Duration value) Sets the maximum Duration that this segment may propagate before being stopped.
void	setOutputSparsity(int value) Sets the interval at which to produce output samples.
void	setStopOnMaximumDurationBehavior(MaximumDurationBehavior value) Sets what should be done if the span of propagation exceeds the MaximumDuration (get / set).
protected void	setStoppablePropagator(StoppablePropagatorDefinition value) Sets the StoppablePropagatorDefinition that will be propagated by this segment.
void	setStoppingConditionAutoSegment(StoppingCondition stoppingCondition, SegmentDefinition autoSegment, int numberOfTimesToExecuteAutoSequence) Each StoppingCondition in the StoppingConditions (get) can have a SegmentDefinition associated with it that will be propagated if that StoppingCondition happens to be the one that stops this segments propagation.

Methods inherited from class agi.foundation.segmentpropagation.SegmentDefinition

checkForSameDefinition, containsElement, getDefinedIn, getElementAdapter, getElements, getName, getNextStateBehavior, getPassAllElementsToNextSegment, getPropagationDirection, getSegmentPropagator, getSegmentPropagator, getSegmentPropagator, getSegmentPropagator, removeElement, setElementAndAdapter, setName, setNextStateBehavior, setPropagationDirection, toString

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, 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

PropagateSegment

public PropagateSegment(StoppablePropagatorDefinition stoppablePropagator)

Initializes a new instance with a StoppablePropagator.

Parameters:

stoppablePropagator - The StoppablePropagator that will be propagated by this segment. Note that this segment will modify properties on this propagator, such as its adapters.

PropagateSegment

protected PropagateSegment(@Nonnull
                           PropagateSegment 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 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(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).

Specified by:

checkForSameDefinition in class SegmentDefinition

Parameters:

other - The other instance to compare to this one.

Returns:

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

checkForSameDefinition

protected boolean checkForSameDefinition(@Nullable
                                         PropagateSegment 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 PropagateSegment.checkForSameDefinition(agi.foundation.segmentpropagation.SegmentDefinition) method.

Overrides:

computeCurrentDefinitionHashCode in class SegmentDefinition

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

freezeAggregatedObjects

protected void freezeAggregatedObjects()

Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. Derived classes which contain additional aggregated objects MUST override this method, call the base implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be frozen in this method are frequently created in this object's constructor and are not settable via properties.

Overrides:

freezeAggregatedObjects in class DefinitionalObject

getStoppablePropagator

public final StoppablePropagatorDefinition getStoppablePropagator()

Gets the StoppablePropagatorDefinition that will be propagated by this segment. Note that the adapters on the StoppablePropagatorDefinition will be automatically set by this segment. Segments that derived from PropagateSegment may set this, but it is often easier to expose the relevant properties on this than to expose it directly.

setStoppablePropagator

protected final void setStoppablePropagator(StoppablePropagatorDefinition value)

Sets the StoppablePropagatorDefinition that will be propagated by this segment. Note that the adapters on the StoppablePropagatorDefinition will be automatically set by this segment. Segments that derived from PropagateSegment may set this, but it is often easier to expose the relevant properties on this than to expose it directly.

addPropagationFinishedEvent

public void addPropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value)

An event that gets raised when propagation is complete.

Specified by:

addPropagationFinishedEvent in class SegmentDefinition

removePropagationFinishedEvent

public void removePropagationFinishedEvent(EventHandler<SegmentPropagationEventArgs> value)

An event that gets raised when propagation is complete.

Specified by:

removePropagationFinishedEvent in class SegmentDefinition

addStepTaken

public final void addStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value)

An event that will be raised every time a step is taken by the underlying StoppablePropagator.

removeStepTaken

public final void removeStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value)

An event that will be raised every time a step is taken by the underlying StoppablePropagator.

getStoppingConditions

public final List<StoppingCondition> getStoppingConditions()

Gets the stopping conditions that may stop this segment. Only one StoppingCondition needs to be satisfied to stop propagation. If by the very rare chance that two conditions happens to stop at the exact same time, the one earlier in this list will be the one that was reported to have stopped propagation. Note that this property returns the StoppingConditions (get) on the StoppablePropagator (get / set). This will be null until the StoppablePropagator (get / set) is initialized.

Note that these conditions will not affect any of the segments being used as a segment that gets executed with a particular stopping condition is tripped. So, while propagating such a segment, none of these StoppingConditions (get) will be used.

getMaximumDuration

@Nonnull
public final Duration getMaximumDuration()

Gets the maximum Duration that this segment may propagate before being stopped. The sign of this Duration will be changed at configuration time to match this segments PropagationDirection (get / set). By default this is set to 100 days.

This Duration will be used to create a StoppingCondition that will be fed to the actual StoppablePropagator being propagated. It will be in effect even if the actual propagator is changed by a ChangePropagateSegmentsPropagatorOperator.

setMaximumDuration

public final void setMaximumDuration(@Nonnull
                                     Duration value)

Sets the maximum Duration that this segment may propagate before being stopped. The sign of this Duration will be changed at configuration time to match this segments PropagationDirection (get / set). By default this is set to 100 days.

This Duration will be used to create a StoppingCondition that will be fed to the actual StoppablePropagator being propagated. It will be in effect even if the actual propagator is changed by a ChangePropagateSegmentsPropagatorOperator.

getStopOnMaximumDurationBehavior

@Nonnull
public final MaximumDurationBehavior getStopOnMaximumDurationBehavior()

Gets what should be done if the span of propagation exceeds the MaximumDuration (get / set). By default this will stop all propagation and immediately return the results computed up to this point.

setStopOnMaximumDurationBehavior

public final void setStopOnMaximumDurationBehavior(@Nonnull
                                                   MaximumDurationBehavior value)

Sets what should be done if the span of propagation exceeds the MaximumDuration (get / set). By default this will stop all propagation and immediately return the results computed up to this point.

getAllowZeroElements

protected boolean getAllowZeroElements()

Gets a value indicating whether if it is acceptable for this type of PropagateSegment to have no elements. By default this is false.

createSegmentPropagator

protected SegmentPropagator createSegmentPropagator(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.

Specified by:

createSegmentPropagator in class SegmentDefinition

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.

setStoppingConditionAutoSegment

public final void setStoppingConditionAutoSegment(@Nonnull
                                                  StoppingCondition stoppingCondition,
                                                  @Nonnull
                                                  SegmentDefinition autoSegment,
                                                  int numberOfTimesToExecuteAutoSequence)

Each StoppingCondition in the StoppingConditions (get) can have a SegmentDefinition associated with it that will be propagated if that StoppingCondition happens to be the one that stops this segments propagation. Use this method to set that optional segment.

Parameters:

stoppingCondition - The StoppingCondition that if tripped will trigger the autoSegment to propagate. The stoppingCondition must be in the StoppingConditions (get) when this segments propagator is created.

autoSegment - The segment to run if the stoppingCondition stops propagation.

numberOfTimesToExecuteAutoSequence - Sets the number of times the autoSegment will get executed. When set to more than 1, after the StoppablePropagator (get / set) is stopped by the stoppingCondition, the autoSegment will be propagated. Once that segment finishes, the StoppingConditionEvaluator that stopped the in initial propagation will be reinitialized and the propagation of the StoppablePropagator (get / set) will continue as many times as this value is specified.

Throws:

ArgumentOutOfRangeException - Thrown when the numberOfTimesToExecuteAutoSequence is less than 1.

getStoppingConditionsAutoSegment

@Nullable
public final SegmentDefinition getStoppingConditionsAutoSegment(StoppingCondition stoppingCondition)

Returns the SegmentDefinition that is set to be run if the specified stoppingCondition stops propagation, or null if there has not been such a segment specified.

Parameters:

stoppingCondition - The condition whose segment you want to retrieve.

Returns:

The SegmentDefinition that is set to be run if the specified stoppingCondition stops propagation, or null if there has not been such a segment specified.

getNumberOfTimesToExecuteStoppingConditionsAutoSegment

public final int getNumberOfTimesToExecuteStoppingConditionsAutoSegment(StoppingCondition stoppingCondition)

Returns the number of times the auto-segment associated with the stoppingCondition is set to execute. If the stoppingCondition does not have a SegmentDefinition associated with it, then 1 will be returned.

Parameters:

stoppingCondition - The condition whose segment you want to retrieve.

Returns:

The number of times the associated auto-segment will be executed, or 1 if there is no associated auto-segment.

clearStoppingConditionsAutoSegment

public final boolean clearStoppingConditionsAutoSegment(StoppingCondition stoppingCondition)

Removes the optional segment that would have been run if the specified StoppingCondition would stop propagation. This method will return false if the stoppingCondition has no optional segment.

Parameters:

stoppingCondition - The StoppingCondition whose associated segment should be cleared.

Returns:

true if the segment was removed successfully. false if there was no segment to remove or if a problem was encountered.

getOutputSparsity

public final int getOutputSparsity()

Gets the interval at which to produce output samples. By default this is set to one, meaning that output will be saved in the state history for every integration step. If a thinner (but less accurate) ephemeris is desired you can set this to a higher number. Two means that output is saved every other integration step, etc, etc.

setOutputSparsity

public final void setOutputSparsity(int value)

Sets the interval at which to produce output samples. By default this is set to one, meaning that output will be saved in the state history for every integration step. If a thinner (but less accurate) ephemeris is desired you can set this to a higher number. Two means that output is saved every other integration step, etc, etc.