agi.foundation.propagators.advanced

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

Class PropagationStateCorrectionEvaluator

java.lang.Object

agi.foundation.propagators.advanced.PropagationStateCorrectionEvaluator

All Implemented Interfaces:

IDisposable, IEvaluator, ICloneWithContext, IThreadAware, IAvailability, AutoCloseable

public abstract class PropagationStateCorrectionEvaluator
extends Object
implements IEvaluator

Members of this class calculate corrections to a propagated state after the integration step.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
abstract Object	clone(CopyContext context) Clones this object using the specified context.
PropagationStateArray	correctAfterStep(PropagationStepInformation info) Calculates the last steps state corrections.
abstract PropagationStateArray	correctAfterStep(PropagationStepInformation info, PropagationStateArray accelerationCorrection) Calculates the last steps state corrections, as well as the acceleration correction needed by a multistep integrator.
void	dispose() Releases any resources associated with this instance.
protected abstract void	dispose(boolean disposing) Releases any resources associated with this instance.
TimeIntervalCollection	getAvailabilityIntervals() Gets a TimeIntervalCollection over which data is available.
abstract TimeIntervalCollection	getAvailabilityIntervals(TimeIntervalCollection consideredIntervals) Gets the intervals over which data is available.
abstract IEvaluator	getCachingWrapper() Gets a version of this evaluator that caches the previously computed value so that if it is evaluated twice at the same date the computation is done only once.
EvaluatorGroup	getGroup() Gets the group that contains this evaluator.
abstract List<String>	getIdentifications() Gets the list of strings that identify the Propagation State Elements that are altered by this state correction evaluator.
abstract boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
abstract boolean	isAvailable(JulianDate date) Determines if valid data is available for the given JulianDate.
abstract void	updateEvaluatorReferences(CopyContext context) Updates the evaluator references held by this object using the reference-to-reference mapping in the specified CopyContext.

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

PropagationStateCorrectionEvaluator

protected PropagationStateCorrectionEvaluator(@Nonnull
                                              EvaluatorGroup group)

Initializes a new instance.

Parameters:

group - The group that contains this evaluator.

Throws:

ArgumentNullException - Thrown when group is null.

PropagationStateCorrectionEvaluator

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

updateEvaluatorReferences

public abstract void updateEvaluatorReferences(CopyContext context)

Updates the evaluator references held by this object using the reference-to-reference mapping in the specified CopyContext.

The following example shows how to implement this method for an evaluator that contains a nested evaluator:

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

This method is called by EvaluatorGroup and usually does not need to be called directly by users. EvaluatorGroup uses this method to replace references to shared evaluators with references to caching versions of the evaluators.

To implement this method, call CopyContext.updateReference(T) on each evaluator reference held by your evaluator and assign the return value back to the field.

Specified by:

updateEvaluatorReferences in interface IEvaluator

Parameters:

context - The context that specifies the reference mapping.

clone

public abstract 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

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

dispose

public final void dispose()

Releases any resources associated with this instance.

Specified by:

dispose in interface IDisposable

dispose

protected abstract void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.

getAvailabilityIntervals

public abstract TimeIntervalCollection getAvailabilityIntervals(TimeIntervalCollection consideredIntervals)

Gets the intervals over which data is available.

Specified by:

getAvailabilityIntervals in interface IAvailability

Parameters:

consideredIntervals - The intervals over which availability information is needed. Note that the returned availability intervals may indicate availability outside of these intervals of consideration.

Returns:

The collection of availability intervals.

isAvailable

public abstract boolean isAvailable(@Nonnull
                                    JulianDate date)

Determines if valid data is available for the given JulianDate.

Specified by:

isAvailable in interface IAvailability

Parameters:

date - The date for which to check availability.

Returns:

true if valid data is available for this date; otherwise false.

getIsThreadSafe

public abstract boolean getIsThreadSafe()

Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.

If this property is true, all methods and properties are guaranteed to be thread safe. Conceptually, an object that returns true for this method acts as if there is a lock protecting each method and property such that only one thread at a time can be inside any method or property in the class. In reality, such locks are generally not used and are in fact discouraged. However, the user must not experience any exceptions or inconsistent behavior that would not be experienced if such locks were used.

If this property is false, the behavior when using this class from multiple threads simultaneously is undefined and may include inconsistent results and exceptions. Clients wishing to use multiple threads should call CopyForAnotherThread.copy(T) to get a separate instance of the object for each thread.

Specified by:

getIsThreadSafe in interface IThreadAware

getGroup

public final EvaluatorGroup getGroup()

Gets the group that contains this evaluator.

Specified by:

getGroup in interface IEvaluator

getCachingWrapper

public abstract IEvaluator getCachingWrapper()

Gets a version of this evaluator that caches the previously computed value so that if it is evaluated twice at the same date the computation is done only once.

This method is called by EvaluatorGroup to create a caching version of an evaluator that is shared between multiple computations.

To implement this method in your own evaluator, construct and return a caching version of the evaluator's base class. For example, if your evaluator implements IEvaluator1 directly, return an instance of CachingEvaluator. In many cases, such as when implementing a PointEvaluator this method does not need to be overridden because the default implementation returns an appropriate caching wrapper already. If you do not want the last value computed by your evaluator to ever be cached, or if your evaluator does its own caching internally, this method can return this.

Shows an example implementation in an evaluator that implements IEvaluator1 directly, where T is double.

@Override
public IEvaluator getCachingWrapper() {
    return new CachingEvaluator<Double>(this);
}

Specified by:

getCachingWrapper in interface IEvaluator

Returns:

A caching version of this evaluator. If a caching version is not available, or if this object does its own caching, this should be returned by this method.

correctAfterStep

@Nonnull
public PropagationStateArray correctAfterStep(PropagationStepInformation info)

Calculates the last steps state corrections.

Parameters:

info - Holds the time and sub-state information before and after the last integration step.

Returns:

The corrections to this corrector's subsection of the state array.

getIdentifications

public abstract List<String> getIdentifications()

Gets the list of strings that identify the Propagation State Elements that are altered by this state correction evaluator.

correctAfterStep

@Nonnull
public abstract PropagationStateArray correctAfterStep(PropagationStepInformation info,
                                                                 @Nullable
                                                                 PropagationStateArray accelerationCorrection)

Calculates the last steps state corrections, as well as the acceleration correction needed by a multistep integrator.

Parameters:

info - Holds the time and sub-state information before and after the last integration step.

accelerationCorrection - This step's derivative correction will be summed into this sub-state.

Returns:

The corrections to this corrector's subsection of the state array.

getAvailabilityIntervals

public final TimeIntervalCollection getAvailabilityIntervals()

Gets a TimeIntervalCollection over which data is available. If the availability interval is infinite, this returns Infinite (get).

It is recommended that you call PropagationStateCorrectionEvaluator.isAvailable(agi.foundation.time.JulianDate) to determine availability instead of calling this method and checking for yourself.

Returns:

The collection of availability intervals.