1 //============================================================================== 2 // 3 // This file is part of GPSTk, the GPS Toolkit. 4 // 5 // The GPSTk is free software; you can redistribute it and/or modify 6 // it under the terms of the GNU Lesser General Public License as published 7 // by the Free Software Foundation; either version 3.0 of the License, or 8 // any later version. 9 // 10 // The GPSTk is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 // GNU Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with GPSTk; if not, write to the Free Software Foundation, 17 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA 18 // 19 // This software was developed by Applied Research Laboratories at the 20 // University of Texas at Austin. 21 // Copyright 2004-2020, The Board of Regents of The University of Texas System 22 // 23 //============================================================================== 24 25 //============================================================================== 26 // 27 // This software was developed by Applied Research Laboratories at the 28 // University of Texas at Austin, under contract to an agency or agencies 29 // within the U.S. Department of Defense. The U.S. Government retains all 30 // rights to use, duplicate, distribute, disclose, or release this software. 31 // 32 // Pursuant to DoD Directive 523024 33 // 34 // DISTRIBUTION STATEMENT A: This software has been approved for public 35 // release, distribution is unlimited. 36 // 37 //============================================================================== 38 39 /// @file OceanLoadTides.hpp 40 /// Include file for classes to handle site displacement due to ocean loading. 41 42 #ifndef CLASS_OCEANLOADING_INCLUDE 43 #define CLASS_OCEANLOADING_INCLUDE 44 45 //------------------------------------------------------------------------------------ 46 // system includes 47 #include <string> 48 #include <vector> 49 #include <map> 50 // GPSTk 51 #include "Exception.hpp" 52 #include "EphTime.hpp" 53 #include "Triple.hpp" 54 55 //------------------------------------------------------------------------------------ 56 namespace gpstk { 57 58 /// Ocean loading. Computation of displacements of sites on the solid earth surface 59 /// due to ocean loading. 60 /// 61 /// The computation requires a site(Lat,Lon)-specific set of coefficients, in a flat 62 /// file with a specific format, and obtainable by a variety of methods. 63 /// Coefficients for all the ITRF sites are found at 64 /// ftp://maia.usno.navy.mil/conventions/chapter7/olls25.blq 65 /// Also, at http://www.oso.chalmers.se/~loading one may submit site label and 66 /// position for one or more sites, and the resulting ocean loading file will be 67 /// computed and emailed. 68 /// Finally, open source software package SPOTL (Some Programs for Ocean Load Tides) 69 /// is available from http://igppweb.ucsd.edu/~agnew/Spotl/spotlmain.html. 70 /// This software will compute the coefficients and output the file, with a variety 71 /// of options. 72 /// 73 /// Once a file is obtained for the site of choice, this object is initialized by 74 /// calling initializeSites(), passing it the file name an a list of the sites for 75 /// which computations will later be desired. The function isValid() returns true 76 /// when a given site has been initialized. The function computeDisplacement() will 77 /// compute the site displacement vector at any time for any initialized site. 78 /// 79 class OceanLoadTides { 80 public: 81 /// Constructor OceanLoadTides()82 OceanLoadTides() {}; 83 84 /// Open and read the given file, containing ocean loading coefficients, and 85 /// initialize this object for the sites names in the input list that match a 86 /// name in the file (case sensitive, may contain embedded whitespace). 87 /// Return the number of successfully initialized site names, and remove those 88 /// sites from the input list. Convert coefficients from degrees to radians. 89 /// Ocean loading files can be obtained from the web. For example all the ITRF 90 /// sites are found at ftp://maia.usno.navy.mil/conventions/chapter7/olls25.blq 91 /// Also, at http://www.oso.chalmers.se/~loading one may submit site label and 92 /// position for one or more sites, and the resulting ocean loading file will be 93 /// emailed. 94 /// @param sites vector<string> On input contains site labels found in the 95 /// file, on output contains only sites that were NOT found. 96 /// If empty, all sites are read. 97 /// @param filename string Input ocean loading file name. 98 /// @return the number of sites successfully initialized. 99 /// @throw Exception if the file could not be opened. 100 int initializeSites(std::vector<std::string>& sites, std::string filename); 101 102 /// Return true if the given site name has been initialized, otherwise false. isValid(std::string site)103 bool isValid(std::string site) throw() 104 { return (coefficientMap.find(site) != coefficientMap.end()); } 105 106 /// Compute the site displacement vector at the given time for the given site. 107 /// Use the 11-tide (simple) model. 108 /// The site must have been successfully initialized; if not an exception is 109 /// thrown. 110 /// @param site string Input name of the site; must be the same as previously 111 /// successfully passed to initializeSites(). 112 /// @param t EphTime Input time of interest. 113 /// @return Triple containing the North, East and Up components of the site 114 /// displacement in meters. 115 /// @throw Exception if the site has not been initialized. 116 Triple computeDisplacement11(std::string site, EphTime t); 117 118 /// Compute the site displacement vector at the given time for the given site. 119 /// The site must have been successfully initialized; if not an exception is 120 /// thrown. Based on IERS routine HARDISP.F 121 /// @param site string Input name of the site; must be the same as previously 122 /// successfully passed to initializeSites(). 123 /// @param t EphTime Input time of interest. 124 /// @return Triple containing the North, East and Up components of the site 125 /// displacement in meters. 126 /// @throw Exception if the site has not been initialized, if the time system is unknown, 127 /// if there is corruption in the static arrays, or . 128 Triple computeDisplacement(std::string site, EphTime t); 129 130 /// Return the recorded latitude, longitude and ht(=0) for the given site. 131 /// Return value of (0.0,0.0,0.0) probably means the position was not found. getPosition(std::string site)132 Triple getPosition(std::string site) throw() 133 { 134 Triple t(0.0,0.0,0.0); 135 std::map<std::string, std::vector<double> >::const_iterator it; 136 it = positionMap.find(site); 137 if(it != positionMap.end()) { 138 t[0] = it->second[0]; 139 t[1] = it->second[1]; 140 } 141 return t; 142 } 143 144 private: 145 // Compute the astronomical angular arguments for each of the 11 tidal modes. 146 // Ref IERS 1996 pg 53. 147 //void SchwiderskiArg(int iyear, int doy, double sod, double* angles) throw(); 148 149 /// map of (site name, coefficient array), created by call to initializeSites() 150 std::map<std::string, std::vector<double> > coefficientMap; 151 152 /// map of (site name,2-element array lat,lon), created by initializeSites() 153 std::map<std::string, std::vector<double> > positionMap; 154 155 /// Used for convenience by computeDisplacements 156 typedef struct { int n[6]; } NVector; 157 158 /// Number of standard (Schwiderski) tides read from BLQ file 159 static const int NSTD; 160 161 /// Number of derived tides computed by deriveTides() 162 static const int NDER; 163 164 /// Derive the 342 tides from the standard 11 tides using cubic spline 165 /// interpolation. Called by computeDisplacements() 166 /// @param SchTides array of 11 NVectors (int[6]) with for standard tides 167 /// @param amp array of 11 amplitudes from BLQ file 168 /// @param phs array of 11 phases from BLQ file 169 /// @param Dood array of 6 Doodson arguments at time t in degrees 170 /// @param freqDood array of 6 Doodson frequencies at time in cycles/day 171 /// @param ampDer array of nout (up to 342) amplitudes of the derived tides 172 /// @param phsDer array of nout (up to 342) phases of the derived tides 173 /// @param freq array of nout (up to 342) frequencies of the derived tides 174 /// @param Nin number of std tides (11) 175 /// @return nout number of derived tides actually computed, may be < 342 176 /// @throw Exception if static arrays are corrupted. 177 int deriveTides(const NVector SchTides[], const double amp[], const double phs[], 178 const double Dood[], const double freqDood[], 179 double ampDer[], double phsDer[], double freq[], const int Nin); 180 181 }; // end class OceanLoadTides 182 183 } // end namespace gpstk 184 185 #endif // nothing below this 186