FieldImpulseManeuver.java

  1. /* Copyright 2002-2025 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.orbits.FieldOrbit;
  27. import org.orekit.propagation.FieldSpacecraftState;
  28. import org.orekit.propagation.events.FieldDetectorModifier;
  29. import org.orekit.propagation.events.FieldEventDetectionSettings;
  30. import org.orekit.propagation.events.FieldEventDetector;
  31. import org.orekit.propagation.events.handlers.FieldEventHandler;
  32. import org.orekit.time.FieldAbsoluteDate;
  33. import org.orekit.utils.Constants;
  34. import org.orekit.utils.FieldAbsolutePVCoordinates;
  35. import org.orekit.utils.FieldPVCoordinates;

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

  79.     /** Triggering event. */
  80.     private final FieldEventDetector<T> trigger;

  82.     /** Specific impulse. */
  83.     private final T isp;

  85.     /** Engine exhaust velocity. */
  86.     private final T vExhaust;

  88.     /** Trigger's detection settings. */
  89.     private final FieldEventDetectionSettings<T> detectionSettings;

  91.     /** Specific event handler. */
  92.     private final Handler<T> handler;

  94.     /** Field impulse provider. */
  95.     private final FieldImpulseProvider<T> fieldImpulseProvider;

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

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

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

  120.     /** Build a new instance.
  121.      * @param trigger triggering event
  122.      * @param attitudeOverride the attitude provider to use for the maneuver
  123.      * @param deltaVSat velocity increment in satellite frame
  124.      * @param isp engine specific impulse (s)
  125.      * @param control3DVectorCostType increment's norm for mass consumption
  126.      * @deprecated since 13.0
  127.      */
  128.     @Deprecated
  129.     public FieldImpulseManeuver(final FieldEventDetector<T> trigger, final AttitudeProvider attitudeOverride,
  130.                                 final FieldVector3D<T> deltaVSat, final T isp,
  131.                                 final Control3DVectorCostType control3DVectorCostType) {
  132.         this(trigger, trigger.getDetectionSettings(), attitudeOverride,
  133.                 FieldImpulseProvider.of(deltaVSat), isp, control3DVectorCostType);
  134.     }

  136.     /** Build a new instance.
  137.      * @param trigger triggering event
  138.      * @param attitudeOverride the attitude provider to use for the maneuver
  139.      * @param fieldImpulseProvider impulse provider
  140.      * @param isp engine specific impulse (s)
  141.      * @param control3DVectorCostType increment's norm for mass consumption
  142.      */
  143.     public FieldImpulseManeuver(final FieldEventDetector<T> trigger, final AttitudeProvider attitudeOverride,
  144.                                 final FieldImpulseProvider<T> fieldImpulseProvider, final T isp,
  145.                                 final Control3DVectorCostType control3DVectorCostType) {
  146.         this(trigger, trigger.getDetectionSettings(), attitudeOverride, fieldImpulseProvider, isp, control3DVectorCostType);
  147.     }

  149.     /** Private constructor.
  150.      * @param trigger triggering event
  151.      * @param detectionSettings event detection settings
  152.      * @param attitudeOverride the attitude provider to use for the maneuver
  153.      * @param fieldImpulseProvider impulse provider
  154.      * @param isp engine specific impulse (s)
  155.      * @param control3DVectorCostType increment's norm for mass consumption
  156.      */
  157.     private FieldImpulseManeuver(final FieldEventDetector<T> trigger,
  158.                                  final FieldEventDetectionSettings<T> detectionSettings,
  159.                                  final AttitudeProvider attitudeOverride, final FieldImpulseProvider<T> fieldImpulseProvider,
  160.                                  final T isp, final Control3DVectorCostType control3DVectorCostType) {
  161.         super(attitudeOverride, control3DVectorCostType);
  162.         this.trigger = trigger;
  163.         this.detectionSettings = detectionSettings;
  164.         this.fieldImpulseProvider = fieldImpulseProvider;
  165.         this.isp = isp;
  166.         this.vExhaust = this.isp.multiply(Constants.G0_STANDARD_GRAVITY);
  167.         this.handler = new Handler<>();
  168.     }

  170.     /**
  171.      * Creates a copy with different event detection settings.
  172.      * @param eventDetectionSettings new detection settings
  173.      * @return a new detector with same properties except for the detection settings
  174.      */
  175.     public FieldImpulseManeuver<T> withDetectionSettings(final FieldEventDetectionSettings<T> eventDetectionSettings) {
  176.         return new FieldImpulseManeuver<>(trigger, eventDetectionSettings, getAttitudeOverride(), fieldImpulseProvider, isp,
  177.                 getControl3DVectorCostType());
  178.     }

  180.     /** {@inheritDoc} */
  181.     @Override
  182.     public void init(final FieldSpacecraftState<T> s0, final FieldAbsoluteDate<T> t) {
  183.         FieldDetectorModifier.super.init(s0, t);
  184.         forward = t.durationFrom(s0.getDate()).getReal() >= 0;
  185.         fieldImpulseProvider.init(s0, t);
  186.     }

  188.     /** {@inheritDoc} */
  189.     @Override
  190.     public void finish(final FieldSpacecraftState<T> state) {
  191.         FieldDetectorModifier.super.finish(state);
  192.         fieldImpulseProvider.finish(state);
  193.     }

  195.     /** {@inheritDoc} */
  196.     @Override
  197.     public FieldEventDetectionSettings<T> getDetectionSettings() {
  198.         return detectionSettings;
  199.     }

  201.     /** {@inheritDoc} */
  202.     @Override
  203.     public FieldEventDetector<T> getDetector() {
  204.         return trigger;
  205.     }

  207.     /** Get the triggering event.
  208.      * @return triggering event
  209.      */
  210.     public FieldEventDetector<T> getTrigger() {
  211.         return getDetector();
  212.     }

  214.     /**
  215.      * Getter for the impulse provider.
  216.      * @return impulse provider
  217.      * @since 13.0
  218.      */
  219.     public FieldImpulseProvider<T> getFieldImpulseProvider() {
  220.         return fieldImpulseProvider;
  221.     }

  223.     /** Get the specific impulse.
  224.      * @return specific impulse
  225.      */
  226.     public T getIsp() {
  227.         return isp;
  228.     }

  230.     @Override
  231.     public FieldEventHandler<T> getHandler() {
  232.         return handler;
  233.     }

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

  238.         /** {@inheritDoc} */
  239.         @Override
  240.         public Action eventOccurred(final FieldSpacecraftState<T> s,
  241.                                     final FieldEventDetector<T> detector,
  242.                                     final boolean increasing) {
  243.             final FieldImpulseManeuver<T> im = (FieldImpulseManeuver<T>) detector;
  244.             im.trigger.getHandler().eventOccurred(s, im.trigger, increasing); // Action ignored but method still called
  245.             return Action.RESET_STATE;
  246.         }

  248.         /** {@inheritDoc} */
  249.         @Override
  250.         public FieldSpacecraftState<T> resetState(final FieldEventDetector<T> detector,
  251.                                                   final FieldSpacecraftState<T> oldState) {

  253.             final FieldImpulseManeuver<T> im = (FieldImpulseManeuver<T>) detector;
  254.             final FieldAbsoluteDate<T> date = oldState.getDate();
  255.             final boolean isStateOrbitDefined = oldState.isOrbitDefined();

  257.             final FieldRotation<T> rotation;
  258.             if (im.getAttitudeOverride() == null) {
  259.                 rotation = oldState.getAttitude().getRotation();
  260.             } else {
  261.                 rotation = im.getAttitudeOverride().getAttitudeRotation(isStateOrbitDefined ? oldState.getOrbit() : oldState.getAbsPVA(),
  262.                         date, oldState.getFrame());
  263.             }

  265.             // convert velocity increment in inertial frame
  266.             final FieldVector3D<T> deltaVSat = im.fieldImpulseProvider.getImpulse(oldState, im.forward);
  267.             final FieldVector3D<T> deltaV = rotation.applyInverseTo(deltaVSat);
  268.             final T one = oldState.getMass().getField().getOne();
  269.             final T sign = (im.forward) ? one : one.negate();

  271.             // apply increment to position/velocity
  272.             final FieldPVCoordinates<T> oldPV = oldState.getPVCoordinates();
  273.             final FieldVector3D<T> newVelocity = oldPV.getVelocity().add(deltaV);
  274.             final FieldPVCoordinates<T> newPV = new FieldPVCoordinates<>(oldPV.getPosition(), newVelocity);

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

  280.             // pack everything in a new state
  281.             if (oldState.isOrbitDefined()) {
  282.                 final FieldOrbit<T> newOrbit = new FieldCartesianOrbit<>(newPV, oldState.getFrame(), oldState.getDate(),
  283.                         oldState.getOrbit().getMu());
  284.                 return new FieldSpacecraftState<>(oldState.getOrbit().getType().normalize(newOrbit, oldState.getOrbit()),
  285.                         oldState.getAttitude(), newMass, oldState.getAdditionalDataValues(),
  286.                         oldState.getAdditionalStatesDerivatives());
  287.             } else {
  288.                 final FieldAbsolutePVCoordinates<T> newAbsPVA = new FieldAbsolutePVCoordinates<>(oldState.getFrame(),
  289.                         oldState.getDate(), newPV);
  290.                 return new FieldSpacecraftState<>(newAbsPVA, oldState.getAttitude(), newMass,
  291.                         oldState.getAdditionalDataValues(), oldState.getAdditionalStatesDerivatives());
  292.             }
  293.         }

  295.     }
  296. }
Created with JaCoCo 0.8.12.202403310830