IntervalEventTrigger.java
/* Copyright 2002-2025 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.forces.maneuvers.trigger;
import java.util.HashMap;
import java.util.Map;
import java.util.stream.Stream;
import org.hipparchus.CalculusFieldElement;
import org.hipparchus.Field;
import org.hipparchus.ode.events.Action;
import org.orekit.propagation.FieldSpacecraftState;
import org.orekit.propagation.SpacecraftState;
import org.orekit.propagation.events.EventDetector;
import org.orekit.propagation.events.FieldEventDetector;
import org.orekit.propagation.events.handlers.FieldEventHandler;
import org.orekit.time.AbsoluteDate;
import org.orekit.time.FieldAbsoluteDate;
/**
* Maneuver triggers based on a single event detector that defines firing intervals.
* <p>
* Firing intervals correspond to time spans with positive value of the event detector
* {@link EventDetector#g(SpacecraftState) g} function.
* </p>
* @param <T> type of the interval detector
* @see StartStopEventsTrigger
* @author Luc Maisonobe
* @since 11.1
*/
public abstract class IntervalEventTrigger<T extends EventDetector> extends AbstractManeuverTriggers {
/** Intervals detector. */
private final ManeuverTriggerDetector<T> firingIntervalDetector;
/** Cached field-based detectors. */
private final Map<Field<? extends CalculusFieldElement<?>>, FieldEventDetector<? extends CalculusFieldElement<?>>> cached;
/** Simple constructor.
* <p>
* Note that the {@code intervalDetector} passed as an argument is used only
* as a <em>prototype</em> from which a new detector will be built using
* {@link ManeuverTriggerDetector}. The original event handler from the prototype
* will be <em>ignored</em> and never called.
* </p>
* <p>
* If the trigger is used in a {@link org.orekit.propagation.FieldPropagator field-based propagation},
* the detector will be automatically converted to a field equivalent. Beware however that the
* {@link FieldEventHandler#eventOccurred(FieldSpacecraftState, FieldEventDetector, boolean) eventOccurred}
* of the converted propagator <em>will</em> call the method with the same name in the prototype
* detector, in order to get the correct return value.
* </p>
* @param prototypeFiringIntervalDetector prototype detector for firing interval
*/
protected IntervalEventTrigger(final T prototypeFiringIntervalDetector) {
this.firingIntervalDetector = new ManeuverTriggerDetector<>(prototypeFiringIntervalDetector, new Handler());
this.cached = new HashMap<>();
}
/** {@inheritDoc} */
@Override
public void init(final SpacecraftState initialState, final AbsoluteDate target) {
this.firingIntervalDetector.init(initialState, target);
super.init(initialState, target);
}
/** {@inheritDoc} */
@Override
public <D extends CalculusFieldElement<D>> void init(final FieldSpacecraftState<D> initialState,
final FieldAbsoluteDate<D> target) {
this.firingIntervalDetector.init(initialState.toSpacecraftState(), target.toAbsoluteDate());
super.init(initialState, target);
}
/**
* Getter for the firing interval detector.
* @return firing interval detector
*/
public T getFiringIntervalDetector() {
return firingIntervalDetector.getDetector();
}
/** {@inheritDoc} */
@Override
protected boolean isFiringOnInitialState(final SpacecraftState initialState, final boolean isForward) {
// set the initial value of firing
final double insideThrustArcG = firingIntervalDetector.g(initialState);
if (insideThrustArcG == 0) {
// bound of arc
// check state for the upcoming times
final double shift = (isForward ? 2 : -2) * firingIntervalDetector.getThreshold();
if (firingIntervalDetector.g(initialState.shiftedBy(shift)) > 0) {
// we are entering the firing interval, from start if forward, from end if backward
notifyResetters(initialState, isForward);
return true;
} else {
// we are leaving the firing interval, from end if forward, from start if backward
notifyResetters(initialState, !isForward);
return false;
}
} else {
return insideThrustArcG > 0;
}
}
/** {@inheritDoc} */
@Override
public Stream<EventDetector> getEventDetectors() {
return Stream.of(firingIntervalDetector);
}
/** {@inheritDoc} */
@Override
public <S extends CalculusFieldElement<S>> Stream<FieldEventDetector<S>> getFieldEventDetectors(final Field<S> field) {
@SuppressWarnings("unchecked")
FieldEventDetector<S> fd = (FieldEventDetector<S>) cached.get(field);
if (fd == null) {
fd = convertAndSetUpHandler(field);
cached.put(field, fd);
}
return Stream.of(fd);
}
/** Convert a detector and set up check interval, threshold and new handler.
* <p>
* This method is not inlined in {@link #getFieldEventDetectors(Field)} because the
* parameterized types confuses the Java compiler.
* </p>
* @param field field to which the state belongs
* @param <D> type of the event detector
* @param <S> type of the field elements
* @return converted firing intervals detector
*/
private <D extends FieldEventDetector<S>, S extends CalculusFieldElement<S>> FieldManeuverTriggerDetector<S, D> convertAndSetUpHandler(final Field<S> field) {
final D converted = convertIntervalDetector(field, firingIntervalDetector.getDetector());
return new FieldManeuverTriggerDetector<>(converted, new FieldHandler<>());
}
/** Convert a primitive firing intervals detector into a field firing intervals detector.
* <p>
* The {@link org.orekit.propagation.events.FieldEventDetectionSettings} must be set up in conformance with the
* non-field detector.
* </p>
* <p>
* A skeleton implementation of this method to convert some {@code XyzDetector} into {@code FieldXyzDetector},
* considering these detectors are created from a date and a number parameter is:
* </p>
* <pre>{@code
* protected <D extends FieldEventDetector<S>, S extends CalculusFieldElement<S>>
* D convertIntervalDetector(final Field<S> field, final XyzDetector detector) {
*
* final FieldAbsoluteDate<S> date = new FieldAbsoluteDate<>(field, detector.getDate());
* final S param = field.getZero().newInstance(detector.getParam());
*
* D converted = (D) new FieldXyzDetector<>(date, param).withDetectionSettings(field, detector.getDetectionSettings());
* return converted;
*
* }
* }
* </pre>
* @param field field to which the state belongs
* @param detector primitive firing intervals detector to convert
* @param <D> type of the event detector
* @param <S> type of the field elements
* @return converted firing intervals detector
*/
protected abstract <D extends FieldEventDetector<S>, S extends CalculusFieldElement<S>>
D convertIntervalDetector(Field<S> field, T detector);
/** Local handler for both start and stop triggers. */
private class Handler extends TriggerHandler {
/** {@inheritDoc} */
@Override
public Action eventOccurred(final SpacecraftState s, final EventDetector detector, final boolean increasing) {
if (isForward()) {
getFirings().addValidAfter(increasing, s.getDate(), false);
} else {
getFirings().addValidBefore(!increasing, s.getDate(), false);
}
notifyResetters(s, increasing);
return determineAction(detector, s);
}
}
/** Local handler for both start and stop triggers.
* @param <S> type of the field elements
*/
private class FieldHandler<S extends CalculusFieldElement<S>> extends FieldTriggerHandler<S> {
/** {@inheritDoc} */
@Override
public Action eventOccurred(final FieldSpacecraftState<S> s, final FieldEventDetector<S> detector, final boolean increasing) {
if (isForward()) {
getFirings().addValidAfter(increasing, s.getDate().toAbsoluteDate(), false);
} else {
getFirings().addValidBefore(!increasing, s.getDate().toAbsoluteDate(), false);
}
notifyResetters(s, increasing);
return determineAction(detector, s);
}
}
}