1   /* Copyright 2002-2013 CS Systèmes d'Information
2    * Licensed to CS Systèmes d'Information (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.gravity.potential;
18  
19  import org.orekit.errors.OrekitException;
20  import org.orekit.time.AbsoluteDate;
21  import org.orekit.time.TimeStamped;
22  
23  /**
24   * Interface used to provide un-normalized spherical harmonics coefficients.
25   * <p>
26   * Un-normalized spherical harmonics coefficients are fine for small degrees. At high
27   * degree and order the un-normalized coefficients are not representable in a {@code
28   * double}. {@link NormalizedSphericalHarmonicsProvider} is recommended for high precision
29   * applications.
30   *
31   * @author Luc Maisonobe
32   * @see GravityFieldFactory
33   * @since 6.0
34   */
35  public interface UnnormalizedSphericalHarmonicsProvider extends SphericalHarmonicsProvider {
36  
37      /**
38       * Un-normalized spherical harmonics coefficients evaluated at a specific instant.
39       * @see #onDate(AbsoluteDate)
40       * @since 6.1
41       */
42      interface UnnormalizedSphericalHarmonics extends TimeStamped {
43  
44          /** Get a spherical harmonic cosine coefficient.
45           * @param n degree of the coefficient
46           * @param m order of the coefficient
47           * @return un-normalized coefficient Cnm
48           * @exception OrekitException if the requested maximal degree or order exceeds the
49           * available degree or order
50           */
51          double getUnnormalizedCnm(int n, int m)
52              throws OrekitException;
53  
54          /** Get a spherical harmonic sine coefficient.
55           * @param n degree of the coefficient
56           * @param m order of the coefficient
57           * @return un-normalized coefficient Snm
58           * @exception OrekitException if the requested maximal degree or order exceeds the
59           * available degree or order
60           */
61          double getUnnormalizedSnm(int n, int m)
62              throws OrekitException;
63  
64      }
65  
66  
67      /**
68       * Get the un-normalized spherical harmonic coefficients at a specific instance in time.
69       *
70       * @param date of evaluation
71       * @return un-normalized coefficients on {@code date}.
72       * @throws OrekitException on error
73       * @since 6.1
74       */
75      UnnormalizedSphericalHarmonics onDate(AbsoluteDate date) throws OrekitException;
76  
77      /** Get a spherical harmonic cosine coefficient.
78       * @param dateOffset date offset since reference date (s)
79       * @param n degree of the coefficient
80       * @param m order of the coefficient
81       * @return un-normalized coefficient Cnm
82       * @exception OrekitException if the requested maximal degree or order exceeds the
83       * available degree or order
84       * @deprecated as of 6.1, replaced with {@link #onDate(AbsoluteDate)}
85       */
86      @Deprecated
87      double getUnnormalizedCnm(double dateOffset, int n, int m)
88          throws OrekitException;
89  
90      /** Get a spherical harmonic sine coefficient.
91       * @param dateOffset date offset since reference date (s)
92       * @param n degree of the coefficient
93       * @param m order of the coefficient
94       * @return un-normalized coefficient Snm
95       * @exception OrekitException if the requested maximal degree or order exceeds the
96       * available degree or order
97       * @deprecated as of 6.1, replaced with {@link #onDate(AbsoluteDate)}
98       */
99      @Deprecated
100     double getUnnormalizedSnm(double dateOffset, int n, int m)
101         throws OrekitException;
102 
103 }