OceanTidesField.java

  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;

  19. import java.util.List;

  21. import org.apache.commons.math3.util.FastMath;
  22. import org.orekit.data.BodiesElements;
  23. import org.orekit.data.FundamentalNutationArguments;
  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.forces.gravity.potential.NormalizedSphericalHarmonicsProvider;
  26. import org.orekit.forces.gravity.potential.OceanTidesWave;
  27. import org.orekit.forces.gravity.potential.TideSystem;
  28. import org.orekit.time.AbsoluteDate;
  29. import org.orekit.time.TimeFunction;

  31. /** Gravity field corresponding to ocean tides.
  32.  * <p>
  33.  * This ocean tides force model implementation corresponds to the method described
  34.  * in <a href="http://www.iers.org/nn_11216/IERS/EN/Publications/TechnicalNotes/tn36.html">
  35.  * IERS conventions (2010)</a>, chapter 6, section 6.3.
  36.  * </p>
  37.  * <p>
  38.  * Note that this class is <em>not</em> thread-safe, and that tides computation
  39.  * are computer intensive if repeated. So this class is really expected to
  40.  * be wrapped within a {@link
  41.  * org.orekit.forces.gravity.potential.CachedNormalizedSphericalHarmonicsProvider}
  42.  * that will both ensure thread safety and improve performances using caching.
  43.  * </p>
  44.  * @see OceanTides
  45.  * @author Luc Maisonobe
  46.  * @since 6.1
  47.  */
  48. class OceanTidesField implements NormalizedSphericalHarmonicsProvider {

  50.     /** Maximum degree. */
  51.     private final int degree;

  53.     /** Maximum order. */
  54.     private final int order;

  56.     /** Central body reference radius. */
  57.     private final double ae;

  59.     /** Central body attraction coefficient. */
  60.     private final double mu;

  62.     /** Tides model. */
  63.     private final List<OceanTidesWave> waves;

  65.     /** Object computing the fundamental arguments. */
  66.     private final FundamentalNutationArguments arguments;

  68.     /** Function computing pole tide terms (ΔC₂₁, ΔS₂₁). */
  69.     private final TimeFunction<double []> poleTideFunction;

  71.     /** Simple constructor.
  72.      * @param ae central body reference radius
  73.      * @param mu central body attraction coefficient
  74.      * @param waves ocean tides waves
  75.      * @param arguments object computing the fundamental arguments
  76.      * @param poleTideFunction function computing ocean pole tide terms (ΔC₂₁, ΔS₂₁), may be null
  77.      * @exception OrekitException if the Love numbers embedded in the
  78.      * library cannot be read
  79.      */
  80.     public OceanTidesField(final double ae, final double mu,
  81.                            final List<OceanTidesWave> waves,
  82.                            final FundamentalNutationArguments arguments,
  83.                            final TimeFunction<double []> poleTideFunction)
  84.         throws OrekitException {

  86.         // store mode parameters
  87.         this.ae  = ae;
  88.         this.mu  = mu;

  90.         // waves
  91.         this.waves = waves;
  92.         int m = 0;
  93.         int n = 0;
  94.         for (final OceanTidesWave wave : waves) {
  95.             m = FastMath.max(m, wave.getMaxDegree());
  96.             n = FastMath.max(n, wave.getMaxOrder());
  97.         }
  98.         degree = m;
  99.         order  = n;

  101.         this.arguments = arguments;

  103.         // pole tide
  104.         this.poleTideFunction = poleTideFunction;

  106.     }

  108.     /** {@inheritDoc} */
  109.     @Override
  110.     public int getMaxDegree() {
  111.         return degree;
  112.     }

  114.     /** {@inheritDoc} */
  115.     @Override
  116.     public int getMaxOrder() {
  117.         return order;
  118.     }

  120.     /** {@inheritDoc} */
  121.     @Override
  122.     public double getMu() {
  123.         return mu;
  124.     }

  126.     /** {@inheritDoc} */
  127.     @Override
  128.     public double getAe() {
  129.         return ae;
  130.     }

  132.     /** {@inheritDoc} */
  133.     @Override
  134.     public AbsoluteDate getReferenceDate() {
  135.         return AbsoluteDate.J2000_EPOCH;
  136.     }

  138.     /** {@inheritDoc} */
  139.     @Override
  140.     public double getOffset(final AbsoluteDate date) {
  141.         return date.durationFrom(AbsoluteDate.J2000_EPOCH);
  142.     }

  144.     /** {@inheritDoc} */
  145.     @Override
  146.     public TideSystem getTideSystem() {
  147.         // not really used here, but for consistency we can state that either
  148.         // we add the permanent tide or it was already in the central attraction
  149.         return TideSystem.ZERO_TIDE;
  150.     }

  152.     /** {@inheritDoc} */
  153.     @Override
  154.     @Deprecated
  155.     public double getNormalizedCnm(final double dateOffset, final int n, final int m)
  156.         throws OrekitException {
  157.         return onDate(getReferenceDate().shiftedBy(dateOffset)).getNormalizedCnm(n, m);
  158.     }

  160.     /** {@inheritDoc} */
  161.     @Override
  162.     @Deprecated
  163.     public double getNormalizedSnm(final double dateOffset, final int n, final int m)
  164.         throws OrekitException {
  165.         return onDate(getReferenceDate().shiftedBy(dateOffset)).getNormalizedSnm(n, m);
  166.     }

  168.     /** {@inheritDoc} */
  169.     @Override
  170.     public NormalizedSphericalHarmonics onDate(final AbsoluteDate date) throws OrekitException {

  172.         // computed Cnm and Snm coefficients
  173.         final double[][] cnm = new double[degree + 1][];
  174.         final double[][] snm = new double[degree + 1][];
  175.         for (int i = 0; i <= degree; ++i) {
  176.             final int m = FastMath.min(i, order) + 1;
  177.             cnm[i] = new double[m];
  178.             snm[i] = new double[m];
  179.         }

  181.         final BodiesElements bodiesElements = arguments.evaluateAll(date);
  182.         for (final OceanTidesWave wave : waves) {
  183.             wave.addContribution(bodiesElements, cnm, snm);
  184.         }

  186.         if (poleTideFunction != null && degree > 1 && order > 0) {
  187.             // add pole tide
  188.             poleTide(date, cnm, snm);
  189.         }

  191.         return new TideHarmonics(date, cnm, snm);

  193.     }

  195.     /** Update coefficients applying pole tide.
  196.      * @param date current date
  197.      * @param cnm the Cnm coefficients. Modified in place.
  198.      * @param snm the Snm coefficients. Modified in place.
  199.      */
  200.     private void poleTide(final AbsoluteDate date, final double[][] cnm, final double[][] snm) {
  201.         final double[] deltaCS = poleTideFunction.value(date);
  202.         cnm[2][1] += deltaCS[0]; // ΔC₂₁
  203.         snm[2][1] += deltaCS[1]; // ΔS₂₁
  204.     }

  206.     /** The Tidal geopotential evaluated on a specific date. */
  207.     private static class TideHarmonics implements NormalizedSphericalHarmonics {

  209.         /** evaluation date. */
  210.         private final AbsoluteDate date;

  212.         /** Cached cnm. */
  213.         private final double[][] cnm;

  215.         /** Cached snm. */
  216.         private final double[][] snm;

  218.         /** Construct the tidal harmonics on the given date.
  219.          *
  220.          * @param date of evaluation
  221.          * @param cnm the Cnm coefficients. Not copied.
  222.          * @param snm the Snm coeffiecients. Not copied.
  223.          */
  224.         private TideHarmonics(final AbsoluteDate date,
  225.                               final double[][] cnm,
  226.                               final double[][] snm) {
  227.             this.date = date;
  228.             this.cnm = cnm;
  229.             this.snm = snm;
  230.         }

  232.         /** {@inheritDoc} */
  233.         @Override
  234.         public AbsoluteDate getDate() {
  235.             return date;
  236.         }

  238.         /** {@inheritDoc} */
  239.         @Override
  240.         public double getNormalizedCnm(final int n, final int m)
  241.             throws OrekitException {
  242.             return cnm[n][m];
  243.         }

  245.         /** {@inheritDoc} */
  246.         @Override
  247.         public double getNormalizedSnm(final int n, final int m)
  248.             throws OrekitException {
  249.             return snm[n][m];
  250.         }

  252.     }

  254. }
Created with JaCoCo 0.6.3.201306030806