ForceModel.java
/* Copyright 2002-2017 CS Systèmes d'Information
* Licensed to CS Systèmes d'Information (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;
import java.util.stream.Stream;
import org.hipparchus.Field;
import org.hipparchus.RealFieldElement;
import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
import org.hipparchus.geometry.euclidean.threed.Vector3D;
import org.hipparchus.util.MathArrays;
import org.orekit.errors.OrekitException;
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.numerical.FieldTimeDerivativesEquations;
import org.orekit.propagation.numerical.TimeDerivativesEquations;
import org.orekit.time.AbsoluteDate;
import org.orekit.utils.ParameterDriver;
/** This interface represents a force modifying spacecraft motion.
*
* <p>
* Objects implementing this interface are intended to be added to a
* {@link org.orekit.propagation.numerical.NumericalPropagator numerical propagator}
* before the propagation is started.
*
* <p>
* The propagator will call at each step the {@link #addContribution(SpacecraftState,
* TimeDerivativesEquations)} method. The force model instance will extract all the
* state data it needs (date, position, velocity, frame, attitude, mass) from the first
* parameter. From these state data, it will compute the perturbing acceleration. It
* will then add this acceleration to the second parameter which will take thins
* contribution into account and will use the Gauss equations to evaluate its impact
* on the global state derivative.
* </p>
* <p>
* Force models which create discontinuous acceleration patterns (typically for maneuvers
* start/stop or solar eclipses entry/exit) must provide one or more {@link
* org.orekit.propagation.events.EventDetector events detectors} to the
* propagator thanks to their {@link #getEventsDetectors()} method. This method
* is called once just before propagation starts. The events states will be checked by
* the propagator to ensure accurate propagation and proper events handling.
* </p>
*
* @author Mathieu Roméro
* @author Luc Maisonobe
* @author Véronique Pommier-Maurussane
*/
public interface ForceModel {
/**
* Initialize the force model at the start of propagation. This method will be called
* before any calls to {@link #addContribution(SpacecraftState, TimeDerivativesEquations)},
* {@link #addContribution(FieldSpacecraftState, FieldTimeDerivativesEquations)},
* {@link #acceleration(SpacecraftState, double[])} or {@link #acceleration(FieldSpacecraftState, RealFieldElement[])}
*
* <p> The default implementation of this method does nothing.</p>
*
* @param initialState spacecraft state at the start of propagation.
* @param target date of propagation. Not equal to {@code initialState.getDate()}.
* @throws OrekitException if an implementing class overrides the default behavior and
* takes some action that throws an {@link OrekitException}.
*/
default void init(SpacecraftState initialState, AbsoluteDate target)
throws OrekitException {
}
/** Compute the contribution of the force model to the perturbing
* acceleration.
* <p>
* The default implementation simply adds the {@link #acceleration(SpacecraftState, double[]) acceleration}
* as a non-Keplerian acceleration.
* </p>
* @param s current state information: date, kinematics, attitude
* @param adder object where the contribution should be added
* @exception OrekitException if some specific error occurs
*/
default void addContribution(SpacecraftState s, TimeDerivativesEquations adder)
throws OrekitException {
adder.addNonKeplerianAcceleration(acceleration(s, getParameters()));
}
/** Compute the contribution of the force model to the perturbing
* acceleration.
* @param s current state information: date, kinematics, attitude
* @param adder object where the contribution should be added
* @param <T> type of the elements
* @exception OrekitException if some specific error occurs
*/
default <T extends RealFieldElement<T>> void addContribution(FieldSpacecraftState<T> s, FieldTimeDerivativesEquations<T> adder)
throws OrekitException {
adder.addNonKeplerianAcceleration(acceleration(s, getParameters(s.getDate().getField())));
}
/** Get force model parameters.
* @return force model parameters
* @since 9.0
*/
default double[] getParameters() {
final ParameterDriver[] drivers = getParametersDrivers();
final double[] parameters = new double[drivers.length];
for (int i = 0; i < drivers.length; ++i) {
parameters[i] = drivers[i].getValue();
}
return parameters;
}
/** Get force model parameters.
* @param field field to which the elements belong
* @param <T> type of the elements
* @return force model parameters
* @since 9.0
*/
default <T extends RealFieldElement<T>> T[] getParameters(final Field<T> field) {
final ParameterDriver[] drivers = getParametersDrivers();
final T[] parameters = MathArrays.buildArray(field, drivers.length);
for (int i = 0; i < drivers.length; ++i) {
parameters[i] = field.getZero().add(drivers[i].getValue());
}
return parameters;
}
/** Check if force models depends on position only.
* @return true if force model depends on position only, false
* if it depends on velocity, either directly or due to a dependency
* on attitude
* @since 9.0
*/
boolean dependsOnPositionOnly();
/** Compute acceleration.
* @param s current state information: date, kinematics, attitude
* @param parameters values of the force model parameters
* @return acceleration in same frame as state
* @exception OrekitException if some specific error occurs
* @since 9.0
*/
Vector3D acceleration(SpacecraftState s, double[] parameters)
throws OrekitException;
/** Compute acceleration.
* @param s current state information: date, kinematics, attitude
* @param parameters values of the force model parameters
* @return acceleration in same frame as state
* @param <T> type of the elements
* @exception OrekitException if some specific error occurs
* @since 9.0
*/
<T extends RealFieldElement<T>> FieldVector3D<T> acceleration(FieldSpacecraftState<T> s, T[] parameters)
throws OrekitException;
/** Get the discrete events related to the model.
* @return stream of events detectors
*/
Stream<EventDetector> getEventsDetectors();
/** Get the discrete events related to the model.
* @param field field to which the state belongs
* @param <T> extends RealFieldElement<T>
* @return stream of events detectors
*/
<T extends RealFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventsDetectors(Field<T> field);
/** Get the drivers for force model parameters.
* @return drivers for force model parameters
* @since 8.0
*/
ParameterDriver[] getParametersDrivers();
/** Get parameter value from its name.
* @param name parameter name
* @return parameter value
* @exception OrekitException if parameter is not supported
* @since 8.0
*/
ParameterDriver getParameterDriver(String name) throws OrekitException;
/** Check if a parameter is supported.
* <p>Supported parameters are those listed by {@link #getParametersDrivers()}.</p>
* @param name parameter name to check
* @return true if the parameter is supported
* @see #getParametersDrivers()
*/
boolean isSupported(String name);
}