GravityFieldFactory.java

  1. /* Copyright 2002-2018 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;

  19. import java.util.ArrayList;
  20. import java.util.List;
  21. import java.util.Map;

  23. import org.hipparchus.util.FastMath;
  24. import org.hipparchus.util.Precision;
  25. import org.orekit.data.DataProvidersManager;
  26. import org.orekit.errors.OrekitException;
  27. import org.orekit.errors.OrekitMessages;

  29. /** Factory used to read gravity field files in several supported formats.
  30.  * @author Fabien Maussion
  31.  * @author Pascal Parraud
  32.  * @author Luc Maisonobe
  33.  */
  34. public class GravityFieldFactory {

  36.     /** Default regular expression for ICGEM files. */
  37.     public static final String ICGEM_FILENAME = "^(.*\\.gfc)|(g(\\d)+_eigen[-_](\\w)+_coef)$";

  39.     /** Default regular expression for SHM files. */
  40.     public static final String SHM_FILENAME = "^eigen[-_](\\w)+_coef$";

  42.     /** Default regular expression for EGM files. */
  43.     public static final String EGM_FILENAME = "^egm\\d\\d_to\\d.*$";

  45.     /** Default regular expression for GRGS files. */
  46.     public static final String GRGS_FILENAME = "^grim\\d_.*$";

  48.     /** Default regular expression for FES Cnm, Snm tides files. */
  49.     public static final String FES_CNM_SNM_FILENAME = "^fes(\\d)+_Cnm-Snm.dat$";

  51.     /** Default regular expression for FES C hat and epsilon tides files. */
  52.     public static final String FES_CHAT_EPSILON_FILENAME = "^fes(\\d)+.dat$";

  54.     /** Default regular expression for FES Hf tides files. */
  55.     public static final String FES_HF_FILENAME = "^hf-fes(\\d)+.dat$";

  57.     /** Potential readers. */
  58.     private static final List<PotentialCoefficientsReader> READERS =
  59.         new ArrayList<PotentialCoefficientsReader>();

  61.     /** Ocean tides readers. */
  62.     private static final List<OceanTidesReader> OCEAN_TIDES_READERS =
  63.         new ArrayList<OceanTidesReader>();

  65.     /** Ocean load deformation coefficients. */
  66.     private static OceanLoadDeformationCoefficients OCEAN_LOAD_DEFORMATION_COEFFICIENTS =
  67.         OceanLoadDeformationCoefficients.IERS_2010;

  69.     /** Private constructor.
  70.      * <p>This class is a utility class, it should neither have a public
  71.      * nor a default constructor. This private constructor prevents
  72.      * the compiler from generating one automatically.</p>
  73.      */
  74.     private GravityFieldFactory() {
  75.     }

  77.     /** Add a reader for gravity fields.
  78.      * @param reader custom reader to add for the gravity field
  79.      * @see #addDefaultPotentialCoefficientsReaders()
  80.      * @see #clearPotentialCoefficientsReaders()
  81.      */
  82.     public static void addPotentialCoefficientsReader(final PotentialCoefficientsReader reader) {
  83.         synchronized (READERS) {
  84.             READERS.add(reader);
  85.         }
  86.     }

  88.     /** Add the default readers for gravity fields.
  89.      * <p>
  90.      * The default READERS supports ICGEM, SHM, EGM and GRGS formats with the
  91.      * default names {@link #ICGEM_FILENAME}, {@link #SHM_FILENAME}, {@link
  92.      * #EGM_FILENAME}, {@link #GRGS_FILENAME} and don't allow missing coefficients.
  93.      * </p>
  94.      * @see #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  95.      * @see #clearPotentialCoefficientsReaders()
  96.      */
  97.     public static void addDefaultPotentialCoefficientsReaders() {
  98.         synchronized (READERS) {
  99.             READERS.add(new ICGEMFormatReader(ICGEM_FILENAME, false));
  100.             READERS.add(new SHMFormatReader(SHM_FILENAME, false));
  101.             READERS.add(new EGMFormatReader(EGM_FILENAME, false));
  102.             READERS.add(new GRGSFormatReader(GRGS_FILENAME, false));
  103.         }
  104.     }

  106.     /** Clear gravity field readers.
  107.      * @see #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  108.      * @see #addDefaultPotentialCoefficientsReaders()
  109.      */
  110.     public static void clearPotentialCoefficientsReaders() {
  111.         synchronized (READERS) {
  112.             READERS.clear();
  113.         }
  114.     }

  116.     /** Add a reader for ocean tides.
  117.      * @param reader custom reader to add for the gravity field
  118.      * @see #addDefaultPotentialCoefficientsReaders()
  119.      * @see #clearPotentialCoefficientsReaders()
  120.      */
  121.     public static void addOceanTidesReader(final OceanTidesReader reader) {
  122.         synchronized (OCEAN_TIDES_READERS) {
  123.             OCEAN_TIDES_READERS.add(reader);
  124.         }
  125.     }

  127.     /** Configure ocean load deformation coefficients.
  128.      * @param oldc ocean load deformation coefficients
  129.      * @see #getOceanLoadDeformationCoefficients()
  130.      */
  131.     public static void configureOceanLoadDeformationCoefficients(final OceanLoadDeformationCoefficients oldc) {
  132.         OCEAN_LOAD_DEFORMATION_COEFFICIENTS = oldc;
  133.     }

  135.     /** Get the configured ocean load deformation coefficients.
  136.      * <p>
  137.      * If {@link #configureOceanLoadDeformationCoefficients(OceanLoadDeformationCoefficients)
  138.      * configureOceanLoadDeformationCoefficients} has never been called, the default
  139.      * value will be the {@link OceanLoadDeformationCoefficients#IERS_2010 IERS 2010}
  140.      * coefficients.
  141.      * </p>
  142.      * @return ocean load deformation coefficients
  143.      * @see #configureOceanLoadDeformationCoefficients(OceanLoadDeformationCoefficients)
  144.      */
  145.     public static OceanLoadDeformationCoefficients getOceanLoadDeformationCoefficients() {
  146.         return OCEAN_LOAD_DEFORMATION_COEFFICIENTS;
  147.     }

  149.     /** Add the default READERS for ocean tides.
  150.      * <p>
  151.      * The default READERS supports files similar to the fes2004_Cnm-Snm.dat and
  152.      * fes2004.dat as published by IERS, using the {@link
  153.      * #configureOceanLoadDeformationCoefficients(OceanLoadDeformationCoefficients)
  154.      * configured} ocean load deformation coefficients, which by default are the
  155.      * IERS 2010 coefficients, which are limited to degree 6. If higher degree
  156.      * coefficients are needed, the {@link
  157.      * #configureOceanLoadDeformationCoefficients(OceanLoadDeformationCoefficients)
  158.      * configureOceanLoadDeformationCoefficients} method can be called prior to
  159.      * loading the ocean tides model with the {@link
  160.      * OceanLoadDeformationCoefficients#GEGOUT high degree coefficients} computed
  161.      * by Pascal Gégout.
  162.      * </p>
  163.      * <p>
  164.      * WARNING: the files referenced in the published conventions have some errors.
  165.      * These errors have been corrected and the updated files can be found here:
  166.      * <a href="http://tai.bipm.org/iers/convupdt/convupdt_c6.html">
  167.      * http://tai.bipm.org/iers/convupdt/convupdt_c6.html</a>.
  168.      * </p>
  169.      * @exception OrekitException if astronomical amplitudes cannot be read
  170.      * @see #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  171.      * @see #clearPotentialCoefficientsReaders()
  172.      * @see #configureOceanLoadDeformationCoefficients(OceanLoadDeformationCoefficients)
  173.      * @see #getOceanLoadDeformationCoefficients()
  174.      */
  175.     public static void addDefaultOceanTidesReaders()
  176.         throws OrekitException {
  177.         synchronized (OCEAN_TIDES_READERS) {

  179.             OCEAN_TIDES_READERS.add(new FESCnmSnmReader(FES_CNM_SNM_FILENAME, 1.0e-11));

  181.             final AstronomicalAmplitudeReader aaReader =
  182.                     new AstronomicalAmplitudeReader(FES_HF_FILENAME, 5, 2, 3, 1.0);
  183.             DataProvidersManager.getInstance().feed(aaReader.getSupportedNames(), aaReader);
  184.             final Map<Integer, Double> map = aaReader.getAstronomicalAmplitudesMap();
  185.             OCEAN_TIDES_READERS.add(new FESCHatEpsilonReader(FES_CHAT_EPSILON_FILENAME,
  186.                                                              0.01, FastMath.toRadians(1.0),
  187.                                                              getOceanLoadDeformationCoefficients(),
  188.                                                              map));


  191.         }
  192.     }

  194.     /** Clear ocean tides readers.
  195.      * @see #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  196.      * @see #addDefaultPotentialCoefficientsReaders()
  197.      */
  198.     public static void clearOceanTidesReaders() {
  199.         synchronized (OCEAN_TIDES_READERS) {
  200.             OCEAN_TIDES_READERS.clear();
  201.         }
  202.     }

  204.     /** Get the constant gravity field coefficients provider from the first supported file.
  205.      * <p>
  206.      * If no {@link PotentialCoefficientsReader} has been added by calling {@link
  207.      * #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  208.      * addPotentialCoefficientsReader} or if {@link #clearPotentialCoefficientsReaders()
  209.      * clearPotentialCoefficientsReaders} has been called afterwards, the {@link
  210.      * #addDefaultPotentialCoefficientsReaders() addDefaultPotentialCoefficientsReaders}
  211.      * method will be called automatically.
  212.      * </p>
  213.      * @param degree maximal degree
  214.      * @param order maximal order
  215.      * @return a gravity field coefficients provider containing already loaded data
  216.      * @exception OrekitException if some data can't be read (missing or read error)
  217.      * or if some loader specific error occurs
  218.      * @since 6.0
  219.      * @see #getNormalizedProvider(int, int)
  220.      */
  221.     public static NormalizedSphericalHarmonicsProvider getConstantNormalizedProvider(final int degree,
  222.                                                                                      final int order)
  223.         throws OrekitException {
  224.         final PotentialCoefficientsReader reader = readGravityField(degree, order);
  225.         final RawSphericalHarmonicsProvider provider = reader.getConstantProvider(true, degree, order);
  226.         return new WrappingNormalizedProvider(provider);
  227.     }

  229.     /** Get the gravity field coefficients provider from the first supported file.
  230.      * <p>
  231.      * If no {@link PotentialCoefficientsReader} has been added by calling {@link
  232.      * #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  233.      * addPotentialCoefficientsReader} or if {@link #clearPotentialCoefficientsReaders()
  234.      * clearPotentialCoefficientsReaders} has been called afterwards, the {@link
  235.      * #addDefaultPotentialCoefficientsReaders() addDefaultPotentialCoefficientsReaders}
  236.      * method will be called automatically.
  237.      * </p>
  238.      * @param degree maximal degree
  239.      * @param order maximal order
  240.      * @return a gravity field coefficients provider containing already loaded data
  241.      * @exception OrekitException if some data can't be read (missing or read error)
  242.      * or if some loader specific error occurs
  243.      * @since 6.0
  244.      * @see #getConstantNormalizedProvider(int, int)
  245.      */
  246.     public static NormalizedSphericalHarmonicsProvider getNormalizedProvider(final int degree,
  247.                                                                              final int order)
  248.         throws OrekitException {
  249.         final PotentialCoefficientsReader reader = readGravityField(degree, order);
  250.         final RawSphericalHarmonicsProvider provider = reader.getProvider(true, degree, order);
  251.         return new WrappingNormalizedProvider(provider);
  252.     }

  254.     /** Create a time-independent {@link NormalizedSphericalHarmonicsProvider} from canonical coefficients.
  255.      * <p>
  256.      * Note that contrary to the other factory method, this one does not read any data, it simply uses
  257.      * the provided data
  258.      * </p>
  259.      * @param ae central body reference radius
  260.      * @param mu central body attraction coefficient
  261.      * @param tideSystem tide system
  262.      * @param normalizedC normalized tesseral-sectorial coefficients (cosine part)
  263.      * @param normalizedS normalized tesseral-sectorial coefficients (sine part)
  264.      * @return provider for normalized coefficients
  265.      * @since 6.0
  266.      */
  267.     public static NormalizedSphericalHarmonicsProvider getNormalizedProvider(final double ae, final double mu,
  268.                                                                              final TideSystem tideSystem,
  269.                                                                              final double[][] normalizedC,
  270.                                                                              final double[][] normalizedS) {
  271.         return new WrappingNormalizedProvider(new ConstantSphericalHarmonics(ae, mu, tideSystem,
  272.                                                                              normalizedC, normalizedS));
  273.     }

  275.     /** Create a {@link NormalizedSphericalHarmonicsProvider} from an {@link UnnormalizedSphericalHarmonicsProvider}.
  276.      * <p>
  277.      * Note that contrary to the other factory method, this one does not read any data, it simply uses
  278.      * the provided data.
  279.      * </p>
  280.      * @param unnormalized provider to normalize
  281.      * @return provider for normalized coefficients
  282.      * @exception OrekitException if degree and order are too large
  283.      * and the normalization coefficients underflow
  284.      * @since 6.0
  285.      */
  286.     public static NormalizedSphericalHarmonicsProvider getNormalizedProvider(final UnnormalizedSphericalHarmonicsProvider unnormalized)
  287.         throws OrekitException {
  288.         return new Normalizer(unnormalized);
  289.     }

  291.     /** Get the constant gravity field coefficients provider from the first supported file.
  292.      * <p>
  293.      * If no {@link PotentialCoefficientsReader} has been added by calling {@link
  294.      * #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  295.      * addPotentialCoefficientsReader} or if {@link #clearPotentialCoefficientsReaders()
  296.      * clearPotentialCoefficientsReaders} has been called afterwards, the {@link
  297.      * #addDefaultPotentialCoefficientsReaders() addDefaultPotentialCoefficientsReaders}
  298.      * method will be called automatically.
  299.      * </p>
  300.      * @param degree maximal degree
  301.      * @param order maximal order
  302.      * @return a gravity field coefficients provider containing already loaded data
  303.      * @exception OrekitException if some data can't be read (missing or read error)
  304.      * or if some loader specific error occurs
  305.      * @since 6.0
  306.      * @see #getUnnormalizedProvider(int, int)
  307.      */
  308.     public static UnnormalizedSphericalHarmonicsProvider getConstantUnnormalizedProvider(final int degree,
  309.                                                                                          final int order)
  310.         throws OrekitException {
  311.         final PotentialCoefficientsReader reader = readGravityField(degree, order);
  312.         final RawSphericalHarmonicsProvider provider = reader.getConstantProvider(false, degree, order);
  313.         return new WrappingUnnormalizedProvider(provider);
  314.     }

  316.     /** Get the gravity field coefficients provider from the first supported file.
  317.      * <p>
  318.      * If no {@link PotentialCoefficientsReader} has been added by calling {@link
  319.      * #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  320.      * addPotentialCoefficientsReader} or if {@link #clearPotentialCoefficientsReaders()
  321.      * clearPotentialCoefficientsReaders} has been called afterwards, the {@link
  322.      * #addDefaultPotentialCoefficientsReaders() addDefaultPotentialCoefficientsReaders}
  323.      * method will be called automatically.
  324.      * </p>
  325.      * @param degree maximal degree
  326.      * @param order maximal order
  327.      * @return a gravity field coefficients provider containing already loaded data
  328.      * @exception OrekitException if some data can't be read (missing or read error)
  329.      * or if some loader specific error occurs
  330.      * @since 6.0
  331.      * @see #getConstantUnnormalizedProvider(int, int)
  332.      */
  333.     public static UnnormalizedSphericalHarmonicsProvider getUnnormalizedProvider(final int degree,
  334.                                                                                  final int order)
  335.         throws OrekitException {
  336.         final PotentialCoefficientsReader reader = readGravityField(degree, order);
  337.         final RawSphericalHarmonicsProvider provider = reader.getProvider(false, degree, order);
  338.         return new WrappingUnnormalizedProvider(provider);
  339.     }

  341.     /** Create a time-independent {@link UnnormalizedSphericalHarmonicsProvider} from canonical coefficients.
  342.      * <p>
  343.      * Note that contrary to the other factory method, this one does not read any data, it simply uses
  344.      * the provided data
  345.      * </p>
  346.      * @param ae central body reference radius
  347.      * @param mu central body attraction coefficient
  348.      * @param tideSystem tide system
  349.      * @param unnormalizedC un-normalized tesseral-sectorial coefficients (cosine part)
  350.      * @param unnormalizedS un-normalized tesseral-sectorial coefficients (sine part)
  351.      * @return provider for un-normalized coefficients
  352.      * @since 6.0
  353.      */
  354.     public static UnnormalizedSphericalHarmonicsProvider getUnnormalizedProvider(final double ae, final double mu,
  355.                                                                                  final TideSystem tideSystem,
  356.                                                                                  final double[][] unnormalizedC,
  357.                                                                                  final double[][] unnormalizedS) {
  358.         return new WrappingUnnormalizedProvider(new ConstantSphericalHarmonics(ae, mu, tideSystem,
  359.                                                                                unnormalizedC, unnormalizedS));
  360.     }

  362.     /** Create an {@link UnnormalizedSphericalHarmonicsProvider} from a {@link NormalizedSphericalHarmonicsProvider}.
  363.      * <p>
  364.      * Note that contrary to the other factory method, this one does not read any data, it simply uses
  365.      * the provided data.
  366.      * </p>
  367.      * @param normalized provider to un-normalize
  368.      * @return provider for un-normalized coefficients
  369.      * @exception OrekitException if degree and order are too large
  370.      * and the un-normalization coefficients underflow
  371.      * @since 6.0
  372.      */
  373.     public static UnnormalizedSphericalHarmonicsProvider getUnnormalizedProvider(final NormalizedSphericalHarmonicsProvider normalized)
  374.         throws OrekitException {
  375.         return new Unnormalizer(normalized);
  376.     }

  378.     /** Read a gravity field coefficients provider from the first supported file.
  379.      * <p>
  380.      * If no {@link PotentialCoefficientsReader} has been added by calling {@link
  381.      * #addPotentialCoefficientsReader(PotentialCoefficientsReader)
  382.      * addPotentialCoefficientsReader} or if {@link #clearPotentialCoefficientsReaders()
  383.      * clearPotentialCoefficientsReaders} has been called afterwards, the {@link
  384.      * #addDefaultPotentialCoefficientsReaders() addDefaultPotentialCoefficientsReaders}
  385.      * method will be called automatically.
  386.      * </p>
  387.      * @param maxParseDegree maximal degree to parse
  388.      * @param maxParseOrder maximal order to parse
  389.      * @return a reader containing already loaded data
  390.      * @exception OrekitException if some data is missing
  391.      * or if some loader specific error occurs
  392.      * @since 6.0
  393.      */
  394.     public static PotentialCoefficientsReader readGravityField(final int maxParseDegree,
  395.                                                                final int maxParseOrder)
  396.         throws OrekitException {

  398.         synchronized (READERS) {

  400.             if (READERS.isEmpty()) {
  401.                 addDefaultPotentialCoefficientsReaders();
  402.             }

  404.             // test the available readers
  405.             for (final PotentialCoefficientsReader reader : READERS) {
  406.                 reader.setMaxParseDegree(maxParseDegree);
  407.                 reader.setMaxParseOrder(maxParseOrder);
  408.                 DataProvidersManager.getInstance().feed(reader.getSupportedNames(), reader);
  409.                 if (!reader.stillAcceptsData()) {
  410.                     return reader;
  411.                 }
  412.             }
  413.         }

  415.         throw new OrekitException(OrekitMessages.NO_GRAVITY_FIELD_DATA_LOADED);

  417.     }

  419.     /** Get a un-normalization factors array.
  420.      * <p>
  421.      * Un-normalized coefficients are obtained by multiplying normalized
  422.      * coefficients by the factors array elements.
  423.      * </p>
  424.      * @param degree maximal degree
  425.      * @param order maximal order
  426.      * @return triangular un-normalization factors array
  427.      * @exception OrekitException if degree and order are too large
  428.      * and the latest coefficients underflow
  429.      * @since 6.0
  430.      */
  431.     public static double[][] getUnnormalizationFactors(final int degree, final int order)
  432.         throws OrekitException {

  434.         // allocate a triangular array
  435.         final int rows = degree + 1;
  436.         final double[][] factor = new double[rows][];
  437.         factor[0] = new double[] {
  438.             1.0
  439.         };

  441.         // compute the factors
  442.         for (int n = 1; n <= degree; n++) {
  443.             final double[] row = new double[FastMath.min(n, order) + 1];
  444.             row[0] = FastMath.sqrt(2 * n + 1);
  445.             double coeff = 2.0 * (2 * n + 1);
  446.             for (int m = 1; m < row.length; m++) {
  447.                 coeff /= (n - m + 1) * (n + m);
  448.                 row[m] = FastMath.sqrt(coeff);
  449.                 if (row[m] < Precision.SAFE_MIN) {
  450.                     throw new OrekitException(OrekitMessages.GRAVITY_FIELD_NORMALIZATION_UNDERFLOW,
  451.                                               n, m);
  452.                 }
  453.             }
  454.             factor[n] = row;
  455.         }

  457.         return factor;

  459.     }

  461.     /** Get the ocean tides waves from the first supported file.
  462.      * <p>
  463.      * If no {@link OceanTidesReader} has been added by calling {@link
  464.      * #addOceanTidesReader(OceanTidesReader)
  465.      * addOceanTidesReader} or if {@link #clearOceanTidesReaders()
  466.      * clearOceanTidesReaders} has been called afterwards, the {@link
  467.      * #addDefaultOceanTidesReaders() addDefaultOceanTidesReaders}
  468.      * method will be called automatically.
  469.      * </p>
  470.      * <p><span style="color:red">
  471.      * WARNING: as of 2013-11-17, there seem to be an inconsistency when loading
  472.      * one or the other file, for wave Sa (Doodson number 56.554) and P1 (Doodson
  473.      * number 163.555). The sign of the coefficients are different. We think the
  474.      * problem lies in the input files from IERS and not in the conversion (which
  475.      * works for all other waves), but cannot be sure. For this reason, ocean
  476.      * tides are still considered experimental at this date.
  477.      * </span></p>
  478.      * @param degree maximal degree
  479.      * @param order maximal order
  480.      * @return list of tides waves containing already loaded data
  481.      * @exception OrekitException if some data can't be read (missing or read error)
  482.      * or if some loader specific error occurs
  483.      * @since 6.1
  484.      */
  485.     public static List<OceanTidesWave> getOceanTidesWaves(final int degree, final int order)
  486.         throws OrekitException {

  488.         synchronized (OCEAN_TIDES_READERS) {

  490.             if (OCEAN_TIDES_READERS.isEmpty()) {
  491.                 addDefaultOceanTidesReaders();
  492.             }

  494.             // test the available readers
  495.             for (final OceanTidesReader reader : OCEAN_TIDES_READERS) {
  496.                 reader.setMaxParseDegree(degree);
  497.                 reader.setMaxParseOrder(order);
  498.                 DataProvidersManager.getInstance().feed(reader.getSupportedNames(), reader);
  499.                 if (!reader.stillAcceptsData()) {
  500.                     return reader.getWaves();
  501.                 }
  502.             }
  503.         }

  505.         throw new OrekitException(OrekitMessages.NO_OCEAN_TIDE_DATA_LOADED);

  507.     }

  509. }
Created with JaCoCo 0.7.9.201702052155