FieldDateDetector.java
/* Copyright 2002-2024 CS GROUP
* Licensed to CS GROUP (CS) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* CS licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.orekit.propagation.events;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import org.hipparchus.CalculusFieldElement;
import org.hipparchus.Field;
import org.hipparchus.ode.events.Action;
import org.orekit.errors.OrekitIllegalArgumentException;
import org.orekit.errors.OrekitMessages;
import org.orekit.propagation.FieldSpacecraftState;
import org.orekit.propagation.events.handlers.FieldEventHandler;
import org.orekit.propagation.events.handlers.FieldStopOnEvent;
import org.orekit.time.FieldAbsoluteDate;
import org.orekit.time.FieldTimeStamped;
/** Finder for date events.
* <p>This class finds date events (i.e. occurrence of some predefined dates).</p>
* <p>As of version 5.1, it is an enhanced date detector:</p>
* <ul>
* <li>it can be defined without prior date ({@link #FieldDateDetector(Field, FieldTimeStamped...)})</li>
* <li>several dates can be added ({@link #addEventDate(FieldAbsoluteDate)})</li>
* </ul>
* <p>The gap between the added dates must be more than the minGap.</p>
* <p>The default implementation behavior is to {@link Action#STOP stop}
* propagation at the first event date occurrence. This can be changed by calling
* {@link #withHandler(FieldEventHandler)} after construction.</p>
* @see org.orekit.propagation.FieldPropagator#addEventDetector(FieldEventDetector)
* @author Luc Maisonobe
* @author Pascal Parraud
* @param <T> type of the field elements
*/
public class FieldDateDetector<T extends CalculusFieldElement<T>> extends FieldAbstractDetector<FieldDateDetector<T>, T>
implements FieldTimeStamped<T> {
/** Default value for max check.
* @since 12.0
*/
public static final double DEFAULT_MAX_CHECK = 1.0e10;
/** Default value for minimum gap between added dates.
* @since 12.0
*/
public static final double DEFAULT_MIN_GAP = 1.0;
/** Default value for convergence threshold.
* @since 12.0
*/
public static final double DEFAULT_THRESHOLD = 1.0e-13;
/** Minimum gap between added dates.
* @since 12.0
*/
private final double minGap;
/** Last date for g computation. */
private FieldAbsoluteDate<T> gDate;
/** List of event dates. */
private final ArrayList<FieldEventDate<T>> eventDateList;
/** Current event date. */
private int currentIndex;
/** Build a new instance.
* <p>First event dates are set here, but others can be
* added later with {@link #addEventDate(FieldAbsoluteDate)}.</p>
* @param field field to which dates belong
* @param dates list of event dates
* @see #addEventDate(FieldAbsoluteDate)
* @since 12.0
*/
@SafeVarargs
public FieldDateDetector(final Field<T> field, final FieldTimeStamped<T>... dates) {
this(FieldAdaptableInterval.of(DEFAULT_MAX_CHECK), field.getZero().newInstance(DEFAULT_THRESHOLD),
DEFAULT_MAX_ITER, new FieldStopOnEvent<>(), DEFAULT_MIN_GAP, dates);
}
/** Protected constructor with full parameters.
* <p>
* This constructor is not public as users are expected to use the builder
* API with the various {@code withXxx()} methods to set up the instance
* in a readable manner without using a huge amount of parameters.
* </p>
* @param maxCheck maximum checking interval
* @param threshold convergence threshold (s)
* @param maxIter maximum number of iterations in the event time search
* @param handler event handler to call at event occurrences
* @param minGap minimum gap between added dates (s)
* @param dates list of event dates
*/
@SafeVarargs
protected FieldDateDetector(final FieldAdaptableInterval<T> maxCheck, final T threshold,
final int maxIter, final FieldEventHandler<T> handler,
final double minGap, final FieldTimeStamped<T>... dates) {
super(new FieldEventDetectionSettings<>(maxCheck, threshold, maxIter), handler);
this.currentIndex = -1;
this.gDate = null;
this.eventDateList = new ArrayList<>(dates.length);
for (final FieldTimeStamped<T> ts : dates) {
addEventDate(ts.getDate());
}
this.minGap = minGap;
}
/**
* Setup minimum gap between added dates.
* @param newMinGap new minimum gap between added dates
* @return a new detector with updated configuration (the instance is not changed)
* @since 12.0
*/
public FieldDateDetector<T> withMinGap(final double newMinGap) {
@SuppressWarnings("unchecked")
final FieldTimeStamped<T>[] dates = eventDateList.toArray(new FieldEventDate[eventDateList.size()]);
return new FieldDateDetector<>(getMaxCheckInterval(), getThreshold(), getMaxIterationCount(),
getHandler(), newMinGap, dates);
}
/** {@inheritDoc} */
@Override
protected FieldDateDetector<T> create(final FieldAdaptableInterval<T> newMaxCheck, final T newThreshold,
final int newMaxIter, final FieldEventHandler<T> newHandler) {
@SuppressWarnings("unchecked")
final FieldTimeStamped<T>[] dates = eventDateList.toArray(new FieldEventDate[eventDateList.size()]);
return new FieldDateDetector<>(newMaxCheck, newThreshold, newMaxIter, newHandler, minGap, dates);
}
/** Get all event field dates currently managed, in chronological order.
* @return all event field dates currently managed, in chronological order
* @since 12.0
*/
public List<FieldTimeStamped<T>> getDates() {
return Collections.unmodifiableList(eventDateList);
}
/** Compute the value of the switching function.
* This function measures the difference between the current and the target date.
* @param s the current state information: date, kinematics, attitude
* @return value of the switching function
*/
public T g(final FieldSpacecraftState<T> s) {
gDate = s.getDate();
if (currentIndex < 0) {
return s.getA().getField().getZero().newInstance(-1);
} else {
final FieldEventDate<T> event = getClosest(gDate);
return event.isgIncrease() ? gDate.durationFrom(event.getDate()) : event.getDate().durationFrom(gDate);
}
}
/** Get the current event date according to the propagator.
* @return event date
*/
public FieldAbsoluteDate<T> getDate() {
return currentIndex < 0 ? null : eventDateList.get(currentIndex).getDate();
}
/** Add an event date.
* <p>The date to add must be:</p>
* <ul>
* <li>less than the smallest already registered event date minus the maxCheck</li>
* <li>or more than the largest already registered event date plus the maxCheck</li>
* </ul>
* @param target target date
* @throws IllegalArgumentException if the date is too close from already defined interval
* @see #FieldDateDetector(Field, FieldTimeStamped...)
*/
public void addEventDate(final FieldAbsoluteDate<T> target) throws IllegalArgumentException {
final boolean increasing;
if (currentIndex < 0) {
increasing = (gDate == null) ? true : target.durationFrom(gDate).getReal() > 0.0;
currentIndex = 0;
eventDateList.add(new FieldEventDate<>(target, increasing));
} else {
final int lastIndex = eventDateList.size() - 1;
final FieldAbsoluteDate<T> firstDate = eventDateList.get(0).getDate();
final FieldAbsoluteDate<T> lastDate = eventDateList.get(lastIndex).getDate();
if (firstDate.durationFrom(target).getReal() > minGap) {
increasing = !eventDateList.get(0).isgIncrease();
eventDateList.add(0, new FieldEventDate<>(target, increasing));
currentIndex++;
} else if (target.durationFrom(lastDate).getReal() > minGap) {
increasing = !eventDateList.get(lastIndex).isgIncrease();
eventDateList.add(new FieldEventDate<>(target, increasing));
} else {
throw new OrekitIllegalArgumentException(OrekitMessages.EVENT_DATE_TOO_CLOSE,
target,
firstDate,
lastDate,
minGap,
firstDate.durationFrom(target),
target.durationFrom(lastDate));
}
}
}
/** Get the closest EventDate to the target date.
* @param target target date
* @return current EventDate
*/
private FieldEventDate<T> getClosest(final FieldAbsoluteDate<T> target) {
final T dt = target.durationFrom(eventDateList.get(currentIndex).getDate());
if (dt.getReal() < 0.0 && currentIndex > 0) {
boolean found = false;
while (currentIndex > 0 && !found) {
if (target.durationFrom(eventDateList.get(currentIndex - 1).getDate()).getReal() < eventDateList.get(currentIndex).getDate().durationFrom(target).getReal()) {
currentIndex--;
} else {
found = true;
}
}
} else if (dt.getReal() > 0.0 && currentIndex < eventDateList.size() - 1) {
final int maxIndex = eventDateList.size() - 1;
boolean found = false;
while (currentIndex < maxIndex && !found) {
if (target.durationFrom(eventDateList.get(currentIndex + 1).getDate()).getReal() > eventDateList.get(currentIndex).getDate().durationFrom(target).getReal()) {
currentIndex++;
} else {
found = true;
}
}
}
return eventDateList.get(currentIndex);
}
/** Event date specification. */
private static class FieldEventDate<T extends CalculusFieldElement<T>> implements FieldTimeStamped<T> {
/** Event date. */
private final FieldAbsoluteDate<T> eventDate;
/** Flag for g function way around event date. */
private final boolean gIncrease;
/** Simple constructor.
* @param date date
* @param increase if true, g function increases around event date
*/
FieldEventDate(final FieldAbsoluteDate<T> date, final boolean increase) {
this.eventDate = date;
this.gIncrease = increase;
}
/** Getter for event date.
* @return event date
*/
public FieldAbsoluteDate<T> getDate() {
return eventDate;
}
/** Getter for g function way at event date.
* @return g function increasing flag
*/
public boolean isgIncrease() {
return gIncrease;
}
}
}