EventBasedScheduler

/* 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.estimation.measurements.generation;

import org.orekit.estimation.measurements.EstimatedMeasurementBase;
import org.orekit.estimation.measurements.ObservedMeasurement;
import org.orekit.propagation.Propagator;
import org.orekit.propagation.SpacecraftState;
import org.orekit.propagation.events.DetectorModifier;
import org.orekit.propagation.events.EventDetector;
import org.orekit.propagation.events.handlers.EventHandler;
import org.orekit.time.AbsoluteDate;
import org.orekit.time.DatesSelector;
import org.orekit.utils.TimeSpanMap;

import java.util.function.Predicate;

/** {@link Scheduler} based on {@link EventDetector} for generating measurements sequences.
 * <p>
 * Event-based schedulers generate measurements following a repetitive pattern when the
 * a {@link EventDetector detector} provided at construction is in a {@link SignSemantic
 * measurement feasible} state. It is important that the sign of the g function of the underlying
 * event detector is not arbitrary, but has a semantic meaning, e.g. in or out,
 * true or false. This class works well with event detectors that detect entry to or exit
 * from a region, e.g. {@link org.orekit.propagation.events.EclipseDetector EclipseDetector},
 * {@link org.orekit.propagation.events.ElevationDetector ElevationDetector}, {@link
 * org.orekit.propagation.events.LatitudeCrossingDetector LatitudeCrossingDetector}. Using this
 * scheduler with detectors that are not based on entry to or exit from a region, e.g. {@link
 * org.orekit.propagation.events.DateDetector DateDetector}, {@link
 * org.orekit.propagation.events.LongitudeCrossingDetector LongitudeCrossingDetector}, will likely
 * lead to unexpected results.
 * </p>
 * <p>
 * The repetitive pattern can be either a continuous stream of measurements separated by
 * a constant step (for example one measurement every 60s), or several sequences of measurements
 * at high rate up to a maximum number, with a rest period between sequences (for example
 * sequences of up to 256 measurements every 100ms with 300s between each sequence).
 * </p>
 * @param <T> the type of the measurement
 * @author Luc Maisonobe
 * @since 9.3
 */
public class EventBasedScheduler<T extends ObservedMeasurement<T>> extends AbstractScheduler<T> {

    /** Semantic of the detector g function sign to use. */
    private final SignSemantic signSemantic;

    /** Feasibility status. */
    private TimeSpanMap<Boolean> feasibility;

    /** Propagation direction. */
    private boolean forward;

    /** Simple constructor.
     * <p>
     * The event detector instance should <em>not</em> be already bound to the propagator.
     * It will be wrapped in an {@link DetectorModifier adapter} in order to manage time
     * ranges when measurements are feasible. The wrapping adapter will be automatically
     * {@link Propagator#addEventDetector(EventDetector) added} to the propagator by this
     * constructor.
     * </p>
     * <p>
     * BEWARE! Dates selectors often store internally the last selected dates, so they are not
     * reusable across several {@link EventBasedScheduler instances}. A separate selector
     * should be used for each scheduler.
     * </p>
     * <p>
     * This constructor calls {@link #EventBasedScheduler(MeasurementBuilder, DatesSelector,
     * Predicate, Propagator, EventDetector, SignSemantic)} whith the predicate set to accept
     * all generated measurements.
     * </p>
     * @param builder builder for individual measurements
     * @param selector selector for dates (beware that selectors are generally not
     * reusable across several {@link EventBasedScheduler instances}, each selector should
     * be dedicated to one scheduler
     * @param propagator propagator associated with this scheduler
     * @param detector detector for checking measurements feasibility
     * @param signSemantic semantic of the detector g function sign to use
     */
    public EventBasedScheduler(final MeasurementBuilder<T> builder, final DatesSelector selector,
                               final Propagator propagator,
                               final EventDetector detector, final SignSemantic signSemantic) {
        this(builder, selector, e -> true, propagator, detector, signSemantic);
    }

    /** Simple constructor.
     * <p>
     * The event detector instance should <em>not</em> be already bound to the propagator.
     * It will be wrapped in an {@link DetectorModifier adapter} in order to manage time
     * ranges when measurements are feasible. The wrapping adapter will be automatically
     * {@link Propagator#addEventDetector(EventDetector) added} to the propagator by this
     * constructor.
     * </p>
     * <p>
     * BEWARE! Dates selectors often store internally the last selected dates, so they are not
     * reusable across several {@link EventBasedScheduler instances}. A separate selector
     * should be used for each scheduler.
     * </p>
     * @param builder builder for individual measurements
     * @param selector selector for dates (beware that selectors are generally not
     * reusable across several {@link EventBasedScheduler instances}, each selector should
     * be dedicated to one scheduler
     * @param filter predicate for a posteriori filtering of generated measurements
     *               (measurements are accepted if the predicates evaluates to {@code true})
     * @param propagator propagator associated with this scheduler
     * @param detector detector for checking measurements feasibility
     * @param signSemantic semantic of the detector g function sign to use
     * @since 13.0
     */
    public EventBasedScheduler(final MeasurementBuilder<T> builder, final DatesSelector selector,
                               final Predicate<EstimatedMeasurementBase<T>> filter, final Propagator propagator,
                               final EventDetector detector, final SignSemantic signSemantic) {
        super(builder, selector, filter);
        this.signSemantic = signSemantic;
        this.feasibility  = new TimeSpanMap<>(Boolean.FALSE);
        this.forward      = true;
        propagator.addEventDetector(new FeasibilityModifier(detector));
    }

    /** {@inheritDoc} */
    @Override
    public boolean measurementIsFeasible(final AbsoluteDate date) {
        return feasibility.get(date);
    }

    /** Adapter for managing feasibility status changes. */
    private class FeasibilityModifier implements DetectorModifier {

        /** Wrapped event detector. */
        private final EventDetector eventDetector;

        /** Build an adaptor wrapping an existing detector.
         * @param eventDetector detector to wrap
         */
        FeasibilityModifier(final EventDetector eventDetector) {
            this.eventDetector = eventDetector;
        }

        /** {@inheritDoc} */
        @Override
        public EventDetector getDetector() {
            return eventDetector;
        }

        /** {@inheritDoc} */
        @Override
        public void init(final SpacecraftState s0, final AbsoluteDate t) {
            DetectorModifier.super.init(s0, t);
            forward     = t.compareTo(s0.getDate()) > 0;
            feasibility = new TimeSpanMap<>(signSemantic.measurementIsFeasible(g(s0)));
        }

        /** {@inheritDoc} */
        @Override
        public EventHandler getHandler() {

            final EventDetector rawDetector = getDetector();
            final EventHandler  rawHandler  = rawDetector.getHandler();

            return (state, detector, increasing) -> {

                // find the feasibility status AFTER the current date
                final boolean statusAfter = signSemantic.measurementIsFeasible(increasing ? +1 : -1);

                // store either status or its opposite according to propagation direction
                if (forward) {
                    // forward propagation
                    feasibility.addValidAfter(statusAfter, state.getDate(), false);
                } else {
                    // backward propagation
                    feasibility.addValidBefore(!statusAfter, state.getDate(), false);
                }

                // delegate to wrapped detector
                return rawHandler.eventOccurred(state, rawDetector, increasing);

            };

        }

    }

}