FieldImpulseManeuver.java

  1. /* Copyright 2002-2024 Exotrail
  2.  * Licensed to CS GROUP (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.forces.maneuvers;

  19. import org.hipparchus.CalculusFieldElement;
  20. import org.hipparchus.geometry.euclidean.threed.FieldRotation;
  21. import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
  22. import org.hipparchus.ode.events.Action;
  23. import org.hipparchus.util.FastMath;
  24. import org.orekit.attitudes.AttitudeProvider;
  25. import org.orekit.orbits.FieldCartesianOrbit;
  26. import org.orekit.propagation.FieldSpacecraftState;
  27. import org.orekit.propagation.events.FieldAbstractDetector;
  28. import org.orekit.propagation.events.FieldAdaptableInterval;
  29. import org.orekit.propagation.events.FieldEventDetector;
  30. import org.orekit.propagation.events.handlers.FieldEventHandler;
  31. import org.orekit.time.FieldAbsoluteDate;
  32. import org.orekit.utils.Constants;
  33. import org.orekit.utils.FieldArrayDictionary;
  34. import org.orekit.utils.FieldPVCoordinates;

  36. /** Impulse maneuver model for propagators working with Fields.
  37.  * <p>This class implements an impulse maneuver as a discrete event
  38.  * that can be provided to any {@link org.orekit.propagation.FieldPropagator
  39.  * Propagator} and mirrors the standard version
  40.  * {@link org.orekit.forces.maneuvers.ImpulseManeuver}.</p>
  41.  * <p>The maneuver is triggered when an underlying event generates a
  42.  * {@link Action#STOP STOP} event, in which case this class will generate a {@link
  43.  * Action#RESET_STATE RESET_STATE}
  44.  * event (the stop event from the underlying object is therefore filtered out).
  45.  * In the simple cases, the underlying event detector may be a basic
  46.  * {@link org.orekit.propagation.events.FieldDateDetector date event}, but it
  47.  * can also be a more elaborate {@link
  48.  * org.orekit.propagation.events.FieldApsideDetector apside event} for apogee
  49.  * maneuvers for example.</p>
  50.  * <p>The maneuver is defined by a single velocity increment.
  51.  * If no AttitudeProvider is given, the current attitude of the spacecraft,
  52.  * defined by the current spacecraft state, will be used as the
  53.  * {@link AttitudeProvider} so the velocity increment should be given in
  54.  * the same pseudoinertial frame as the {@link FieldSpacecraftState} used to
  55.  * construct the propagator that will handle the maneuver.
  56.  * If an AttitudeProvider is given, the velocity increment given should be
  57.  * defined appropriately in consideration of that provider. So, a typical
  58.  * case for tangential maneuvers is to provide a {@link org.orekit.attitudes.LofOffset LOF aligned}
  59.  * attitude provider along with a velocity increment defined in accordance with
  60.  * that LOF aligned attitude provider; e.g. if the LOF aligned attitude provider
  61.  * was constructed using LOFType.VNC the velocity increment should be
  62.  * provided in VNC coordinates.</p>
  63.  * <p>The norm through which the delta-V maps to the mass consumption is chosen via the
  64.  * enum {@link Control3DVectorCostType}. Default is Euclidean. </p>
  65.  * <p>Beware that the triggering event detector must behave properly both
  66.  * before and after maneuver. If for example a node detector is used to trigger
  67.  * an inclination maneuver and the maneuver change the orbit to an equatorial one,
  68.  * the node detector will fail just after the maneuver, being unable to find a
  69.  * node on an equatorial orbit! This is a real case that has been encountered
  70.  * during validation ...</p>
  71.  * @see org.orekit.propagation.FieldPropagator#addEventDetector(FieldEventDetector)
  72.  * @see org.orekit.forces.maneuvers.ImpulseManeuver
  73.  * @author Romain Serra
  74.  * @since 12.0
  75.  * @param <D> type of the detector
  76.  * @param <T> type of the field elements
  77.  */
  78. public class FieldImpulseManeuver<D extends FieldEventDetector<T>, T extends CalculusFieldElement<T>>
  79.         extends FieldAbstractDetector<FieldImpulseManeuver<D, T>, T> {

  81.     /** The attitude to override during the maneuver, if set. */
  82.     private final AttitudeProvider attitudeOverride;

  84.     /** Triggering event. */
  85.     private final D trigger;

  87.     /** Velocity increment in satellite frame. */
  88.     private final FieldVector3D<T> deltaVSat;

  90.     /** Specific impulse. */
  91.     private final T isp;

  93.     /** Engine exhaust velocity. */
  94.     private final T vExhaust;

  96.     /** Indicator for forward propagation. */
  97.     private boolean forward;

  99.     /** Type of norm linking delta-V to mass consumption. */
  100.     private final Control3DVectorCostType control3DVectorCostType;

  102.     /** Build a new instance.
  103.      * @param trigger triggering event
  104.      * @param deltaVSat velocity increment in satellite frame
  105.      * @param isp engine specific impulse (s)
  106.      */
  107.     public FieldImpulseManeuver(final D trigger, final FieldVector3D<T> deltaVSat, final T isp) {
  108.         this(trigger, null, deltaVSat, isp);
  109.     }

  111.     /** Build a new instance.
  112.      * @param trigger triggering event
  113.      * @param attitudeOverride the attitude provider to use for the maneuver
  114.      * @param deltaVSat velocity increment in satellite frame
  115.      * @param isp engine specific impulse (s)
  116.      */
  117.     public FieldImpulseManeuver(final D trigger, final AttitudeProvider attitudeOverride,
  118.                                 final FieldVector3D<T> deltaVSat, final T isp) {
  119.         this(trigger.getMaxCheckInterval(), trigger.getThreshold(), trigger.getMaxIterationCount(),
  120.                 new Handler<>(), trigger, attitudeOverride, deltaVSat, isp,
  121.                 Control3DVectorCostType.TWO_NORM);
  122.     }

  124.     /** Build a new instance.
  125.      * @param trigger triggering event
  126.      * @param attitudeOverride the attitude provider to use for the maneuver
  127.      * @param deltaVSat velocity increment in satellite frame
  128.      * @param isp engine specific impulse (s)
  129.      * @param control3DVectorCostType increment's norm for mass consumption
  130.      */
  131.     public FieldImpulseManeuver(final D trigger, final AttitudeProvider attitudeOverride,
  132.                                 final FieldVector3D<T> deltaVSat, final T isp,
  133.                                 final Control3DVectorCostType control3DVectorCostType) {
  134.         this(trigger.getMaxCheckInterval(), trigger.getThreshold(), trigger.getMaxIterationCount(),
  135.                 new Handler<>(), trigger, attitudeOverride, deltaVSat, isp, control3DVectorCostType);
  136.     }

  138.     /** Private constructor with full parameters.
  139.      * <p>
  140.      * This constructor is private as users are expected to use the builder
  141.      * API with the various {@code withXxx()} methods to set up the instance
  142.      * in a readable manner without using a huge amount of parameters.
  143.      * </p>
  144.      * @param maxCheck maximum checking interval
  145.      * @param threshold convergence threshold (s)
  146.      * @param maxIter maximum number of iterations in the event time search
  147.      * @param eventHandler event handler to call at event occurrences
  148.      * @param trigger triggering event
  149.      * @param attitudeOverride the attitude provider to use for the maneuver
  150.      * @param deltaVSat velocity increment in satellite frame
  151.      * @param isp engine specific impulse (s)
  152.      * @param control3DVectorCostType increment's norm for mass consumption
  153.      */
  154.     private FieldImpulseManeuver(final FieldAdaptableInterval<T> maxCheck, final T threshold, final int maxIter,
  155.                                  final FieldEventHandler<T> eventHandler, final D trigger,
  156.                                  final AttitudeProvider attitudeOverride, final FieldVector3D<T> deltaVSat,
  157.                                  final T isp, final Control3DVectorCostType control3DVectorCostType) {
  158.         super(maxCheck, threshold, maxIter, eventHandler);
  159.         this.trigger = trigger;
  160.         this.deltaVSat = deltaVSat;
  161.         this.isp = isp;
  162.         this.attitudeOverride = attitudeOverride;
  163.         this.control3DVectorCostType = control3DVectorCostType;
  164.         this.vExhaust = this.isp.multiply(Constants.G0_STANDARD_GRAVITY);
  165.     }

  167.     /** {@inheritDoc} */
  168.     @Override
  169.     protected FieldImpulseManeuver<D, T> create(final FieldAdaptableInterval<T> newMaxCheck, final T newThreshold,
  170.                                                 final int newMaxIter,
  171.                                                 final FieldEventHandler<T> fieldEventHandler) {
  172.         return new FieldImpulseManeuver<>(newMaxCheck, newThreshold, newMaxIter, fieldEventHandler,
  173.                 trigger, attitudeOverride, deltaVSat, isp, control3DVectorCostType);
  174.     }

  176.     /** {@inheritDoc} */
  177.     @Override
  178.     public void init(final FieldSpacecraftState<T> s0, final FieldAbsoluteDate<T> t) {
  179.         forward = t.durationFrom(s0.getDate()).getReal() >= 0;
  180.         // Initialize the triggering event
  181.         trigger.init(s0, t);
  182.     }

  184.     /** {@inheritDoc} */
  185.     @Override
  186.     public T g(final FieldSpacecraftState<T> fieldSpacecraftState) {
  187.         return trigger.g(fieldSpacecraftState);
  188.     }

  190.     /**
  191.      * Get the Attitude Provider to use during maneuver.
  192.      * @return the attitude provider
  193.      */
  194.     public AttitudeProvider getAttitudeOverride() {
  195.         return attitudeOverride;
  196.     }

  198.     /** Get the triggering event.
  199.      * @return triggering event
  200.      */
  201.     public FieldEventDetector<T> getTrigger() {
  202.         return trigger;
  203.     }

  205.     /** Get the velocity increment in satellite frame.
  206.      * @return velocity increment in satellite frame
  207.      */
  208.     public FieldVector3D<T> getDeltaVSat() {
  209.         return deltaVSat;
  210.     }

  212.     /** Get the specific impulse.
  213.      * @return specific impulse
  214.      */
  215.     public T getIsp() {
  216.         return isp;
  217.     }

  219.     /** Get the control vector's cost type.
  220.      * @return control cost type
  221.      * @since 12.0
  222.      */
  223.     public Control3DVectorCostType getControl3DVectorCostType() {
  224.         return control3DVectorCostType;
  225.     }

  227.     /** Local handler. */
  228.     private static class Handler<T extends CalculusFieldElement<T>> implements FieldEventHandler<T> {

  230.         /** {@inheritDoc} */
  231.         @Override
  232.         public Action eventOccurred(final FieldSpacecraftState<T> s,
  233.                                     final FieldEventDetector<T> detector,
  234.                                     final boolean increasing) {
  235.             // filter underlying event
  236.             @SuppressWarnings("unchecked")
  237.             final FieldImpulseManeuver<?, T> im = (FieldImpulseManeuver<?, T>) detector;
  238.             final Action underlyingAction = im.trigger.getHandler().eventOccurred(s, im.trigger,
  239.                     increasing);

  241.             return (underlyingAction == Action.STOP) ? Action.RESET_STATE : Action.CONTINUE;
  242.         }

  244.         /** {@inheritDoc} */
  245.         @Override
  246.         public FieldSpacecraftState<T> resetState(final FieldEventDetector<T> detector,
  247.                                                   final FieldSpacecraftState<T> oldState) {

  249.             @SuppressWarnings("unchecked")
  250.             final FieldImpulseManeuver<?, T> im = (FieldImpulseManeuver<?, T>) detector;
  251.             final FieldAbsoluteDate<T> date = oldState.getDate();
  252.             final FieldRotation<T> rotation;

  254.             if (im.getAttitudeOverride() == null) {
  255.                 rotation = oldState.getAttitude().getRotation();
  256.             } else {
  257.                 rotation = im.attitudeOverride.getAttitudeRotation(oldState.getOrbit(), date,
  258.                         oldState.getFrame());
  259.             }

  261.             // convert velocity increment in inertial frame
  262.             final FieldVector3D<T> deltaV = rotation.applyInverseTo(im.deltaVSat);
  263.             final T one = oldState.getMu().getField().getOne();
  264.             final T sign = (im.forward) ? one : one.negate();

  266.             // apply increment to position/velocity
  267.             final FieldPVCoordinates<T> oldPV = oldState.getPVCoordinates();
  268.             final FieldPVCoordinates<T> newPV =
  269.                     new FieldPVCoordinates<>(oldPV.getPosition(),
  270.                             new FieldVector3D<>(one, oldPV.getVelocity(), sign, deltaV));
  271.             final FieldCartesianOrbit<T> newOrbit =
  272.                     new FieldCartesianOrbit<>(newPV, oldState.getFrame(), date, oldState.getMu());

  274.             // compute new mass
  275.             final T normDeltaV = im.control3DVectorCostType.evaluate(im.deltaVSat);
  276.             final T newMass = oldState.getMass().multiply(FastMath.exp(normDeltaV.multiply(sign.negate()).divide(im.vExhaust)));

  278.             // pack everything in a new state
  279.             FieldSpacecraftState<T> newState = new FieldSpacecraftState<>(oldState.getOrbit().getType().normalize(newOrbit, oldState.getOrbit()),
  280.                     oldState.getAttitude(), newMass);

  282.             for (final FieldArrayDictionary<T>.Entry entry : oldState.getAdditionalStatesValues().getData()) {
  283.                 newState = newState.addAdditionalState(entry.getKey(), entry.getValue());
  284.             }
  285.             for (final FieldArrayDictionary<T>.Entry entry : oldState.getAdditionalStatesDerivatives().getData()) {
  286.                 newState = newState.addAdditionalStateDerivative(entry.getKey(), entry.getValue());
  287.             }

  289.             return newState;
  290.         }

  292.     }
  293. }
Created with JaCoCo 0.8.12.202403310830