1   /* Copyright 2022-2025 Bryan Cazabonne
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    * Bryan Cazabonne 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.propagation.semianalytical.dsst.forces;
18  
19  import org.hipparchus.CalculusFieldElement;
20  import org.orekit.propagation.FieldSpacecraftState;
21  import org.orekit.propagation.PropagationType;
22  import org.orekit.propagation.SpacecraftState;
23  import org.orekit.propagation.semianalytical.dsst.utilities.AuxiliaryElements;
24  import org.orekit.propagation.semianalytical.dsst.utilities.FieldAuxiliaryElements;
25  
26  import java.util.Collections;
27  import java.util.List;
28  
29  /**
30   * Semi-analytical J2-squared model.
31   * <p>
32   * This interface is implemented by models providing J2-squared
33   * second-order terms in equinoctial elements. These terms are
34   * used in the computation of the closed-form J2-squared perturbation
35   * in semi-analytical satellite theory.
36   * </p>
37   * @see ZeisModel
38   * @author Bryan Cazabonne
39   * @since 12.0
40   */
41  public interface J2SquaredModel {
42  
43      /**
44       * Compute the J2-squared second-order terms in equinoctial elements.
45       * @param context model context
46       * @return the J2-squared second-order terms in equinoctial elements.
47       *         Order must follow: [A, K, H, Q, P, M]
48       */
49      double[] computeMeanEquinoctialSecondOrderTerms(DSSTJ2SquaredClosedFormContext context);
50  
51      /**
52       * Compute the J2-squared second-order terms in equinoctial elements.
53       * @param context model context
54       * @param <T> type of the elements
55       * @return the J2-squared second-order terms in equinoctial elements.
56       *         Order must follow: [A, K, H, Q, P, M]
57       */
58      <T extends CalculusFieldElement<T>> T[] computeMeanEquinoctialSecondOrderTerms(FieldDSSTJ2SquaredClosedFormContext<T> context);
59  
60      /**
61       * Performs initialization of J2-squared short period terms prior to propagation.
62       * @param auxiliaryElements auxiliary elements
63       * @param type type of the elements used (MEAN or OSCULATING)
64       * @param parameters force model parameters
65       * @return a list containing the initialized short period terms
66       * @since 12.2
67       */
68      default List<ShortPeriodTerms> initializeShortPeriodTerms(final AuxiliaryElements auxiliaryElements,
69                                                                final PropagationType type,
70                                                                final double[] parameters) {
71          return Collections.emptyList();
72      }
73  
74      /**
75       * Performs initialization of J2-squared short period terms prior to propagation.
76       * @param auxiliaryElements auxiliary elements
77       * @param type type of the orbital elements used (MEAN or OSCULATING)
78       * @param parameters force model parameters
79       * @param <T> type of the field elements
80       * @return a list containing the initialized short period terms
81       * @since 12.2
82       */
83      default <T extends CalculusFieldElement<T>> List<FieldShortPeriodTerms<T>> initializeShortPeriodTerms(final FieldAuxiliaryElements<T> auxiliaryElements,
84                                                                                                            final PropagationType type,
85                                                                                                            final T[] parameters) {
86          return Collections.emptyList();
87      }
88  
89      /** Update the J2-squared short period terms.
90       * <p>
91       * The {@link ShortPeriodTerms short period terms} that will be updated
92       * are the ones that were returned during the call to {@link
93       * #initializeShortPeriodTerms(AuxiliaryElements, PropagationType, double[])}.
94       * </p>
95       * @param parameters force model parameters
96       * @param meanStates mean states information: date, kinematics, attitude
97       * @since 12.2
98       */
99      default void updateShortPeriodTerms(final double[] parameters, final SpacecraftState... meanStates) {
100         // Does nothing by default
101     }
102 
103     /** Update the J2-squared short period terms.
104      * <p>
105      * The {@link ShortPeriodTerms short period terms} that will be updated
106      * are the ones that were returned during the call to {@link
107      * #initializeShortPeriodTerms(AuxiliaryElements, PropagationType, double[])}.
108      * </p>
109      * @param parameters force model parameters
110      * @param meanStates mean states information: date, kinematics, attitude
111      * @param <T> type of the field elements
112      * @since 12.2
113      */
114     @SuppressWarnings("unchecked")
115     default <T extends CalculusFieldElement<T>> void updateShortPeriodTerms(final T[] parameters, final FieldSpacecraftState<T>... meanStates) {
116         // Does nothing by default
117     }
118 
119 }