GeomagnetismHeader.h
Go to the documentation of this file.
00001 /*      WMM Subroutine library was tested in the following environments
00002  *
00003  *      1. Red Hat Linux  with GCC Compiler
00004  *      2. MS Windows XP with CodeGear C++ compiler
00005  *      3. Sun Solaris with GCC Compiler
00006  *
00007  *
00008  *      Revision Number: $Revision: 833 $
00009  *      Last changed by: $Author: awoods $
00010  *      Last changed on: $Date: 2012-04-16 14:01:51 -0600 (Mon, 16 Apr 2012) $
00011  *
00012  *
00013  */
00014 
00015 
00016 #ifndef _POSIX_C_SOURCE
00017 #define _POSIX_C_SOURCE
00018 #endif
00019 
00020 //#ifndef EPOCHRANGE
00021 //#define EPOCHRANGE (int)5
00022 //#endif
00023 
00024 #define READONLYMODE "r"
00025 #define MAXLINELENGTH (1024)
00026 #define NOOFPARAMS (15)
00027 #define NOOFCOEFFICIENTS (7)
00028 
00029 
00030 #define _DEGREE_NOT_FOUND (-2)
00031 #define CALCULATE_NUMTERMS(N)    (N * ( N + 1 ) / 2 + N)
00032 
00033 #ifndef WMMHEADER_H
00034 #define WMMHEADER_H
00035 
00036 #ifndef M_PI
00037 #define M_PI    ((2)*(acos(0.0)))
00038 #endif
00039 
00040 #define RAD2DEG(rad)    ((rad)*(180.0L/M_PI))
00041 #define DEG2RAD(deg)    ((deg)*(M_PI/180.0L))
00042 #define ATanH(x)            (0.5 * log((1 + x) / (1 - x)))
00043 
00044 
00045 #define TRUE            ((int)1)
00046 #define FALSE           ((int)0)
00047 
00048 
00049 
00050 
00051 #define MAG_PS_MIN_LAT_DEGREE  -55 /* Minimum Latitude for  Polar Stereographic projection in degrees   */
00052 #define MAG_PS_MAX_LAT_DEGREE  55  /* Maximum Latitude for Polar Stereographic projection in degrees     */
00053 #define MAG_UTM_MIN_LAT_DEGREE -80.5  /* Minimum Latitude for UTM projection in degrees   */
00054 #define MAG_UTM_MAX_LAT_DEGREE  84.5  /* Maximum Latitude for UTM projection in degrees     */
00055 
00056 #define MAG_GEO_POLE_TOLERANCE  1e-5
00057 #define MAG_USE_GEOID   1    /* 1 Geoid - Ellipsoid difference should be corrected, 0 otherwise */
00058 
00059 /*
00060 Data types and prototype declaration for
00061 World Magnetic Model (WMM) subroutines.
00062 
00063 July 28, 2009
00064 
00065 manoj.c.nair@noaa.gov*/
00066 
00067 
00068 typedef struct {
00069     double EditionDate;
00070     double epoch; //Base time of Geomagnetic model epoch (yrs)
00071     char ModelName[32];
00072     double *Main_Field_Coeff_G; // C - Gauss coefficients of main geomagnetic model (nT)
00073     double *Main_Field_Coeff_H; // C - Gauss coefficients of main geomagnetic model (nT)
00074     double *Secular_Var_Coeff_G; // CD - Gauss coefficients of secular geomagnetic model (nT/yr)
00075     double *Secular_Var_Coeff_H; // CD - Gauss coefficients of secular geomagnetic model (nT/yr)
00076     int nMax; // Maximum degree of spherical harmonic model
00077     int nMaxSecVar; //Maxumum degree of spherical harmonic secular model
00078     int SecularVariationUsed; //Whether or not the magnetic secular variation vector will be needed by program
00079     double CoefficientFileEndDate; //
00080 } MAGtype_MagneticModel;
00081 
00082 typedef struct {
00083     double a; /*semi-major axis of the ellipsoid*/
00084     double b; /*semi-minor axis of the ellipsoid*/
00085     double fla; /* flattening */
00086     double epssq; /*first eccentricity squared */
00087     double eps; /* first eccentricity */
00088     double re; /* mean radius of  ellipsoid*/
00089 } MAGtype_Ellipsoid;
00090 
00091 typedef struct {
00092     double lambda; // longitude
00093     double phi; // geodetic latitude
00094     double HeightAboveEllipsoid; // height above the ellipsoid (HaE)
00095     double HeightAboveGeoid; /* (height above the EGM96 geoid model ) */
00096     int UseGeoid;
00097 } MAGtype_CoordGeodetic;
00098 
00099 typedef struct {
00100     double lambda; /* longitude*/
00101     double phig; /* geocentric latitude*/
00102     double r; /* distance from the center of the ellipsoid*/
00103 } MAGtype_CoordSpherical;
00104 
00105 typedef struct {
00106     int Year;
00107     int Month;
00108     int Day;
00109     double DecimalYear; /* decimal years */
00110 } MAGtype_Date;
00111 
00112 /*typedef struct { 
00113     int MAG_Mercator;
00114     int MAG_LambertConformalConic;
00115     int MAG_PolarStereographic;
00116     int MAG_TransverseMercator;
00117 } MAGtype_MapProjectionCode; 
00118  Deprecated, Will be removed in the next revision.*/
00119 
00120 typedef struct {
00121     double *Pcup; /* Legendre Function */
00122     double *dPcup; /* Derivative of Legendre fcn */
00123 } MAGtype_LegendreFunction;
00124 
00125 typedef struct {
00126     double Bx; /* North */
00127     double By; /* East */
00128     double Bz; /* Down */
00129 } MAGtype_MagneticResults;
00130 
00131 typedef struct {
00132     double *RelativeRadiusPower; /* [earth_reference_radius_km / sph. radius ]^n  */
00133     double *cos_mlambda; /*cp(m)  - cosine of (m*spherical coord. longitude)*/
00134     double *sin_mlambda; /* sp(m)  - sine of (m*spherical coord. longitude) */
00135 } MAGtype_SphericalHarmonicVariables;
00136 
00137 typedef struct {
00138     double Decl; /* 1. Angle between the magnetic field vector and true north, positive east*/
00139     double Incl; /*2. Angle between the magnetic field vector and the horizontal plane, positive down*/
00140     double F; /*3. Magnetic Field Strength*/
00141     double H; /*4. Horizontal Magnetic Field Strength*/
00142     double X; /*5. Northern component of the magnetic field vector*/
00143     double Y; /*6. Eastern component of the magnetic field vector*/
00144     double Z; /*7. Downward component of the magnetic field vector*/
00145     double GV; /*8. The Grid Variation*/
00146     double Decldot; /*9. Yearly Rate of change in declination*/
00147     double Incldot; /*10. Yearly Rate of change in inclination*/
00148     double Fdot; /*11. Yearly rate of change in Magnetic field strength*/
00149     double Hdot; /*12. Yearly rate of change in horizontal field strength*/
00150     double Xdot; /*13. Yearly rate of change in the northern component*/
00151     double Ydot; /*14. Yearly rate of change in the eastern component*/
00152     double Zdot; /*15. Yearly rate of change in the downward component*/
00153     double GVdot; /*16. Yearly rate of change in grid variation*/
00154 } MAGtype_GeoMagneticElements;
00155 
00156 typedef struct {
00157     int NumbGeoidCols; /* 360 degrees of longitude at 15 minute spacing */
00158     int NumbGeoidRows; /* 180 degrees of latitude  at 15 minute spacing */
00159     int NumbHeaderItems; /* min, max lat, min, max long, lat, long spacing*/
00160     int ScaleFactor; /* 4 grid cells per degree at 15 minute spacing  */
00161     float *GeoidHeightBuffer;
00162     int NumbGeoidElevs;
00163     int Geoid_Initialized; /* indicates successful initialization */
00164     int UseGeoid; /*Is the Geoid being used?*/
00165 } MAGtype_Geoid;
00166 
00167 typedef struct {
00168     char Longitude[40];
00169     char Latitude[40];
00170 } MAGtype_CoordGeodeticStr;
00171 
00172 typedef struct {
00173     double Easting; /* (X) in meters*/
00174     double Northing; /* (Y) in meters */
00175     int Zone; /*UTM Zone*/
00176     char HemiSphere;
00177     double CentralMeridian;
00178     double ConvergenceOfMeridians;
00179     double PointScale;
00180 } MAGtype_UTMParameters;
00181 
00182 enum PARAMS {
00183     SHDF,
00184     MODELNAME,
00185     PUBLISHER,
00186     RELEASEDATE,
00187     DATACUTOFF,
00188     MODELSTARTYEAR,
00189     MODELENDYEAR,
00190     EPOCH,
00191     INTSTATICDEG,
00192     INTSECVARDEG,
00193     EXTSTATICDEG,
00194     EXTSECVARDEG,
00195     GEOMAGREFRAD,
00196     NORMALIZATION,
00197     SPATBASFUNC
00198 };
00199 
00200 enum COEFFICIENTS {
00201     IE,
00202     N,
00203     M,
00204     GNM,
00205     HNM,
00206     DGNM,
00207     DHNM
00208 };
00209 
00210 enum YYYYMMDD {
00211     YEAR,
00212     MONTH,
00213     DAY
00214 };
00215 
00216 /*Prototypes */
00217 
00218 /*Wrapper Functions*/
00219 int MAG_Geomag(MAGtype_Ellipsoid Ellip,
00220         MAGtype_CoordSpherical CoordSpherical,
00221         MAGtype_CoordGeodetic CoordGeodetic,
00222         MAGtype_MagneticModel *TimedMagneticModel,
00223         MAGtype_GeoMagneticElements *GeoMagneticElements);
00224 
00225 int MAG_Grid(MAGtype_CoordGeodetic minimum,
00226         MAGtype_CoordGeodetic maximum,
00227         double step_size,
00228         double altitude_step_size,
00229         double time_step,
00230         MAGtype_MagneticModel *MagneticModel,
00231         MAGtype_Geoid *geoid,
00232         MAGtype_Ellipsoid Ellip,
00233         MAGtype_Date StartDate,
00234         MAGtype_Date EndDate,
00235         int ElementOption,
00236         int PrintOption,
00237         char *OutputFile);
00238 
00239 int MAG_robustReadMagneticModel_Large(char *filename, char* filenameSV, MAGtype_MagneticModel **MagneticModel, int array_size);
00240 
00241 int MAG_robustReadMagModels(char *filename, MAGtype_MagneticModel *(*magneticmodels)[], int array_size);
00242 
00243 int MAG_SetDefaults(MAGtype_Ellipsoid *Ellip, MAGtype_Geoid *Geoid);
00244 
00245 /*User Interface*/
00246 
00247 void MAG_Error(int control);
00248 
00249 char MAG_GeomagIntroduction_WMM(MAGtype_MagneticModel *MagneticModel, char *VersionDate);
00250 
00251 char MAG_GeomagIntroduction_EMM(MAGtype_MagneticModel *MagneticModel, char *VersionDate);
00252 
00253 int MAG_GetUserGrid(MAGtype_CoordGeodetic *minimum,
00254         MAGtype_CoordGeodetic *maximum,
00255         double *step_size,
00256         double *a_step_size,
00257         double *step_time,
00258         MAGtype_Date *StartDate,
00259         MAGtype_Date *EndDate,
00260         int *ElementOption,
00261         int *PrintOption,
00262         char *OutputFile,
00263         MAGtype_Geoid *Geoid);
00264 
00265 int MAG_GetUserInput(MAGtype_MagneticModel *MagneticModel,
00266         MAGtype_Geoid *Geoid,
00267         MAGtype_CoordGeodetic *CoordGeodetic,
00268         MAGtype_Date *MagneticDate);
00269 
00270 void MAG_PrintUserData(MAGtype_GeoMagneticElements GeomagElements,
00271         MAGtype_CoordGeodetic SpaceInput,
00272         MAGtype_Date TimeInput,
00273         MAGtype_MagneticModel *MagneticModel,
00274         MAGtype_Geoid *Geoid);
00275 
00276 int MAG_ValidateDMSstringlat(char *input, char *Error);
00277 
00278 int MAG_ValidateDMSstringlong(char *input, char *Error);
00279 
00280 int MAG_Warnings(int control, double value, MAGtype_MagneticModel *MagneticModel);
00281 
00282 /*Memory and File Processing*/
00283 
00284 MAGtype_LegendreFunction *MAG_AllocateLegendreFunctionMemory(int NumTerms);
00285 
00286 MAGtype_MagneticModel *MAG_AllocateModelMemory(int NumTerms);
00287 
00288 MAGtype_SphericalHarmonicVariables *MAG_AllocateSphVarMemory(int nMax);
00289 
00290 void MAG_AssignHeaderValues(MAGtype_MagneticModel *model, char values[][MAXLINELENGTH]);
00291 
00292 void MAG_AssignMagneticModelCoeffs(MAGtype_MagneticModel *Assignee, MAGtype_MagneticModel *Source, int nMax, int nMaxSecVar);
00293 
00294 int MAG_FreeMemory(MAGtype_MagneticModel *MagneticModel, MAGtype_MagneticModel *TimedMagneticModel, MAGtype_LegendreFunction *LegendreFunction);
00295 
00296 int MAG_FreeLegendreMemory(MAGtype_LegendreFunction *LegendreFunction);
00297 
00298 int MAG_FreeMagneticModelMemory(MAGtype_MagneticModel *MagneticModel);
00299 
00300 int MAG_FreeSphVarMemory(MAGtype_SphericalHarmonicVariables *SphVar);
00301 
00302 void MAG_PrintWMMFormat(char *filename, MAGtype_MagneticModel *MagneticModel);
00303 
00304 void MAG_PrintEMMFormat(char *filename, char *filenameSV, MAGtype_MagneticModel *MagneticModel);
00305 
00306 int MAG_readMagneticModel(char *filename, MAGtype_MagneticModel *MagneticModel);
00307 
00308 int MAG_readMagneticModel_Large(char *filename, char *filenameSV, MAGtype_MagneticModel *MagneticModel);
00309 
00310 int MAG_readMagneticModel_SHDF(char *filename, MAGtype_MagneticModel *(*magneticmodels)[], int array_size);
00311 
00312 int MAG_swab_type();
00313 
00314 char *MAG_Trim(char *str);
00315 
00316 float MAG_FloatSwap(float f);
00317 
00318 /*Conversions, Transformations, and other Calculations*/
00319 
00320 int MAG_CalculateGeoMagneticElements(MAGtype_MagneticResults *MagneticResultsGeo, MAGtype_GeoMagneticElements *GeoMagneticElements);
00321 
00322 int MAG_CalculateSecularVariationElements(MAGtype_MagneticResults MagneticVariation, MAGtype_GeoMagneticElements *MagneticElements);
00323 
00324 int MAG_CalculateGridVariation(MAGtype_CoordGeodetic location, MAGtype_GeoMagneticElements *elements);
00325 
00326 int MAG_DateToYear(MAGtype_Date *Calendar_Date, char *Error);
00327 
00328 void MAG_DegreeToDMSstring(double DegreesOfArc, int UnitDepth, char *DMSstring);
00329 
00330 void MAG_DMSstringToDegree(char *DMSstring, double *DegreesOfArc);
00331 
00332 int MAG_GeodeticToSpherical(MAGtype_Ellipsoid Ellip, MAGtype_CoordGeodetic CoordGeodetic, MAGtype_CoordSpherical *CoordSpherical);
00333 
00334 int MAG_GetTransverseMercator(MAGtype_CoordGeodetic CoordGeodetic, MAGtype_UTMParameters *UTMParameters);
00335 
00336 int MAG_GetUTMParameters(double Latitude,
00337         double Longitude,
00338         int *Zone,
00339         char *Hemisphere,
00340         double *CentralMeridian);
00341 
00342 int MAG_isNaN(double d);
00343 
00344 int MAG_RotateMagneticVector(MAGtype_CoordSpherical,
00345         MAGtype_CoordGeodetic CoordGeodetic,
00346         MAGtype_MagneticResults MagneticResultsSph,
00347         MAGtype_MagneticResults *MagneticResultsGeo);
00348 
00349 void MAG_SphericalToCartesian(MAGtype_CoordSpherical CoordSpherical, double *x, double *y, double *z);
00350 
00351 void MAG_TMfwd4(double Eps, double Epssq, double K0R4, double K0R4oa,
00352         double Acoeff[], double Lam0, double K0, double falseE,
00353         double falseN, int XYonly, double Lambda, double Phi,
00354         double *X, double *Y, double *pscale, double *CoM);  //Rewrite this?
00355 
00356 int MAG_YearToDate(MAGtype_Date *Date);
00357 
00358 
00359 /*Spherical Harmonics*/
00360 
00361 int MAG_AssociatedLegendreFunction(MAGtype_CoordSpherical CoordSpherical, int nMax, MAGtype_LegendreFunction *LegendreFunction);
00362 
00363 int MAG_CheckGeographicPole(MAGtype_CoordGeodetic *CoordGeodetic);
00364 
00365 int MAG_ComputeSphericalHarmonicVariables(MAGtype_Ellipsoid Ellip,
00366         MAGtype_CoordSpherical CoordSpherical,
00367         int nMax,
00368         MAGtype_SphericalHarmonicVariables * SphVariables);
00369 
00370 int MAG_PcupHigh(double *Pcup, double *dPcup, double x, int nMax);
00371 
00372 int MAG_PcupLow(double *Pcup, double *dPcup, double x, int nMax);
00373 
00374 int MAG_SecVarSummation(MAGtype_LegendreFunction *LegendreFunction,
00375         MAGtype_MagneticModel *MagneticModel,
00376         MAGtype_SphericalHarmonicVariables SphVariables,
00377         MAGtype_CoordSpherical CoordSpherical,
00378         MAGtype_MagneticResults *MagneticResults);
00379 
00380 int MAG_SecVarSummationSpecial(MAGtype_MagneticModel *MagneticModel,
00381         MAGtype_SphericalHarmonicVariables SphVariables,
00382         MAGtype_CoordSpherical CoordSpherical,
00383         MAGtype_MagneticResults *MagneticResults);
00384 
00385 int MAG_Summation(MAGtype_LegendreFunction *LegendreFunction,
00386         MAGtype_MagneticModel *MagneticModel,
00387         MAGtype_SphericalHarmonicVariables SphVariables,
00388         MAGtype_CoordSpherical CoordSpherical,
00389         MAGtype_MagneticResults *MagneticResults);
00390 
00391 int MAG_SummationSpecial(MAGtype_MagneticModel *MagneticModel,
00392         MAGtype_SphericalHarmonicVariables SphVariables,
00393         MAGtype_CoordSpherical CoordSpherical,
00394         MAGtype_MagneticResults *MagneticResults);
00395 
00396 int MAG_TimelyModifyMagneticModel(MAGtype_Date UserDate, MAGtype_MagneticModel *MagneticModel, MAGtype_MagneticModel *TimedMagneticModel);
00397 
00398 /*Geoid*/
00399 
00400 int MAG_InitializeGeoid(MAGtype_Geoid *Geoid);
00401 
00402 
00403 
00404 int MAG_ConvertGeoidToEllipsoidHeight(MAGtype_CoordGeodetic *CoordGeodetic, MAGtype_Geoid *Geoid);
00405 /*
00406  * The function Convert_Geoid_To_Ellipsoid_Height converts the specified WGS84
00407  * geoid height at the specified geodetic coordinates to the equivalent
00408  * ellipsoid height, using the EGM96 gravity model.
00409  *
00410  *    Latitude            : Geodetic latitude in radians           (input)
00411  *    Longitude           : Geodetic longitude in radians          (input)
00412  *    Geoid_Height        : Geoid height, in meters                (input)
00413  *    Ellipsoid_Height    : Ellipsoid height, in meters.           (output)
00414  *
00415  */
00416 
00417 int MAG_GetGeoidHeight(double Latitude, double Longitude, double *DeltaHeight, MAGtype_Geoid *Geoid);
00418 /*
00419  * The private function Get_Geoid_Height returns the height of the
00420  * WGS84 geiod above or below the WGS84 ellipsoid,
00421  * at the specified geodetic coordinates,
00422  * using a grid of height adjustments from the EGM96 gravity model.
00423  *
00424  *    Latitude            : Geodetic latitude in radians           (input)
00425  *    Longitude           : Geodetic longitude in radians          (input)
00426  *    DeltaHeight         : Height Adjustment, in meters.          (output)
00427  *
00428  */
00429 
00430 
00431 
00432 
00433 
00434 
00435 #endif /*WMMHEADER_H*/


world_magnetic_model
Author(s): National Geophysical Data Center (NGDC, Boulder CO, USA), British Geological Survey (BGS, Edinburgh, Scotland)
autogenerated on Sat Jul 26 2014 07:02:19