%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% A SET OF FORTRAN SUBROUTINES FOR COMPUTATIONS OF THE GEOMAGNETIC FIELD IN THE EARTH'S MAGNETOSPHERE (GEOPACK; release of January 5, 2001, corrected April 3, 2001) N.A. TSYGANENKO UNIVERSITIES SPACE RESEARCH ASSOCIATION (USRA) CODE 690.2 NASA GSFC GREENBELT, MD 20771 USA INTRODUCTION Recent studies in the solar-terrestrial physics led to recognizing the role of the geomagnetic field as one of the most important characteristics of human environment. The Earth's magnetic field links the interplanetary medium with the upper atmosphere and the ionosphere, guides the energetic charged particles ejected during solar flares, channels the low-frequency electromagnetic waves and heat flux, confines the radiation belt and auroral plasma particles, and serves as a giant accumulator of the solar wind energy that eventually dissipates during the magnetic storms. Understanding these phenomena is crucial for the problem of forecasting the "weather" in the near- Earth space, which affects many aspects of modern human activities and space technolo- gies. In many applications one often needs numerical tools for evaluating the components of the geomagnetic field vector in a wide range of distances, trace the field lines far away from the Earth's surface, calculate the geomagnetically conjugate points, and map a spacecraft position with respect to characteristic magnetospheric/ionospheric bounda- ries. This requires using quantitative models of the Earth's magnetic field, including both the internal part, due to the dynamo currents inside Earth, and the external part, produced by the magnetospheric and ionospheric electric current systems. The present set of subroutines is intended as a subsidiary package for calculating the geomagnetic field components at any point of space within the Earth's magnetosphere up to the Moon's orbit and tracing the field lines. Upon specifying the universal time and day of year as input parameters, it automatically performs all the necessary rotations of coordinate axes and takes into account the tilt angle of the Earth's geodipole axis. The Earth's internal field can be computed either in the dipole approximation or by using a more realistic DGRF/IGRF model, updated for a given epoch. It also contains several subsidiary subroutines for transformations between coordinate systems, most widely used in geophysics and space physics. The present version of GEOPACK does not include subroutines for an external field model. This area is now rapidly developing; each of several existing models has its own advantages and deficiencies, so that it is not easy to give a preference to a single one. Also, we expect better models to appear in the nearest future. Therefore, it was considered reasonable to divide the software into two files; the first one (GEOPACK) includes general-use codes, which are unlikely to significantly change in the future, while the external field models are provided separately. A convenient way of using the GEOPACK subroutines is to compile them separately from the main user's code and include the corresponding object modules in the user's personal library. The GEOPACK subroutines were developed originally in 1978; the present version emerged as a result of many upgrades, numerous tests, and many critical comments received since its first release. Although the package appears as quite robust a tool, it is unlikely that no room for further improvement is left. The author greatly appreciates any comments on the performance of the codes, possible problems, and any suggestions on how to make the GEOPACK subroutines simpler, faster, more versatile, and easier to understand. Below is a sort of a "manual guide" for using the subroutines, including a list of refe- rences and two examples of a typical main program for tracing model field lines, with the purpose to help users to debug their own codes and avoid common mistakes. The FORTRAN listings of the package subroutines are placed in a separate file GEOPACK.FOR. DESCRIPTIONS OF THE SUBROUTINES 1. SUBROUTINE: IGRF FUNCTION: Computes three spherical components of the main (internal) geomagnetic field in the geographical geocentric coordinate system (GEO). FORTRAN STATEMENT: CALL IGRF(IY,NM,R,T,F,BR,BT,BF) INPUT PARAMETERS: IY - year (four digits) which should be specified within the interval 1965 <= IY <= 2005; NM - maximal order of spherical harmonics to be taken into account in the scalar potential expansions (1<=NM<=10) R,T,F - spherical coordinates of the point, where the field vector is to be evaluated: R is the radial geocentric distance in Earth radii (Re=6371.2 km), T is the colatitude, and F is the east longitude (both angles in radians). OUTPUT PARAMETERS: BR, BT, BF - spherical components of the main geomagnetic field in nanotesla: BR is the radial component (BR>0 corresponds to outward field direction), BT is the southward component, and BP is the eastward component. COMMON BLOCKS: none. OTHER SUBROUTINES INVOKED: none. COMMENTS: The subroutine uses harmonic coefficients for eight epochs: 1965.0, 1970.0, 1975.0, 1980.0, 1985.0, 1990.0, 1995.0, and 2000.0; the expansion coeffi- cients are automatically calculated by means of a linear interpolation between the nearest epochs. If 2000 < IY < 2005, the subroutine extrapolates the coefficients by using the "secular velocities" through the order 8. If IY<1965 or IY>2005, the coefficients are assumed equal to those for IY=1965 or IY=2005, respectively. The subroutine is being upgraded on a regular basis, as coefficients for the next epoch become available. When calculating the IGRF field at large distances, there is no need to retain all the terms in the expansion, since the relative contribution from higher-order multipoles rapidly falls off with R. This makes it possible to drastically reduce the computation time by choosing smaller values of the parameter NM at large geocentric distances (see Tsyganenko [1990], p.81, for details). In contrast, one has to use full IGRF expansions with NM=10 at and near the Earth's surface. See [Langel, 1987] for a general information on the main field models or visit the IGRF website. 2. SUBROUTINE: DIP FUNCTION: Computes Cartesian geocentric solar-magnetospheric (GSM) components of the Earth's magnetic field, corresponding to the first (dipolar) term in the spherical harmonic expansion for the epoch 2000. FORTRAN STATEMENT: CALL DIP(PS,X,Y,Z,BX,BY,BZ) INPUT PARAMETERS: PS - tilt angle (in radians) between the axis of Earth's centered dipole moment and ZGSM axis (PS<0 in winter and PS>0 in summer); X,Y,Z - Cartesian GSM coordinates of the point (in Earth's radii). OUTPUT PARAMETERS: BX,BY,BZ - GSM magnetic field components in nanotesla. COMMON BLOCKS: none. OTHER SUBROUTINES INVOKED: none. COMMENTS: (1) The dipole is assumed to be centered at the origin; the value of its magnetic moment corresponds to the epoch 2000.0. (2) The angle PS can either be specified directly or calculated by using the subroutine RECALC; in the last case, a named COMMON block /GEOPACK/ should be present in the user's module, from which RECALC and DIP are invoked. The value of the dipole tilt angle (in radians) should be taken from the 16-th element of that COMMON-block (after having invoked RECALC). The structure of the COMMON-block should be the same as in the subroutine RECALC (see examples in the end of this file). 3. SUBROUTINE: SUN FUNCTION: This is a subsidiary subroutine which is usually called from the subroutine RECALC and computes the spherical angles of the Earth-Sun line in the geocentric inertial coordinate system, and the Greenwich mean sidereal time. FORTRAN STATEMENT: CALL SUN(IYR,IDAY,IHOUR,MIN,ISEC,GST,SLONG,SRASN,SDEC) INPUT PARAMETERS: IYR,IDAY,IHOUR,MIN,ISEC - year (four-digit number), day, hour, minute, and second, respectively; OUTPUT PARAMETERS: GST - Greenwich mean sidereal time, SLONG - ecliptical longitude of Sun SRASN - right ascension of Sun SDEC - declination of Sun All the above output parameters are in radians. COMMON BLOCKS: none. OTHER SUBROUTINES INVOKED: none. COMMENTS: (1) 1901<IYR<2099 (2) IDAY=1 is January 1 (3) The subroutine, authored by G.D. Mead, was compiled (with minor changes) from the paper by C.T. Russell (1971). 4. SUBROUTINE: SPHCAR FUNCTION: Computes spherical coordinates from Cartesian ones or vica versa. FORTRAN STATEMENT: CALL SPHCAR(R,THETA,PHI,X,Y,Z,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0, then spherical coordinates R,THETA,PHI are the input quantities (colatitude THETA and longitude PHI are in radians), (b) if J<0, then Cartesian coordinates X,Y,Z are the inputs. OUTPUT PARAMETERS: (a) if J>0 then Cartesian coordinates X,Y,Z, (b) if J<0 then R,THETA,PHI. COMMON BLOCKS: none. OTHER SUBROUTINES INVOKED: none. COMMENTS: If, for J<0, X=0 and Y=0, then PHI is set equal to 0. 5. SUBROUTINE: BSPCAR FUNCTION: Calculation of Cartesian components of a field vector from its known local spherical components (e.g., provided by IGRF) and the spherical angles THETA and PHI of the observation point. FORTRAN STATEMENT: CALL BSPCAR(THETA,PHI,BR,BTHETA,BPHI,BX,BY,BZ) INPUT PARAMETERS: THETA, PHI - colatitude and longitude of the point in radians; BR, BTHETA, BPHI - spherical components of the field vector in the local orthogonal coordinate system. OUTPUT PARAMETERS: BX,BY,BZ - Cartesian components of the vector. COMMON BLOCKS: none. OTHER SUBROUTINES INVOKED: none. 6. SUBROUTINE: RECALC FUNCTION: Computes the angles, defining the geodipole orientation for a given UT moment, and the elements of matrices for transformations between the following Cartesian geocentric coordinate systems: geographic (GEO), geomagnetic (MAG), solar-magnetic (SM), solar-magnetospheric (GSM), solar-ecliptic (GSE), and equatorial inertial (GEI). FORTRAN STATEMENT: CALL RECALC(IYR,IDAY,IHOUR,MIN,ISEC) INPUT PARAMETERS: IYR,IDAY,IHOUR,MIN,ISEC - same as in the subroutine SUN. OUTPUT PARAMETERS: none. OTHER SUBROUTINES INVOKED: SUN, MAGSM, SMGSM. COMMON BLOCKS: Output parameters are placed in the named common block /GEOPACK/, containing 37 4-byte words. COMMENTS: If only GEO and MAG coordinate systems are involved (no UT dependence), then it is recommended to set IHOUR>24; this is a convenient way to avoid unnecessary calculation of other matrix parameters. The subroutine is being upgraded on a regular basis, as the expansion coefficients for the next epoch become available. 7. SUBROUTINE: GEOMAG. FUNCTION: Transformation of the geographic Cartesian coordinates (GEO) into the dipolar geomagnetic (MAG) and vica versa. FORTRAN STATEMENT: CALL GEOMAG(XGEO,YGEO,ZGEO,XMAG,YMAG,ZMAG,J,IYR) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0, then geographic coordinates XGEO,YGEO,ZGEO are the inputs; (b) if J<0, then geomagnetic coordinates XMAG,YMAG,ZMAG are the inputs; IYR - four-digit year number (needed for taking into account secular variation of the Earth's dipole moment). OUTPUT PARAMETERS: If J>0 then XMAG,YMAG,ZMAG; if J<0 then XGEO,YGEO,ZGEO. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: RECALC. 8. SUBROUTINE: GEIGEO. FUNCTION: Transformation of the Geocentric Equatorial Inertial (GEI) coordinates into geographic ones (GEO) and vica versa. FORTRAN STATEMENT: CALL GEIGEO(XGEI,YGEI,ZGEI,XGEO,YGEO,ZGEO,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0, then GEI coordinates XGEI,YGEI,ZGEI are the inputs; (b) if J<0, then geographic coordinates XGEO,YGEO,ZGEO are the inputs; OUTPUT PARAMETERS: If J>0 then XGEO,YGEO,ZGEO; if J<0 then XGEI,YGEI,ZGEI. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: none. 9. SUBROUTINE: MAGSM. FUNCTION: Transformation of dipolar geomagnetic (MAG) coordinates into the solar magnetic (SM) ones or vica versa. FORTRAN STATEMENT: CALL MAGSM(XMAG,YMAG,ZMAG,XSM,YSM,ZSM,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0, then MAG coordinates XMAG,YMAG,ZMAG are the inputs; (b) if J<0, then SM coordinates XSM,YSM,ZSM are the inputs. OUTPUT PARAMETERS: If J>0 then XSM,YSM,ZSM; if J<0 then XMAG,YMAG,ZMAG. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: none. 10. SUBROUTINE: GSMGSE. FUNCTION: Transformation of geocentric solar magnetospheric (GSM) coordinates into geocentric solar ecliptic (GSE) ones and vica versa. FORTRAN STATEMENT: CALL GSMGSE(XGSM,YGSM,ZGSM,XGSE,YGSE,ZGSE,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0 then GSM coordinates XGSM,YGSM,ZGSM are the inputs; (b) if J<0 then GSE coordinates XGSE,YGSE,ZGSE are the inputs. OUTPUT PARAMETERS: If J>0 then XGSE,YGSE,ZGSE; if J<0 then XGSM,YGSM,ZGSM. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: none. 11. SUBROUTINE: SMGSM. FUNCTION: Transformation of solar magnetic (SM) coordinates into solar magnetospheric (GSM) ones and vica versa. FORTRAN STATEMENT: CALL SMGSM(XSM,YSM,ZSM,XGSM,YGSM,ZGSM,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0 then SM coordinates XSM,YSM,ZSM are the inputs; (b) if J<0 then GSM coordinates XGSM,YGSM,ZGSM are the inputs. OUTPUT PARAMETERS: If J>0 then XGSM,YGSM,ZGSM; if J<0 then XSM,YSM,ZSM. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: none. 12. SUBROUTINE: GEOGSM. FUNCTION: Transformation of the geographic (GEO) coordinates into solar magnetospheric (GSM) ones and vica versa. FORTRAN STATEMENT: CALL GEOGSM(XGEO,YGEO,ZGEO,XGSM,YGSM,ZGSM,J) INPUT PARAMETERS: J - integer switch parameter: (a) if J>0 then GEO coordinates XGEO,YGEO,ZGEO are the inputs; (b) if J<0 then GSM coordinates XGSM,YGSM,ZGSM are the inputs. OUTPUT PARAMETERS: If J>0 then XGSM,YGSM,ZGSM; if J<0 then XGEO,YGEO,ZGEO. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: none. 13. SUBROUTINE: RHAND. FUNCTION: This is a subsidiary subroutine, calculating the right-hand sides of the field line equations (that is, components of the unit vector along the local direction of B), which are necessary for making one step along the field line by the subroutine STEP. FORTRAN STATEMENT: CALL RHAND(X,Y,Z,R1,R2,R3,IOPT,PARMOD,EXNAME) INPUT PARAMETERS: X,Y,Z - GSM coordinates of the current point on a field line; IOPT - an integer index, reserved for specifying a version of the external magnetic field model. In the case of T87 or T89 model [Tsyganenko, 1987; 1989], this parameter can be used for specifying the range of the Kp-index; PARMOD - a 10-element array, reserved for other input parameters of the external field model, e.g., solar wind pressure, interplanetary magnetic field components, Dst, as in the T96 model [Tsyganenko, 1995; 1996]; EXNAME - a name of the external field model subroutine (see below the description of subroutine TRACE for more details). OUTPUT PARAMETERS: R1,R2,R3 - right-hand-side quantities (the unit vector components). COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: DIP, IGRF, GEOGSM, SPHCAR, BSPCAR, and EXNAME (to be replaced by an actual name of a model subroutine). 14. SUBROUTINE: STEP. FUNCTION: Makes one step along a model magnetic field line. The model field is a sum of contributions from internal and external sources, provided by the subroutines IGRF (or DIP) and EXNAME, respectively. FORTRAN STATEMENT: CALL STEP(N,X,Y,Z,DS,ERRIN,IOPT,PARMOD,EXNAME) INPUT PARAMETERS: N - the highest order of spherical harmonics in the main field expansions, required to maintain sufficient accuracy (depends on geocentric distance and is automatically adjusted by TRACE; see below); X,Y,Z - GSM position of the initial point on a field line; DS - step size along the line; ERRIN - an estimate of the admissible error; IOPT - an integer index, reserved for specifying a version of the external magnetic field model (in the case of T87 or T89 model, this parameter can be used for specifying the range of the Kp-index); PARMOD - a 10-element array, reserved for other input parameters of the external field model (e.g., solar wind pressure, interplanetary magnetic field components, and Dst, as in the T96 model); EXNAME - a name of the external field model subroutine (see below the description of subroutine TRACE for more details). OUTPUT PARAMETERS: X,Y,Z - GSM coordinates of the next point on the field line; that is, the input values of initial X,Y,Z are replaced by the output values, corresponding to the next point on the line. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: RHAND. COMMENTS: (1) Do not forget to specify the actual name of the model field subroutine as EXTERNAL in a subroutine or program, from which the s/r STEP is invoked (see also comments 1-3 in the description of the s/r TRACE below). (2) The parameter DS can change its value as a result of having invoked STEP, since (a) if the step error estimate exceeds ERRIN, the step is repeated once again with a halved value of the stepsize DS, (b) if the error estimate is found to be less than 0.04*ERRIN, then the current step is not repeated, but the value of DS for the next step is doubled. 15. SUBROUTINE: TRACE. FUNCTION: Calculates GSM coordinates of a sequence of points lying on a field line. The tracing starts at a given initial point and ends either upon crossing an inner spherical boundary of the tracing region (e.g., Earth's surface), or upon exiting from the modeling region. FORTRAN STATEMENT: CALL TRACE(XI,YI,ZI,DIR,RLIM,R0,IHARM,NP,IOPT,PARMOD,EXNAME,XF,YF,ZF,XX,YY,ZZ,L) INPUT PARAMETERS: XI,YI,ZI, - GSM position of the initial point (in Earth's radii); DIR - defines the tracing direction: assign DIR=1.0 if a line should be traced oppositely to the B vector (e.g., from the northern polar ionosphere down the northern tail lobe), and DIR=-1.0 for the opposite case. RLIM - geocentric radius of the outer boundary of the tracing region (in Earth's radii); the tracing is ceased once R>RLIM; R0 - radius of the inner boundary of the tracing region (usually R0=1.0, which corresponds to the Earth's surface; see also the comment No.4); IHARM - highest order of spherical harmonics in the main field expansion (see comments ## 1 and 2 below); NP - upper estimate of the expected number of steps along the field line (it usually suffices to assume NP=1000); IOPT - an integer index, reserved for specifying a version of the external magnetic field model (in the case of T87 or T89 model, this parameter can be used for specifying the range of the Kp-index); PARMOD - a 10-element array, reserved for other input parameters of the external field model (e.g., solar wind pressure, interplanetary magnetic field components, and Dst, as in the T96 model); EXNAME - a name of the external field model subroutine. The corresponding actual argument should have the type CHARACTER*n (n is the total number of symbols) and must be specified in the EXTERNAL statement of the main module. The list of formal parameters of the subroutine EXNAME must be as follows: (IOPT, PARMOD, PS, X, Y, Z, BX, BY, BZ), where IOPT is an integer and PARMOD is a 10-element array of real type. The other 6 parameters are identical to those in the subroutine DIP. For more details, see an example of using this subroutine in the end of this file. COMMON BLOCKS: Same as in RECALC. OTHER SUBROUTINES INVOKED: STEP, RHAND. COMMENTS: (1) Before tracing field lines for a specific geophysical situation, it is necessary to calculate some quantities, defining relative orientation of geographic and solar-magnetospheric coordinate systems. This can be done just by invoking the subroutine RECALC with appropriate values of year (4-digit), day, and universal time of the day. It is also recommended to set IHARM=10, having in mind that the optimal length of the main field expansions will be defined by TRACE automatically, based on a current value of the radial distance. (2) If the dipolar approximation for the main B-field is sufficient, then it is possible to set IHARM=0; in this case the subroutine DIP will automatically be used instead of IGRF, and the code will run much faster. In that case, the corresponding value of the dipole tilt angle (in radians) should be specified and put in the 16-th element of the COMMON-block /GEOPACK/. It also can be done by setting IHARM=1 and calling RECALC before tracing; in this case the tilt angle and the coordinate transformation matrices will automatically be found from the specified values of year, day, and UT moment. (3) Any external field model subroutine can be used, provided it has the same structure of formal parameter list and its name is included in the EXTERNAL statement in the user's module, which invokes TRACE. (4) If a field line is closed (i.e., returns back to Earth), then the last (L-th) element in the arrays XX,YY,ZZ (and the triplet XF,YF,ZF) corresponds to the footpoint of the line at the sphere of radius R0. (5) If L<NP, then the rest (NP-L) elements of XX,YY,ZZ are filled with the values of the coordinates (XF,YF,ZF) of the last field line point. If L>NP (that is, not enough space reserved for the computation results) then the computation is aborted and a warning message is displayed. In most cases, it suffices to set NP~300-500. REFERENCES Langel, R. A., Main field, Ch.IV, in Geomagnetism, edited by J. A. Jacobs, Academic Press, London, 1987. Russell, C. T., Geophysical coordinate transformations. Cosmic Electrodynamics, v.2, p.184, 1971. Tsyganenko, N. A., Global quantitative models of the geomagnetic field in the cislunar magnetosphere for different disturbance levels, Planet.Space Sci., v.35, p.1347, 1987. Tsyganenko, N. A., A magnetospheric magnetic field model with a warped tail plasma sheet. Planet.Space Sci., v.37, p.5, 1989. Tsyganenko, N. A., Quantitative models of the magnetospheric magnetic field: methods and results. Space Sci. Rev., v.54, pp.75-186, 1990. Tsyganenko, N. A., Modeling the Earth's magnetospheric magnetic field confined within a realistic magnetopause, J. Geophys.Res., v.100, p.5599, 1995. Tsyganenko, N. A., Effects of the solar wind conditions on the global magnetospheric configuration as deduced from data-based field models, in European Space Agency Publication ESA SP-389, p.181, 1996. ----------------------------------------------------------------------- C APPENDIX: C C###################################################################### C THE CODES BELOW GIVE TWO EXAMPLES OF TRACING THE FIELD LINES # C BY USING THE GEOPACK SOFTWARE # C (just for illustration; do not include them in your code library) # C###################################################################### C PROGRAM EXAMPLE1 C C IN THIS EXAMPLE IT IS ASSUMED THAT WE KNOW GEOGRAPHIC COORDINATES C OF A POINT AT THE EARTH'S SURFACE AND WANT TO TRACE THE CORRESPONDING C FIELD LINE AT A SPECIFIED MOMENT OF UNIVERSAL TIME, TAKING INTO ACCOUNT C THE HIGHER-ORDER MULTIPOLES IN THE INTERNAL FIELD EXPANSION. C DIMENSION XX(500),YY(500),ZZ(500), PARMOD(10) c c be sure to include the following EXTERNAL statement in your codes c and do not forget to include an external field model subroutine (of your c choice) in the package. That subroutine does not necessarily have to c be named EXTERN; if you use another name, use that name instead of EXTERN c in the next statement below: c EXTERNAL EXTERN C C FIRST OF ALL WE DEFINE THE TIME MOMENT AND COMPUTE THE NECESSARY C QUANTITIES FOR COORDINATE TRANSFORMATIONS BY USING THE SUBROUTINE C RECALC: IN THIS PARTICULAR CASE WE NEED TO TRACE FIELD LINES C FOR YEAR=1967, IDAY=350, UT HOUR = 21 C CALL RECALC(1967,350,21,0,0) C C IOPT=1 CORRESPOND TO THE MOST QUIET EXTERNAL FIELD MODEL VERSION (T89) C IOPT=1 C C WHEN USING THE T96 MODEL, THE FOLLOWING STATEMENTS ARE NEEDED, TO SPECIFY C THE SOLAR WIND PRESSURE (PDYN, NANOPASCALS), DST-INDEX (DST, nT), AND C TWO COMPONENTS OF IMF (BY_IMF AND BZ_IMF, nT) C PDYN = ! INSERT A DESIRED VALUE OF PDYN HERE DST = ! INSERT A DESIRED VALUE OF DST HERE BY_IMF= ! INSERT A DESIRED VALUE OF BY_IMF HERE BZ_IMF= ! INSERT A DESIRED VALUE OF BZ_IMF HERE PARMOD(1)=PDYN PARMOD(2)=DST PARMOD(3)=BY_IMF PARMOD(4)=BZ_IMF C C THE LINE WILL BE TRACED FROM THE POINT HAVING GEOGRAPHICAL C LONGITUDE 45 DEGREES AND LATITUDE 75 DEGREES: C GEOLAT=75. GEOLON=45. COLAT=(90.-GEOLAT)*.01745329 XLON=GEOLON*.01745329 C C CONVERT SPHERICAL COORDS INTO CARTESIAN : C CALL SPHCAR(1.,COLAT,XLON,XGEO,YGEO,ZGEO,1) C C TRANSFORM GEOGRAPHICAL COORDS INTO SOLAR MAGNETOSPHERIC : C CALL GEOGSM(XGEO,YGEO,ZGEO,XGSM,YGSM,ZGSM,1) C C TRACE THE FIELD LINE (EXTERN IS THE NAME OF THE EXTERNAL FIELD MODEL C SUBROUTINE, THAT SHOULD BE COMPILED AND LINKED WITH THE GEOPACK SUB- C ROUTINES): C CALL TRACE(XGSM,YGSM,ZGSM,1.,60.,1.,7,500, * IOPT,PARMOD,EXTERN,XF,YF,ZF,XX,YY,ZZ,M) ! replace EXTERN by the C actual name C WRITE THE RESULTS IN THE DATAFILE 'LINTEST1.DAT': C OPEN(UNIT=1,FILE='LINTEST1.DAT',STATUS='NEW') WRITE (1,20) (XX(L),YY(L),ZZ(L),L=1,M) 20 FORMAT((2X,3F6.2)) CLOSE(UNIT=1) STOP END C------------------------------------------------------------------- C PROGRAM EXAMPLE2 C C THIS IS AN EXAMPLE OF USING 'TRACE' SUBROUTINE FOR THE CASE, C IN WHICH THE EARTH'S DIPOLE TILT ANGLE IS EXPLIICITLY SPECIFIED. C IT IS ASSUMED THAT WE KNOW THE GSM LATITUDE AND LONGITUDE OF THE C STARTING POINT AT THE EARTH'S SURFACE C IT IS ALSO ASSUMED THAT THE MAIN (INTERNAL) FIELD IS PURELY DIPOLAR. C COMMON /GEOPACK/ AA(10),SPS,CPS,BB(3),PS,CC(11),KK(2),DD(8) DIMENSION XX(500),YY(500),ZZ(500), PARMOD(10) c c be sure to include the following EXTERNAL statement in your codes c and do not forget to include an external field model subroutine (of your c choice) in the package. That subroutine does not necessarily have to c be named EXTERN; if you use another name, use that name instead of EXTERN c in the next statement below: c EXTERNAL EXTERN C IOPT=1 ! THE MOST QUIET VERSION OF THE EXTERNAL FIELD MODEL (T89) C WHEN USING THE T96 MODEL, THE FOLLOWING STATEMENTS ARE NEEDED, TO SPECIFY C THE SOLAR WIND PRESSURE (PDYN, NANOPASCALS), DST-INDEX (DST, nT), AND C TWO COMPONENTS OF IMF (BY_IMF AND BZ_IMF, nT) C PDYN = ! INSERT A DESIRED VALUE OF PDYN HERE DST = ! INSERT A DESIRED VALUE OF DST HERE BY_IMF= ! INSERT A DESIRED VALUE OF BY_IMF HERE BZ_IMF= ! INSERT A DESIRED VALUE OF BZ_IMF HERE PARMOD(1)=PDYN PARMOD(2)=DST PARMOD(3)=BY_IMF PARMOD(4)=BZ_IMF c XLAT=75. XLON=180. C c we have defined the latitude (XLAT) and longitude (XLON) in the GSM system c PS=0. SPS=SIN(PS) CPS=COS(PS) C C WE HAVE SPECIFIED THE DIPOLE TILT ANGLE (PS), ITS SINE (SPS) AND COSINE (CPS) C T=(90.-XLAT)*.01745329 XL=XLON*.01745329 XGSM=SIN(T)*COS(XL) YGSM=SIN(T)*SIN(XL) ZGSM=COS(T) CALL TRACE(XGSM,YGSM,ZGSM,1.,60.,1.,0,500, * IOPT,PARMOD,EXTERN,XF,YF,ZF,XX,YY,ZZ,M) C C THE MEANING OF INPUT PARAMETERS FOR TRACE IS EXPLAINED IN C THE FILE GEOPACK.TXT C C WRITE THE RESULTS IN THE DATAFILE 'LINTEST2.DAT': C OPEN(UNIT=1, FILE='LINTEST2.DAT',STATUS='NEW') 1 WRITE (1,20) (XX(L),YY(L),ZZ(L),L=1,M) 20 FORMAT((2X,3F6.2)) CLOSE(UNIT=1) STOP END C C============================================================================ C============================================================================ C============================================================================ c c########################################################################## c# # c# GEOPACK # c# (MAIN SET OF FORTRAN CODES) # c# # c########################################################################## C c c This collection of subroutines is a result of several upgrades of the original c package by N. A. Tsyganenko. This release is dated by January 5, 2001. c c Please see the additional file geopack.txt for descriptions of the individual c subroutines. c c The following changes were made to the previous release of April 16, 1996: c c (1) The latest set of IGRF expansion coefficients for the epoch 2000.0 c was added, so that the updated version of the main field model accepts c dates through 2005. c c (2) All explicit type statements as well as IMPLICIT NONE were taken c out from all subroutines, for the sake of brevity. c (3) To avoid potential run-time errors on some types of FORTRAN compilers, c the SAVE statements were added in the subroutines IGRF, DIP, RECALC, GEOMAG. C C (4) In the tracing subroutine TRACE, more harmonic terms were allowed c to be included in the main field expansion (IGRF) for maintaining a higher c accuracy. c c (5) An update and some correction/editing of the documentation file c GEOPACK.TXT was made. c c c---------------------------------------------------------------------------------- c SUBROUTINE IGRF(IY,NM,R,T,F,BR,BT,BF) c C CALCULATES COMPONENTS OF THE MAIN (INTERNAL) GEOMAGNETIC FIELD IN SPHERICAL C GEOGRAPHICAL COORDINATE SYSTEM, USING IAGA INTERNATIONAL GEOMAGNETIC REFERENCE C MODEL COEFFICIENTS (e.g., http://www.ngdc.noaa.gov/IAGA/wg8/igrf2000.html) C C UPDATING THE COEFFICIENTS TO A GIVEN EPOCH IS MADE AUTOMATICALLY UPON THE FIRST C CALL AND AFTER EVERY CHANGE OF THE PARAMETER IY. C C-----INPUT PARAMETERS: C C IY - YEAR NUMBER (FOUR-DIGIT; 1965 &LE IY &LE 2005) C NM - HIGHEST ORDER OF SPHERICAL HARMONICS IN THE SCALAR POTENTIAL (NM &LE 10) C R,T,F - SPHERICAL COORDINATES (RADIUS R IN UNITS RE=6371.2 KM, GEOGRAPHIC C COLATITUDE T AND LONGITUDE F IN RADIANS) C C-----OUTPUT PARAMETERS: C C BR,BT,BF - SPHERICAL COMPONENTS OF THE MAIN GEOMAGNETIC FIELD IN NANOTESLA C C LAST MODIFICATION: JANUARY 5, 2001. C THE CODE WAS MODIFIED TO ACCEPT DATES THROUGH 2005. C IT HAS ALSO BEEN SLIGHTLY SIMPLIFIED BY TAKING OUT SOME REDUNDANT STATEMENTS, C AND A "SAVE" STATEMENT WAS ADDED, TO AVOID POTENTIAL PROBLEMS WITH SOME C FORTRAN COMPILERS. c C WRITTEN BY: N. A. TSYGANENKO C SAVE MA,IYR,IPR C DIMENSION A(11),B(11),G(66),H(66),REC(66),G65(66),H65(66),G70(66), * H70(66),G75(66),H75(66),G80(66),H80(66),G85(66),H85(66),G90(66), * H90(66),G95(66),H95(66),G00(66),H00(66),DG00(45),DH00(45) c DATA G65/0.,-30334.,-2119.,-1662.,2997.,1594.,1297.,-2038.,1292., *856.,957.,804.,479.,-390.,252.,-219.,358.,254.,-31.,-157.,-62., *45.,61.,8.,-228.,4.,1.,-111.,75.,-57.,4.,13.,-26.,-6.,13.,1.,13., *5.,-4.,-14.,0.,8.,-1.,11.,4.,8.,10.,2.,-13.,10.,-1.,-1.,5.,1.,-2., *-2.,-3.,2.,-5.,-2.,4.,4.,0.,2.,2.,0./ DATA H65/0.,0.,5776.,0.,-2016.,114.,0.,-404.,240.,-165.,0.,148., *-269.,13.,-269.,0.,19.,128.,-126.,-97.,81.,0.,-11.,100.,68.,-32., *-8.,-7.,0.,-61.,-27.,-2.,6.,26.,-23.,-12.,0.,7.,-12.,9.,-16.,4., *24.,-3.,-17.,0.,-22.,15.,7.,-4.,-5.,10.,10.,-4.,1.,0.,2.,1.,2., *6.,-4.,0.,-2.,3.,0.,-6./ c DATA G70/0.,-30220.,-2068.,-1781.,3000.,1611.,1287.,-2091.,1278., *838.,952.,800.,461.,-395.,234.,-216.,359.,262.,-42.,-160.,-56., *43.,64.,15.,-212.,2.,3.,-112.,72.,-57.,1.,14.,-22.,-2.,13.,-2., *14.,6.,-2.,-13.,-3.,5.,0.,11.,3.,8.,10.,2.,-12.,10.,-1.,0.,3., *1.,-1.,-3.,-3.,2.,-5.,-1.,6.,4.,1.,0.,3.,-1./ DATA H70/0.,0.,5737.,0.,-2047.,25.,0.,-366.,251.,-196.,0.,167., *-266.,26.,-279.,0.,26.,139.,-139.,-91.,83.,0.,-12.,100.,72.,-37., *-6.,1.,0.,-70.,-27.,-4.,8.,23.,-23.,-11.,0.,7.,-15.,6.,-17.,6., *21.,-6.,-16.,0.,-21.,16.,6.,-4.,-5.,10.,11.,-2.,1.,0.,1.,1.,3., *4.,-4.,0.,-1.,3.,1.,-4./ c DATA G75/0.,-30100.,-2013.,-1902.,3010.,1632.,1276.,-2144.,1260., *830.,946.,791.,438.,-405.,216.,-218.,356.,264.,-59.,-159.,-49., *45.,66.,28.,-198.,1.,6.,-111.,71.,-56.,1.,16.,-14.,0.,12.,-5., *14.,6.,-1.,-12.,-8.,4.,0.,10.,1.,7.,10.,2.,-12.,10.,-1.,-1.,4., *1.,-2.,-3.,-3.,2.,-5.,-2.,5.,4.,1.,0.,3.,-1./ DATA H75/0.,0.,5675.,0.,-2067.,-68.,0.,-333.,262.,-223.,0.,191., *-265.,39.,-288.,0.,31.,148.,-152.,-83.,88.,0.,-13.,99.,75.,-41., *-4.,11.,0.,-77.,-26.,-5.,10.,22.,-23.,-12.,0.,6.,-16.,4.,-19.,6., *18.,-10.,-17.,0.,-21.,16.,7.,-4.,-5.,10.,11.,-3.,1.,0.,1.,1.,3., *4.,-4.,-1.,-1.,3.,1.,-5./ c DATA G80/0.,-29992.,-1956.,-1997.,3027.,1663.,1281.,-2180.,1251., *833.,938.,782.,398.,-419.,199.,-218.,357.,261.,-74.,-162.,-48., *48.,66.,42.,-192.,4.,14.,-108.,72.,-59.,2.,21.,-12.,1.,11.,-2., *18.,6.,0.,-11.,-7.,4.,3.,6.,-1.,5.,10.,1.,-12.,9.,-3.,-1.,7.,2., *-5.,-4.,-4.,2.,-5.,-2.,5.,3.,1.,2.,3.,0./ DATA H80/0.,0.,5604.,0.,-2129.,-200.,0.,-336.,271.,-252.,0.,212., *-257.,53.,-297.,0.,46.,150.,-151.,-78.,92.,0.,-15.,93.,71.,-43., *-2.,17.,0.,-82.,-27.,-5.,16.,18.,-23.,-10.,0.,7.,-18.,4.,-22.,9., *16.,-13.,-15.,0.,-21.,16.,9.,-5.,-6.,9.,10.,-6.,2.,0.,1.,0.,3., *6.,-4.,0.,-1.,4.,0.,-6./ c DATA G85/0.,-29873.,-1905.,-2072.,3044.,1687.,1296.,-2208.,1247., *829.,936.,780.,361.,-424.,170.,-214.,355.,253.,-93.,-164.,-46., *53.,65.,51.,-185.,4.,16.,-102.,74.,-62.,3.,24.,-6.,4.,10.,0.,21., *6.,0.,-11.,-9.,4.,4.,4.,-4.,5.,10.,1.,-12.,9.,-3.,-1.,7.,1.,-5., *-4.,-4.,3.,-5.,-2.,5.,3.,1.,2.,3.,0./ DATA H85/0.,0.,5500.,0.,-2197.,-306.,0.,-310.,284.,-297.,0.,232., *-249.,69.,-297.,0.,47.,150.,-154.,-75.,95.,0.,-16.,88.,69.,-48., *-1.,21.,0.,-83.,-27.,-2.,20.,17.,-23.,-7.,0.,8.,-19.,5.,-23.,11., *14.,-15.,-11.,0.,-21.,15.,9.,-6.,-6.,9.,9.,-7.,2.,0.,1.,0.,3., *6.,-4.,0.,-1.,4.,0.,-6./ c DATA G90/0., -29775., -1848., -2131., 3059., 1686., 1314., * -2239., 1248., 802., 939., 780., 325., -423., * 141., -214., 353., 245., -109., -165., -36., * 61., 65., 59., -178., 3., 18., -96., * 77., -64., 2., 26., -1., 5., 9., * 0., 23., 5., -1., -10., -12., 3., * 4., 2., -6., 4., 9., 1., -12., * 9., -4., -2., 7., 1., -6., -3., * -4., 2., -5., -2., 4., 3., 1., * 3., 3., 0./ DATA H90/0., 0., 5406., 0., -2279., -373., 0., * -284., 293., -352., 0., 247., -240., 84., * -299., 0., 46., 154., -153., -69., 97., * 0., -16., 82., 69., -52., 1., 24., * 0., -80., -26., 0., 21., 17., -23., * -4., 0., 10., -19., 6., -22., 12., * 12., -16., -10., 0., -20., 15., 11., * -7., -7., 9., 8., -7., 2., 0., * 2., 1., 3., 6., -4., 0., -2., * 3., -1., -6./ DATA G95/0., -29682., -1789., -2197., 3074., 1685., 1329., * -2268., 1249., 769., 941., 782., 291., -421., * 116., -210., 352., 237., -122., -167., -26., * 66., 64., 65., -172., 2., 17., -94., * 78., -67., 1., 29., 4., 8., 10., * -2., 24., 4., -1., -9., -14., 4., * 5., 0., -7., 4., 9., 1., -12., * 9., -4., -2., 7., 0., -6., -3., * -4., 2., -5., -2., 4., 3., 1., * 3., 3., 0./ DATA H95/0., 0., 5318., 0., -2356., -425., 0., * -263., 302., -406., 0., 262., -232., 98., * -301., 0., 44., 157., -152., -64., 99., * 0., -16., 77., 67., -57., 4., 28., * 0., -77., -25., 3., 22., 16., -23., * -3., 0., 12., -20., 7., -21., 12., * 10., -17., -10., 0., -19., 15., 11., * -7., -7., 9., 7., -8., 1., 0., * 2., 1., 3., 6., -4., 0., -2., * 3., -1., -6./ DATA G00/0., -29615., -1728., -2267., 3072., 1672., 1341., * -2290., 1253., 715., 935., 787., 251., -405., * 110., -217., 351., 222., -131., -169., -12., * 72., 68., 74., -161., -5., 17., -91., * 79., -74., 0., 33., 9., 7., 8., * -2., 25., 6., -9., -8., -17., 9., * 7., -8., -7., 5., 9., 3., - 8., * 6., -9., -2., 9., -4., -8., -2., * -6., 2., -3., 0., 4., 1., 2., * 4., 0., -1./ DATA H00/0., 0., 5186., 0., -2478., -458., 0., * -227., 296., -492., 0., 272., -232., 119., * -304., 0., 44., 172., -134., -40., 107., * 0., -17., 64., 65., -61., 1., 44., * 0., -65., -24., 6., 24., 15., -25., * -6., 0., 12., -22., 8., -21., 15., * 9., -16., -3., 0., -20., 13., 12., * -6., -8., 9., 4., -8., 5., 0., * 1., 0., 4., 5., -6., -1., -3., * 0., -2., -8./ DATA DG00/0.0, 14.6, 10.7, -12.4, 1.1, -1.1, 0.7, * -5.4, 0.9, -7.7, -1.3, 1.6, -7.3, 2.9, * -3.2, 0.0, -0.7, -2.1, -2.8, -0.8, 2.5, * 1.0, -0.4, 0.9, 2.0, -0.6, -0.3, 1.2, * -0.4, -0.4, -0.3, 1.1, 1.1, -0.2, 0.6, * -0.9, -0.3, 0.2, -0.3, 0.4, -1.0, 0.3, * -0.5, -0.7, -0.4/ DATA DH00/0.0, 0.0, -22.5, 0.0, -20.6, -9.6, 0.0, * 6.0, -0.1, -14.2, 0.0, 2.1, 1.3, 5.0, * 0.3, 0.0, -0.1, 0.6, 1.7, 1.9, 0.1, * 0.0, -0.2, -1.4, 0.0, -0.8, 0.0, 0.9, * 0.0, 1.1, 0.0, 0.3, -0.1, -0.6, -0.7, * 0.2, 0.0, 0.1, 0.0, 0.0, 0.3, 0.6, * -0.4, 0.3, 0.7/ c c DATA MA,IYR,IPR/0,0,0/ IF(MA.NE.1) GOTO 10 IF(IY.NE.IYR) GOTO 30 GOTO 130 10 MA=1 C DO 20 N=1,11 N2=2*N-1 N2=N2*(N2-2) DO 20 M=1,N MN=N*(N-1)/2+M 20 REC(MN)=FLOAT((N-M)*(N+M-2))/FLOAT(N2) C 30 IYR=IY IF (IYR.LT.1965) IYR=1965 IF (IYR.GT.2005) IYR=2005 IF (IY.NE.IYR.AND.IPR.EQ.0) WRITE (*,999)IY,IYR IF (IYR.NE.IY) IPR=1 IF (IYR.LT.1970) GOTO 50 !INTERPOLATE BETWEEN 1965 - 1970 IF (IYR.LT.1975) GOTO 60 !INTERPOLATE BETWEEN 1970 - 1975 IF (IYR.LT.1980) GOTO 70 !INTERPOLATE BETWEEN 1975 - 1980 IF (IYR.LT.1985) GOTO 80 !INTERPOLATE BETWEEN 1980 - 1985 IF (IYR.LT.1990) GOTO 90 !INTERPOLATE BETWEEN 1985 - 1990 IF (IYR.LT.1995) GOTO 100 !INTERPOLATE BETWEEN 1990 - 1995 IF (IYR.LT.2000) GOTO 110 !INTERPOLATE BETWEEN 1995 - 2000 C C EXTRAPOLATE BEYOND 2000: C DT=FLOAT(IYR)-2000. DO 40 N=1,66 G(N)=G00(N) H(N)=H00(N) IF (N.GT.45) GOTO 40 G(N)=G(N)+DG00(N)*DT H(N)=H(N)+DH00(N)*DT 40 CONTINUE GOTO 300 C C INTERPOLATE BETWEEEN 1965 - 1970: C 50 F2=(IYR-1965)/5. F1=1.-F2 DO 55 N=1,66 G(N)=G65(N)*F1+G70(N)*F2 55 H(N)=H65(N)*F1+H70(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1970 - 1975: C 60 F2=(IYR-1970)/5. F1=1.-F2 DO 65 N=1,66 G(N)=G70(N)*F1+G75(N)*F2 65 H(N)=H70(N)*F1+H75(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1975 - 1980: C 70 F2=(IYR-1975)/5. F1=1.-F2 DO 75 N=1,66 G(N)=G75(N)*F1+G80(N)*F2 75 H(N)=H75(N)*F1+H80(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1980 - 1985: C 80 F2=(IYR-1980)/5. F1=1.-F2 DO 85 N=1,66 G(N)=G80(N)*F1+G85(N)*F2 85 H(N)=H80(N)*F1+H85(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1985 - 1990: C 90 F2=(IYR-1985)/5. F1=1.-F2 DO 95 N=1,66 G(N)=G85(N)*F1+G90(N)*F2 95 H(N)=H85(N)*F1+H90(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1990 - 1995: C 100 F2=(IYR-1990)/5. F1=1.-F2 DO 105 N=1,66 G(N)=G90(N)*F1+G95(N)*F2 105 H(N)=H90(N)*F1+H95(N)*F2 GOTO 300 C C INTERPOLATE BETWEEN 1995 - 2000: C 110 F2=(IYR-1995)/5. F1=1.-F2 DO 115 N=1,66 G(N)=G95(N)*F1+G00(N)*F2 115 H(N)=H95(N)*F1+H00(N)*F2 GOTO 300 C C COEFFICIENTS FOR A GIVEN YEAR HAVE BEEN CALCULATED; NOW MULTIPLY C THEM BY SCHMIDT NORMALIZATION FACTORS: C 300 S=1. DO 120 N=2,11 MN=N*(N-1)/2+1 S=S*FLOAT(2*N-3)/FLOAT(N-1) G(MN)=G(MN)*S H(MN)=H(MN)*S P=S DO 120 M=2,N AA=1. IF (M.EQ.2) AA=2. P=P*SQRT(AA*FLOAT(N-M+1)/FLOAT(N+M-2)) MNN=MN+M-1 G(MNN)=G(MNN)*P 120 H(MNN)=H(MNN)*P C C NOW CALCULATE THE FIELD COMPONENTS C (IN CASE OF MULTIPLE INVOCATIONS WITH THE SAME VALUES OF IY AND NM, C CALCULATIONS START RIGHT HERE): C 130 PP=1./R P=PP K=NM+1 DO 150 N=1,K P=P*PP A(N)=P 150 B(N)=P*N P=1. D=0. BBR=0. BBT=0. BBF=0. U=T CF=COS(F) SF=SIN(F) C=COS(U) S=SIN(U) DO 200 M=1,K IF(M.EQ.1) GOTO 160 MM=M-1 W=X X=W*CF+Y*SF Y=Y*CF-W*SF GOTO 170 160 X=0. Y=1. 170 Q=P Z=D BI=0. P2=0. D2=0. DO 190 N=M,K AN=A(N) MN=N*(N-1)/2+M E=G(MN) HH=H(MN) W=E*Y+HH*X BBR=BBR+B(N)*W*Q BBT=BBT-AN*W*Z IF(M.EQ.1) GOTO 180 QQ=Q IF(S.LT.1.E-5) QQ=Z BI=BI+AN*(E*X-HH*Y)*QQ 180 XK=REC(MN) DP=C*Z-S*Q-XK*D2 PM=C*Q-XK*P2 D2=Z P2=Q Z=DP 190 Q=PM D=S*D+C*P P=S*P IF(M.EQ.1) GOTO 200 BI=BI*MM BBF=BBF+BI 200 CONTINUE C BR=BBR BT=BBT IF(S.LT.1.E-5) GOTO 210 BF=BBF/S RETURN 210 IF(C.LT.0.) BBF=-BBF BF=BBF RETURN C 999 FORMAT(//1X, * 'IGRF WARNS:**** YEAR IS OUT OF INTERVAL 1965-2005: IY =',I5,/, *', CALCULATIONS WILL BE DONE FOR IYR =',I5,' ****'//) END C c SUBROUTINE DIP(PS,X,Y,Z,BX,BY,BZ) C C C CALCULATES GSM COMPONENTS OF A GEODIPOLE FIELD WITH THE DIPOLE MOMENT C CORRESPONDING TO THE EPOCH OF 2000. C C----INPUT PARAMETERS: C PS - GEODIPOLE TILT ANGLE IN RADIANS, C X,Y,Z - GSM COORDINATES IN RE (1 RE = 6371.2 km) C C----OUTPUT PARAMETERS: C BX,BY,BZ - FIELD COMPONENTS IN GSM SYSTEM, IN NANOTESLA. C C LAST MODIFICATION: JAN. 5, 2001. THE VALUE OF THE DIPOLE MOMENT WAS UPDATED TO 2000. C AND A "SAVE" STATEMENT HAS BEEN ADDED, TO AVOID POTENTIAL PROBLEMS WITH SOME C FORTRAN COMPILERS C C WRITTEN BY: N. A. TSYGANENKO C SAVE M,PSI DATA M,PSI/0,5./ IF(M.EQ.1.AND.ABS(PS-PSI).LT.1.E-5) GOTO 1 SPS=SIN(PS) CPS=COS(PS) PSI=PS M=1 1 P=X**2 U=Z**2 V=3.*Z*X T=Y**2 Q=30115./SQRT(P+T+U)**5 BX=Q*((T+U-2.*P)*SPS-V*CPS) BY=-3.*Y*Q*(X*SPS+Z*CPS) BZ=Q*((P+T-2.*U)*CPS-V*SPS) RETURN END c SUBROUTINE SUN(IYR,IDAY,IHOUR,MIN,ISEC,GST,SLONG,SRASN,SDEC) C C CALCULATES FOUR QUANTITIES NECESSARY FOR COORDINATE TRANSFORMATIONS C WHICH DEPEND ON SUN POSITION (AND, HENCE, ON UNIVERSAL TIME AND SEASON) C C------- INPUT PARAMETERS: C IYR,IDAY,IHOUR,MIN,ISEC - YEAR, DAY, AND UNIVERSAL TIME IN HOURS, MINUTES, C AND SECONDS (IDAY=1 CORRESPONDS TO JANUARY 1). C C------- OUTPUT PARAMETERS: C GST - GREENWICH MEAN SIDEREAL TIME, SLONG - LONGITUDE ALONG ECLIPTIC C SRASN - RIGHT ASCENSION, SDEC - DECLINATION OF THE SUN (RADIANS) C ORIGINAL VERSION OF THIS SUBROUTINE HAS BEEN COMPILED FROM: C RUSSELL, C.T., COSMIC ELECTRODYNAMICS, 1971, V.2, PP.184-196. C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT FROM THE PREVIOUS VERSION) C C ORIGINAL VERSION WRITTEN BY: Gilbert D. Mead C DOUBLE PRECISION DJ,FDAY DATA RAD/57.295779513/ C IF(IYR.LT.1901.OR.IYR.GT.2099) RETURN FDAY=DFLOAT(IHOUR*3600+MIN*60+ISEC)/86400.D0 DJ=365*(IYR-1900)+(IYR-1901)/4+IDAY-0.5D0+FDAY T=DJ/36525. VL=DMOD(279.696678+0.9856473354*DJ,360.D0) GST=DMOD(279.690983+.9856473354*DJ+360.*FDAY+180.,360.D0)/RAD G=DMOD(358.475845+0.985600267*DJ,360.D0)/RAD SLONG=(VL+(1.91946-0.004789*T)*SIN(G)+0.020094*SIN(2.*G))/RAD IF(SLONG.GT.6.2831853) SLONG=SLONG-6.2831853 IF (SLONG.LT.0.) SLONG=SLONG+6.2831853 OBLIQ=(23.45229-0.0130125*T)/RAD SOB=SIN(OBLIQ) SLP=SLONG-9.924E-5 C C THE LAST CONSTANT IS A CORRECTION FOR THE ANGULAR ABERRATION DUE TO C THE ORBITAL MOTION OF THE EARTH C SIND=SOB*SIN(SLP) COSD=SQRT(1.-SIND**2) SC=SIND/COSD SDEC=ATAN(SC) SRASN=3.141592654-ATAN2(COS(OBLIQ)/SOB*SC,-COS(SLP)/COSD) RETURN END c SUBROUTINE SPHCAR(R,TETA,PHI,X,Y,Z,J) C C CONVERTS SPHERICAL COORDS INTO CARTESIAN ONES AND VICA VERSA C (TETA AND PHI IN RADIANS). C C J &Gt 0 J &Lt 0 C-----INPUT: J,R,TETA,PHI J,X,Y,Z C----OUTPUT: X,Y,Z R,TETA,PHI C C LAST MOFIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C IF(J.GT.0) GOTO 3 SQ=X**2+Y**2 R=SQRT(SQ+Z**2) IF (SQ.NE.0.) GOTO 2 PHI=0. IF (Z.LT.0.) GOTO 1 TETA=0. RETURN 1 TETA=3.141592654 RETURN 2 SQ=SQRT(SQ) PHI=ATAN2(Y,X) TETA=ATAN2(SQ,Z) IF (PHI.LT.0.) PHI=PHI+6.28318531 RETURN 3 SQ=R*SIN(TETA) X=SQ*COS(PHI) Y=SQ*SIN(PHI) Z=R*COS(TETA) RETURN END c SUBROUTINE BSPCAR(TETA,PHI,BR,BTET,BPHI,BX,BY,BZ) C C CALCULATES CARTESIAN FIELD COMPONENTS FROM SPHERICAL ONES C-----INPUT: TETA,PHI - SPHERICAL ANGLES OF THE POINT IN RADIANS C BR,BTET,BPHI - SPHERICAL COMPONENTS OF THE FIELD C-----OUTPUT: BX,BY,BZ - CARTESIAN COMPONENTS OF THE FIELD C C LAST MOFIFICATION: JAN 5 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C S=SIN(TETA) C=COS(TETA) SF=SIN(PHI) CF=COS(PHI) BE=BR*S+BTET*C BX=BE*CF-BPHI*SF BY=BE*SF+BPHI*CF BZ=BR*C-BTET*S RETURN END c C SUBROUTINE RECALC(IYR,IDAY,IHOUR,MIN,ISEC) C C PREPARES ELEMENTS OF ROTATION MATRICES FOR TRANSFORMATIONS OF VECTORS BETWEEN C SEVERAL COORDINATE SYSTEMS, MOST FREQUENTLY USED IN SPACE PHYSICS. C C THIS SUBROUTINE SHOULD BE INVOKED BEFORE USING THE FOLLOWING SUBROUTINES: C GEOGSM, MAGSM, SMGSM, GSMGSE, GEIGEO. C C THERE IS NO NEED TO REPEATEDLY INVOKE RECALC, IF MULTIPLE CALCULATIONS ARE MADE C FOR THE SAME DATE AND TIME. C C-----INPUT PARAMETERS: C C IYR - YEAR NUMBER (FOUR DIGITS) C IDAY - DAY OF YEAR (DAY 1 = JAN 1) C IHOUR - HOUR OF DAY (00 TO 23) C MIN - MINUTE OF HOUR (00 TO 59) C ISEC - SECONDS OF MINUTE (00 TO 59) C C-----OUTPUT PARAMETERS: NONE (ALL OUTPUT QUANTITIES ARE PLACED C INTO THE COMMON BLOCK /GEOPACK/) C C OTHER SUBROUTINES CALLED BY THIS ONE: SUN C C ################################################ C # WRITTEN BY N.A. TSYGANENKO ON DEC.1, 1991 # C ################################################ c c Last modification: January 5, 2001. c The code has been modified to accept dates through 2005. c Also, a "save" statement was added, to avoid potential problems c with some Fortran compilers. C COMMON /GEOPACK/ ST0,CT0,SL0,CL0,CTCL,STCL,CTSL,STSL,SFI,CFI,SPS, * CPS,SHI,CHI,HI,PSI,XMUT,A11,A21,A31,A12,A22,A32,A13,A23,A33,DS3, * K,IY,CGST,SGST,BA(6) c SAVE IYE,IDE,IPR DATA IYE,IDE,IPR/3*0/ C IF (IYR.EQ.IYE.AND.IDAY.EQ.IDE) GOTO 5 C C IYE AND IDE ARE THE CURRENT VALUES OF YEAR AND DAY NUMBER C IY=IYR IDE=IDAY IF(IY.LT.1965) IY=1965 IF(IY.GT.2005) IY=2005 C C WE ARE RESTRICTED BY THE INTERVAL 1965-2005, C FOR WHICH THE IGRF COEFFICIENTS ARE KNOWN; IF IYR IS OUTSIDE THIS INTERVAL C THE SUBROUTINE PRINTS A WARNING (BUT DOES NOT REPEAT IT AT NEXT INVOCATIONS) C IF(IY.NE.IYR.AND.IPR.EQ.0) WRITE (*,10) IYR,IY IF(IY.NE.IYR) IPR=1 IYE=IY C C LINEAR INTERPOLATION OF THE GEODIPOLE MOMENT COMPONENTS BETWEEN THE C VALUES FOR THE NEAREST EPOCHS: C IF (IY.LT.1970) THEN !1965-1970 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1965.)/5. F1=1.D0-F2 G10=30334.*F1+30220.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-2119.*F1-2068.*F2 H11=5776.*F1+5737.*F2 ELSEIF (IY.LT.1975) THEN !1970-1975 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1970.)/5. F1=1.D0-F2 G10=30220.*F1+30100.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-2068.*F1-2013.*F2 H11=5737.*F1+5675.*F2 ELSEIF (IY.LT.1980) THEN !1975-1980 F2=(DFLOAT(IY)+DFLOAT(IDAY)/365.-1975.)/5. F1=1.D0-F2 G10=30100.*F1+29992.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-2013.*F1-1956.*F2 H11=5675.*F1+5604.*F2 ELSEIF (IY.LT.1985) THEN !1980-1985 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1980.)/5. F1=1.D0-F2 G10=29992.*F1+29873.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-1956.*F1-1905.*F2 H11=5604.*F1+5500.*F2 ELSEIF (IY.LT.1990) THEN !1985-1990 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1985.)/5. F1=1.D0-F2 G10=29873.*F1+29775.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-1905.*F1-1848.*F2 H11=5500.*F1+5406.*F2 ELSEIF (IY.LT.1995) THEN !1990-1995 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1990.)/5. F1=1.D0-F2 G10=29775.*F1+29682.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-1848.*F1-1789.*F2 H11=5406.*F1+5318.*F2 ELSEIF (IY.LT.2000) THEN !1995-2000 F2=(FLOAT(IY)+FLOAT(IDAY)/365.-1995.)/5. F1=1.D0-F2 G10=29682.*F1+29615.*F2 ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-1789.*F1-1728.*F2 H11=5318.*F1+5186.*F2 ELSE !2000-2005 C C LINEAR EXTRAPOLATION BEYOND 2000 BY USING SECULAR VELOCITY COEFFICIENTS: C DT=FLOAT(IY)+FLOAT(IDAY)/366.-2000. G10=29615.-14.6*DT ! HERE G10 HAS OPPOSITE SIGN TO THAT IN IGRF TABLES G11=-1728.+10.7*DT H11=5186.-22.5*DT ENDIF C C NOW CALCULATE THE COMPONENTS OF THE UNIT VECTOR EzMAG IN GEO COORD.SYSTEM: C SIN(TETA0)*COS(LAMBDA0), SIN(TETA0)*SIN(LAMBDA0), AND COS(TETA0) C ST0 * CL0 ST0 * SL0 CT0 C SQ=G11**2+H11**2 SQQ=SQRT(SQ) SQR=SQRT(G10**2+SQ) SL0=-H11/SQQ CL0=-G11/SQQ ST0=SQQ/SQR CT0=G10/SQR STCL=ST0*CL0 STSL=ST0*SL0 CTSL=CT0*SL0 CTCL=CT0*CL0 C C THE CALCULATIONS ARE TERMINATED IF ONLY GEO-MAG TRANSFORMATION C IS TO BE DONE (IHOUR>24 IS THE AGREED INDICATOR FOR THIS CASE): C 5 IF (IHOUR.GT.24) RETURN C CALL SUN(IY,IDAY,IHOUR,MIN,ISEC,GST,SLONG,SRASN,SDEC) C C S1,S2, AND S3 ARE THE COMPONENTS OF THE UNIT VECTOR EXGSM=EXGSE IN THE C SYSTEM GEI POINTING FROM THE EARTH'S CENTER TO THE SUN: C S1=COS(SRASN)*COS(SDEC) S2=SIN(SRASN)*COS(SDEC) S3=SIN(SDEC) CGST=COS(GST) SGST=SIN(GST) C C DIP1, DIP2, AND DIP3 ARE THE COMPONENTS OF THE UNIT VECTOR EZSM=EZMAG C IN THE SYSTEM GEI: C DIP1=STCL*CGST-STSL*SGST DIP2=STCL*SGST+STSL*CGST DIP3=CT0 C C NOW CALCULATE THE COMPONENTS OF THE UNIT VECTOR EYGSM IN THE SYSTEM GEI C BY TAKING THE VECTOR PRODUCT D x S AND NORMALIZING IT TO UNIT LENGTH: C Y1=DIP2*S3-DIP3*S2 Y2=DIP3*S1-DIP1*S3 Y3=DIP1*S2-DIP2*S1 Y=SQRT(Y1*Y1+Y2*Y2+Y3*Y3) Y1=Y1/Y Y2=Y2/Y Y3=Y3/Y C C THEN IN THE GEI SYSTEM THE UNIT VECTOR Z = EZGSM = EXGSM x EYGSM = S x Y C HAS THE COMPONENTS: C Z1=S2*Y3-S3*Y2 Z2=S3*Y1-S1*Y3 Z3=S1*Y2-S2*Y1 C C THE VECTOR EZGSE (HERE DZ) IN GEI HAS THE COMPONENTS (0,-SIN(DELTA), C COS(DELTA)) = (0.,-0.397823,0.917462); HERE DELTA = 23.44214 DEG FOR C THE EPOCH 1978 (SEE THE BOOK BY GUREVICH OR OTHER ASTRONOMICAL HANDBOOKS). C HERE THE MOST ACCURATE TIME-DEPENDENT FORMULA IS USED: C DJ=FLOAT(365*(IY-1900)+(IY-1901)/4 +IDAY) * -0.5+FLOAT(IHOUR*3600+MIN*60+ISEC)/86400. T=DJ/36525. OBLIQ=(23.45229-0.0130125*T)/57.2957795 DZ1=0. DZ2=-SIN(OBLIQ) DZ3=COS(OBLIQ) C C THEN THE UNIT VECTOR EYGSE IN GEI SYSTEM IS THE VECTOR PRODUCT DZ x S : C DY1=DZ2*S3-DZ3*S2 DY2=DZ3*S1-DZ1*S3 DY3=DZ1*S2-DZ2*S1 C C THE ELEMENTS OF THE MATRIX GSE TO GSM ARE THE SCALAR PRODUCTS: C CHI=EM22=(EYGSM,EYGSE), SHI=EM23=(EYGSM,EZGSE), EM32=(EZGSM,EYGSE)=-EM23, C AND EM33=(EZGSM,EZGSE)=EM22 C CHI=Y1*DY1+Y2*DY2+Y3*DY3 SHI=Y1*DZ1+Y2*DZ2+Y3*DZ3 HI=ASIN(SHI) C C TILT ANGLE: PSI=ARCSIN(DIP,EXGSM) C SPS=DIP1*S1+DIP2*S2+DIP3*S3 CPS=SQRT(1.-SPS**2) PSI=ASIN(SPS) C C THE ELEMENTS OF THE MATRIX MAG TO SM ARE THE SCALAR PRODUCTS: C CFI=GM22=(EYSM,EYMAG), SFI=GM23=(EYSM,EXMAG); THEY CAN BE DERIVED AS FOLLOWS: C C IN GEO THE VECTORS EXMAG AND EYMAG HAVE THE COMPONENTS (CT0*CL0,CT0*SL0,-ST0) C AND (-SL0,CL0,0), RESPECTIVELY. HENCE, IN GEI THE COMPONENTS ARE: C EXMAG: CT0*CL0*COS(GST)-CT0*SL0*SIN(GST) C CT0*CL0*SIN(GST)+CT0*SL0*COS(GST) C -ST0 C EYMAG: -SL0*COS(GST)-CL0*SIN(GST) C -SL0*SIN(GST)+CL0*COS(GST) C 0 C THE COMPONENTS OF EYSM IN GEI WERE FOUND ABOVE AS Y1, Y2, AND Y3; C NOW WE ONLY HAVE TO COMBINE THE QUANTITIES INTO SCALAR PRODUCTS: C EXMAGX=CT0*(CL0*CGST-SL0*SGST) EXMAGY=CT0*(CL0*SGST+SL0*CGST) EXMAGZ=-ST0 EYMAGX=-(SL0*CGST+CL0*SGST) EYMAGY=-(SL0*SGST-CL0*CGST) CFI=Y1*EYMAGX+Y2*EYMAGY SFI=Y1*EXMAGX+Y2*EXMAGY+Y3*EXMAGZ C XMUT=(ATAN2(SFI,CFI)+3.1415926536)*3.8197186342 C C THE ELEMENTS OF THE MATRIX GEO TO GSM ARE THE SCALAR PRODUCTS: C C A11=(EXGEO,EXGSM), A12=(EYGEO,EXGSM), A13=(EZGEO,EXGSM), C A21=(EXGEO,EYGSM), A22=(EYGEO,EYGSM), A23=(EZGEO,EYGSM), C A31=(EXGEO,EZGSM), A32=(EYGEO,EZGSM), A33=(EZGEO,EZGSM), C C ALL THE UNIT VECTORS IN BRACKETS ARE ALREADY DEFINED IN GEI: C C EXGEO=(CGST,SGST,0), EYGEO=(-SGST,CGST,0), EZGEO=(0,0,1) C EXGSM=(S1,S2,S3), EYGSM=(Y1,Y2,Y3), EZGSM=(Z1,Z2,Z3) C AND THEREFORE: C A11=S1*CGST+S2*SGST A12=-S1*SGST+S2*CGST A13=S3 A21=Y1*CGST+Y2*SGST A22=-Y1*SGST+Y2*CGST A23=Y3 A31=Z1*CGST+Z2*SGST A32=-Z1*SGST+Z2*CGST A33=Z3 C 10 FORMAT(//1X, * '****RECALC WARNS: YEAR IS OUT OF INTERVAL 1965-2005: IYR=',I4, * /,6X,'CALCULATIONS WILL BE DONE FOR IYR=',I4,/) RETURN END C SUBROUTINE GEOMAG(XGEO,YGEO,ZGEO,XMAG,YMAG,ZMAG,J,IYR) C C CONVERTS GEOGRAPHIC (GEO) TO DIPOLE (MAG) COORDINATES OR VICA VERSA. C IYR IS YEAR NUMBER (FOUR DIGITS). C C J &Gt 0 J &Lt 0 C-----INPUT: J,XGEO,YGEO,ZGEO,IYR J,XMAG,YMAG,ZMAG,IYR C-----OUTPUT: XMAG,YMAG,ZMAG XGEO,YGEO,ZGEO C C OTHER SUBROUTINES CALLED BY THIS ONE: RECALC C C LAST MOFIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ ST0,CT0,SL0,CL0,CTCL,STCL,CTSL,STSL,AB(19), * K,IY,BB(8) SAVE II DATA II/1/ C IF(IYR.EQ.II) GOTO 1 II=IYR CALL RECALC(II,0,25,0,0) 1 CONTINUE IF(J.LT.0) GOTO 2 XMAG=XGEO*CTCL+YGEO*CTSL-ZGEO*ST0 YMAG=YGEO*CL0-XGEO*SL0 ZMAG=XGEO*STCL+YGEO*STSL+ZGEO*CT0 RETURN 2 XGEO=XMAG*CTCL-YMAG*SL0+ZMAG*STCL YGEO=XMAG*CTSL+YMAG*CL0+ZMAG*STSL ZGEO=ZMAG*CT0-XMAG*ST0 RETURN END c c SUBROUTINE GEIGEO(XGEI,YGEI,ZGEI,XGEO,YGEO,ZGEO,J) C C CONVERTS EQUATORIAL INERTIAL (GEI) TO GEOGRAPHICAL (GEO) COORDS C OR VICA VERSA. C J &Gt 0 J &Lt 0 C----INPUT: J,XGEI,YGEI,ZGEI J,XGEO,YGEO,ZGEO C----OUTPUT: XGEO,YGEO,ZGEO XGEI,YGEI,ZGEI C C ATTENTION: SUBROUTINE RECALC MUST BE INVOKED BEFORE GEIGEO IN TWO CASES: C /A/ BEFORE THE FIRST INVOCATION OF GEIGEO C /B/ IF THE CURRENT VALUES OF IYEAR,IDAY,IHOUR,MIN,ISEC HAVE BEEN CHANGED C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ A(27),KKKK(2),CGST,SGST,B(6) C IF(J.LT.0) GOTO 1 XGEO=XGEI*CGST+YGEI*SGST YGEO=YGEI*CGST-XGEI*SGST ZGEO=ZGEI RETURN 1 XGEI=XGEO*CGST-YGEO*SGST YGEI=YGEO*CGST+XGEO*SGST ZGEI=ZGEO RETURN END C C SUBROUTINE MAGSM(XMAG,YMAG,ZMAG,XSM,YSM,ZSM,J) C C CONVERTS DIPOLE (MAG) TO SOLAR MAGNETIC (SM) COORDINATES OR VICA VERSA C C J &Gt 0 J &Lt 0 C----INPUT: J,XMAG,YMAG,ZMAG J,XSM,YSM,ZSM C----OUTPUT: XSM,YSM,ZSM XMAG,YMAG,ZMAG C C ATTENTION: SUBROUTINE RECALC MUST BE INVOKED BEFORE MAGSM IN TWO CASES: C /A/ BEFORE THE FIRST INVOCATION OF MAGSM C /B/ IF THE VALUES OF IYEAR,IDAY,IHOUR,MIN,ISEC HAVE BEEN CHANGED C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ A(8),SFI,CFI,B(7),AB(10),K,IY,BA(8) C IF (J.LT.0) GOTO 1 XSM=XMAG*CFI-YMAG*SFI YSM=XMAG*SFI+YMAG*CFI ZSM=ZMAG RETURN 1 XMAG=XSM*CFI+YSM*SFI YMAG=YSM*CFI-XSM*SFI ZMAG=ZSM RETURN END C SUBROUTINE GSMGSE(XGSM,YGSM,ZGSM,XGSE,YGSE,ZGSE,J) C C CONVERTS GEOCENTRIC SOLAR MAGNETOSPHERIC (GSM) COORDS TO SOLAR ECLIPTIC (GSE) ONES C OR VICA VERSA. C J &Gt 0 J &Lt 0 C-----INPUT: J,XGSM,YGSM,ZGSM J,XGSE,YGSE,ZGSE C----OUTPUT: XGSE,YGSE,ZGSE XGSM,YGSM,ZGSM C C ATTENTION: SUBROUTINE RECALC MUST BE INVOKED BEFORE GSMGSE IN TWO CASES: C /A/ BEFORE THE FIRST INVOCATION OF GSMGSE C /B/ IF THE VALUES OF IYEAR,IDAY,IHOUR,MIN,ISEC HAVE BEEN CHANGED C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ A(12),SHI,CHI,AB(13),K,IY,BA(8) C IF (J.LT.0) GOTO 1 XGSE=XGSM YGSE=YGSM*CHI-ZGSM*SHI ZGSE=YGSM*SHI+ZGSM*CHI RETURN 1 XGSM=XGSE YGSM=YGSE*CHI+ZGSE*SHI ZGSM=ZGSE*CHI-YGSE*SHI RETURN END C SUBROUTINE SMGSM(XSM,YSM,ZSM,XGSM,YGSM,ZGSM,J) C C CONVERTS SOLAR MAGNETIC (SM) TO GEOCENTRIC SOLAR MAGNETOSPHERIC C (GSM) COORDINATES OR VICA VERSA. C J &Gt 0 J &Lt 0 C-----INPUT: J,XSM,YSM,ZSM J,XGSM,YGSM,ZGSM C----OUTPUT: XGSM,YGSM,ZGSM XSM,YSM,ZSM C C ATTENTION: SUBROUTINE RECALC MUST BE INVOKED BEFORE SMGSM IN TWO CASES: C /A/ BEFORE THE FIRST INVOCATION OF SMGSM C /B/ IF THE VALUES OF IYEAR,IDAY,IHOUR,MIN,ISEC HAVE BEEN CHANGED C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ A(10),SPS,CPS,B(15),K,IY,AB(8) IF (J.LT.0) GOTO 1 XGSM=XSM*CPS+ZSM*SPS YGSM=YSM ZGSM=ZSM*CPS-XSM*SPS RETURN 1 XSM=XGSM*CPS-ZGSM*SPS YSM=YGSM ZSM=XGSM*SPS+ZGSM*CPS RETURN END C SUBROUTINE GEOGSM(XGEO,YGEO,ZGEO,XGSM,YGSM,ZGSM,J) C C CONVERTS GEOGRAPHIC (GEO) TO SOLAR MAGNETOSPHERIC (SM) COORDINATES OR VICA VERSA. C C J &Gt 0 J &Lt 0 C----- INPUT: J,XGEO,YGEO,ZGEO J,XGSM,YGSM,ZGSM C---- OUTPUT: XGSM,YGSM,ZGSM XGEO,YGEO,ZGEO C C ATTENTION: SUBROUTINE RECALC MUST BE INVOKED BEFORE GEOGSM IN TWO CASES: C /A/ BEFORE THE FIRST INVOCATION OF GEOGSM C /B/ IF THE VALUES OF IYEAR,IDAY,IHOUR,MIN,ISEC HAVE BEEN CHANGED C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C COMMON /GEOPACK/ AA(17),A11,A21,A31,A12,A22,A32,A13,A23,A33, * D,K,IY,B(8) C IF (J.LT.0) GOTO 1 XGSM=A11*XGEO+A12*YGEO+A13*ZGEO YGSM=A21*XGEO+A22*YGEO+A23*ZGEO ZGSM=A31*XGEO+A32*YGEO+A33*ZGEO RETURN 1 XGEO=A11*XGSM+A21*YGSM+A31*ZGSM YGEO=A12*XGSM+A22*YGSM+A32*ZGSM ZGEO=A13*XGSM+A23*YGSM+A33*ZGSM RETURN END C SUBROUTINE RHAND(X,Y,Z,R1,R2,R3,IOPT,PARMOD,EXNAME) C C COMPUTES RIGHT HAND EXPRESSIONS IN THE GEOMAGNETIC FIELD LINE EQUATION C (a subsidiary subroutine for the subr. STEP) C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C DIMENSION PARMOD(10) EXTERNAL EXNAME C COMMON /GEOPACK/ A(15),PSI,AA(10),DS3,K,IY,BB(8) CALL EXNAME(IOPT,PARMOD,PSI,X,Y,Z,BX,BY,BZ) IF (K.EQ.0) GOTO 1 CALL GEOGSM(XG,YG,ZG,X,Y,Z,-1) CALL SPHCAR(R,T,F,XG,YG,ZG,-1) CALL IGRF(IY,K,R,T,F,BR,BT,BF) CALL BSPCAR(T,F,BR,BT,BF,FX,FY,FZ) CALL GEOGSM(FX,FY,FZ,HX,HY,HZ,1) GOTO 2 1 CALL DIP(PSI,X,Y,Z,HX,HY,HZ) 2 BX=BX+HX BY=BY+HY BZ=BZ+HZ B=DS3/SQRT(BX**2+BY**2+BZ**2) R1=BX*B R2=BY*B R3=BZ*B RETURN END C SUBROUTINE STEP(N,X,Y,Z,DS,ERRIN,IOPT,PARMOD,EXNAME) C C RE-CALCULATES COORDS X,Y,Z FOR ONE STEP ALONG FIELD LINE. N IS MAXIMUM C ORDER OF HARMONICS IN MAIN FIELD EXPANSION, DS IS STEP SIZE, ERRIN IS C PERMISSIBLE ERROR VALUE, IOPT AND EXNAME - SEE COMMENTS TO SUBROUTINE TRACE C ALL THE PARAMETERS ARE INPUT ONES; OUTPUT IS THE RENEWED TRIPLET X,Y,Z C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES, BUT C SOME REDUNDANT STATEMENTS TAKEN OUT) C C WRITTEN BY: N. A. TSYGANENKO C C DIMENSION PARMOD(10) COMMON /GEOPACK/ A(26),DS3,K,IY,B(8) EXTERNAL EXNAME K=N 1 DS3=-DS/3. CALL RHAND(X,Y,Z,R11,R12,R13,IOPT,PARMOD,EXNAME) CALL RHAND(X+R11,Y+R12,Z+R13,R21,R22,R23,IOPT,PARMOD,EXNAME) CALL RHAND(X+.5*(R11+R21),Y+.5*(R12+R22),Z+.5* *(R13+R23),R31,R32,R33,IOPT,PARMOD,EXNAME) CALL RHAND(X+.375*(R11+3.*R31),Y+.375*(R12+3.*R32 *),Z+.375*(R13+3.*R33),R41,R42,R43,IOPT,PARMOD,EXNAME) CALL RHAND(X+1.5*(R11-3.*R31+4.*R41),Y+1.5*(R12- *3.*R32+4.*R42),Z+1.5*(R13-3.*R33+4.*R43), *R51,R52,R53,IOPT,PARMOD,EXNAME) ERRCUR=ABS(R11-4.5*R31+4.*R41-.5*R51)+ABS(R12-4.5*R32+4.*R42-.5* *R52)+ABS(R13-4.5*R33+4.*R43-.5*R53) IF (ERRCUR.LT.ERRIN) GOTO 2 DS=DS*.5 GOTO 1 2 X=X+.5*(R11+4.*R41+R51) Y=Y+.5*(R12+4.*R42+R52) Z=Z+.5*(R13+4.*R43+R53) IF(ERRCUR.LT.ERRIN*.04.AND.ABS(DS).LT.1.33) DS=DS*1.5 RETURN END C SUBROUTINE TRACE(XI,YI,ZI,DIR,RLIM,R0,IHARM,NP,IOPT,PARMOD,EXNAME, *XF,YF,ZF,XX,YY,ZZ,L) C C TRACES A FIELD LINE FROM AN ARBITRARY POINT OF SPACE TO THE EARTH'S C SURFACE OR TO A MODEL LIMITING BOUNDARY. C C------------- INPUT PARAMETERS: C C XI,YI,ZI - GSM COORDS OF INITIAL POINT (IN EARTH RADII), C C DIR - SIGN OF TRACING DIRECTION: IF DIR=1. THEN ANTIPARALLEL TO C B VECTOR (E.G. FROM NORTHERN TO SOUTHERN CONJUGATE POINT), C AND IF DIR=-1. THEN PARALLEL TO B. C C R0 - RADIUS OF A SPHERE (IN RE) FOR WHICH FOOTPOINT POINT COORDINATES C XF,YF,ZF ARE TO BE CALCULATED. C C RLIM - UPPER LIMIT OF THE GEOCENTRIC DISTANCE, WHERE THE TRACING IS TERMINATED. C C IHARM - THE HIGHEST ORDER OF SPHERICAL HARMONICS IN THE MAIN FIELD EXPANSION, C THIS PARAMETER DEPENDS ON A VERSION OF THE MAIN GEOMAGNETIC FIELD MODEL. C THE SUBROUTINE IGRF INCLUDED IN THIS PACKAGE HAS IHARM=10. C IF THE MAIN FIELD CAN BE ASSUMED PURELY DIPOLAR, THEN TAKE IHARM=0 C AND SPECIFY A VALUE OF THE GEODIPOLE TILT ANGLE PSI (IN RADIANS) C IN THE 16-TH ELEMENT OF THE COMMON BLOCK /GEOPACK/ BEFORE INVOKING TRACE. C OTHERWISE INVOKE RECALC BEFORE USING TRACE. C C NP - UPPER ESTIMATE OF THE NUMBER OF STEPS ALONG A FIELD LINE C (IN MOST CASES, NP=500 IS SUFFICIENT). C C IOPT - A MODEL INDEX; CAN BE USED FOR SPECIFYING AN OPTION OF THE EXTERNAL FIELD C MODEL (E.G., INTERVAL OF THE KP-INDEX). ALTERNATIVELY, ONE CAN USE THE ARRAY C PARMOD FOR THAT PURPOSE (SEE BELOW); IN THAT CASE IOPT CAN BE JUST IGNORED. C C PARMOD - A 10-ELEMENT ARRAY CONTAINING MODEL PARAMETERS, NEEDED FOR A UNIQUE C SPECIFICATION OF THE EXTERNAL FIELD. THE CONCRETE MEANING OF THE COMPONENTS C OF PARMOD DEPENDS ON A SPECIFIC VERSION OF THE EXTERNAL FIELD MODEL. C C EXNAME - NAME OF A SUBROUTINE PROVIDING COMPONENTS OF THE EXTERNAL MAGNETIC FIELD. C C-------------- OUTPUT PARAMETERS: C C XF,YF,ZF - GSM COORDS OF THE LAST CALCULATED POINT OF A FIELD LINE C XX,YY,ZZ - ARRAYS, CONTAINING COORDS OF FIELD LINE POINTS. THEIR SIZE SHOULD BE C NOT LESS THAN NP. C L - ACTUAL NUMBER OF THE CALCULATED FIELD LINE POINTS. IF L EXCEEDS NP, THE TRACING C TERMINATES, AND A WARNING IS DISPLAYED. C C C LAST MODIFICATION: JAN 5, 2001 (NO ESSENTIAL CHANGES) C C WRITTEN BY: N. A. TSYGANENKO C DIMENSION XX(NP),YY(NP),ZZ(NP), PARMOD(10) COMMON /GEOPACK/ AA(26),DD,K1,K2,BB(8) EXTERNAL EXNAME J=IHARM ERR=0.0005 L=0 DS=0.5*DIR X=XI Y=YI Z=ZI DD=DIR K1=IHARM AL=0. CALL RHAND(X,Y,Z,R1,R2,R3,IOPT,PARMOD,EXNAME) AD=SIGN(0.01,X*R1+Y*R2+Z*R3) RR=SQRT(X**2+Y**2+Z**2)+AD 1 L=L+1 IF(L.GT.NP) GOTO 7 XX(L)=X YY(L)=Y ZZ(L)=Z RYZ=Y**2+Z**2 R2=X**2+RYZ R=SQRT(R2) IF(R.GT.RLIM.OR.RYZ.GT.1600..OR.X.GT.20.) GOTO 8 IF(R.LT.R0.AND.RR.GT.R) GOTO 6 IF(R.GE.RR) GOTO 5 IF(R.GT.5.) GOTO 5 IF(R.GE.3.) GOTO 3 FC=0.2 IF(R-R0.LT.0.05) FC=0.05 AL=FC*(R-R0+0.2) DS=DIR*AL GOTO 4 3 DS=DIR AL=1. 4 XR=X YR=Y ZR=Z 5 RR=R IF(IHARM.NE.0) J=1+20./(R-AL) IF(J.GT.IHARM) J=IHARM CALL STEP(J,X,Y,Z,DS,ERR,IOPT,PARMOD,EXNAME) GOTO 1 6 R1=(R0-R)/(RR-R) X=X-(X-XR)*R1 Y=Y-(Y-YR)*R1 Z=Z-(Z-ZR)*R1 GOTO 8 7 WRITE (*,10) L=NP RETURN 8 XF=X YF=Y ZF=Z DO 9 I=L,NP XX(I)=XF YY(I)=YF 9 ZZ(I)=ZF RETURN 10 FORMAT(//,1X,'**** COMPUTATIONS IN THE SUBROUTINE TRACE', *' ARE TERMINATED: NP IS TOO SMALL ****'//) END c---------------------------------------------------------------------------------- c
Nikolai Tsyganenko - USRA/GSFC (ys2nt@lepvax.gsfc.nasa.gov)
Last updated: August 7, 2001