This section describes functions from file opt/geopack_ct.ct.
[X,Y,Z] = geopack_coordtrans(fromto,x,y,z,epoch)
[X,Y,Z] = geopack_coordtrans("fromto",x,y,z,epoch)
transforms Cartesian coordinates (x,y,z) to another system.
The first argument specifies the transformation, it must be a 4-6-character
string containing two coordinate system symbols. Valid coordinate
systems are GEO,GSM,GSE,GEI,MAG and SM. For example, "GEOGSM","GEISM",
"SMSM" and "MAGGSE" are valid first arguments where e.g. GEOGSM specifices
that (x,y,z) is in the GEO system and is to be transformed to the GSM system
(X,Y,Z). The last argument (epoch) is the number of milliseconds since
January 1, year 0000, see functions computeEPOCH, EPOCHbreakdown, parseEPOCH
and encodeEPOCH how to manipulate and construct epoch values.
The arguments x,y,z,epoch can be scalars or arrays. If they are arrays,
the must be of the same size. Scalars and arrays can be mixed, scalars
are implicitly promoted to arrays.
This function calls the GEOPACK Fortran routines by N. Tsyganenko et al.
The GEOPACK package operates in single precision.
Error codes:
-1: First arg not a string
-2: Second arg (x) must be int or real scalar or array
-3: Third arg (y) must be int or real scalar or array
-4: Fourth arg (z) must be int or real scalar or array
-5: Fifth arg (epoch) must be int or real scalar or array
-6: First arg not a string with 4, 5 or 6 characters
-7: First arg not a valid string (allowed coordsys: GEO,GSM,GSE,GEI,MAG,SM)
-8: Incompatible array dimensions
[Bx,By,Bz] = geopack_model(model,params,x,y,z,epoch; tiltangle)
[Bx,By,Bz] = geopack_model(model,params,x,y,z,epoch;tiltangle)
computes a Tsyganenko model magnetic field.
Inputs:
model: string specifying model to use
params: parameter vector for the model
x,y,z: GSM coordinates in units of R_E (6371.2 km)
epoch: Epoch used in IGRF part (and external, if
tiltangle is not given)
tiltangle: (optional) Dipole tilt angle in radians,
do not use with IGRF
Outputs:
Bx,By,Bz: GSM Cartesian B-field in nanotesla
Format of model specification string: either "MODEL"
or "MODEL,MODEL". Valid MODELs are DIP,IGRF,T89,T96,T96_NOFAC and NONE.
Empty string is synonym for NONE. The values are case
insensitive, i.e. both "T96" and "t96" can be used.
Examples of valid strings: "IGRF", "IGRF,T96", ",DIP",
"T89,", "None,t89". The T96_NOFAC is T96 from which Birkeland
currents have been left out; this switch was added by P.Janhunen.
Parameter vector for T96 and T96_NOFAC is #(Pdyn,Dst,By,Bz)
where Pdyn is solar wind dynamic pressure (nanopascal),
Dst the Dst index (nanotesla), By and Bz the IMF GSM
components (nanotesla).
Parameter vector for T89 is #(Kp), i.e., the vector contains
just one element, the Kp index. For DIP (dipole) and IGRF
models, the parameter vector is ignored (it must still be a
real or int vector, e.g., zeros(0) suffices).
If tiltangle is given as seventh input argument, it is used
in the external field model, and epoch only affects the internal
part. If tiltangle is not given, it is computed automatically
from the epoch.
This function calls the GEOPACK Fortran routines by N. Tsyganenko et al.
The GEOPACK package operates in single precision. Using sophisticated
methods such as Bulirsch-Stoer or quality-controlled Runge-Kutta for
field-line tracing using geopack_model may therefore be problematic;
the function geopack_trace that is provided for this purpose uses
simpler methods, for this reason. This is a warning to those who would
like to improve the speed of geopack_trace by implementing a better
ODE integrator.
Error codes:
-1: First arg (model) not a string
-2: Second arg (params) is not a real vector
-3: Third arg (x) is not real scalar or array
-4: Fourth arg (y) is not real scalar or array
-5: Fifth arg (z) is not real scalar or array
-6: Sixth arg (epoch) is not real scalar or array
-7: Seventh arg (tiltangle) not real scalar
-8: First arg (model) is an invalid string
-9: Two Tsyganenko models cannot be combined (the other must be IGRF)
-10: Second arg (params) is of improper length (must be 1 for T89, 4 for T96/T96_NOFAC)
1: tiltangle setting ignored since IGRF model in use (use DIP instead)
[x,y,z; X,Y,Z,success] = geopack_trace(model,params,domain,x0,y0,z0,epoch...)
[x,y,z; X,Y,Z,success] = geopack_trace(model,params,domain,x0,y0,z0,
epoch[,optional-args])
traces a field line in a model magnetic field, starting from (x0,y0,z0).
The model and params arguments are the same as for geopack_model.
Coordinates are GSM and measured in Earth radius R_E (6371.2 km).
The domain argument defines the region where the tracing is performed.
The tracing is stopped when the point moves outside the domain.
The meaning of the epoch argument is the same as in geopack_model.
Format of domain string: "r=1.01,r=4.5,z=0", i.e., a comma-separated
list of equations. Valid left-hand-sides are r,x,y,z (r=sqrt(x^2+y^2+z^2)).
Coordinates are GSM and units in R_E also here. Any real value is a
valid inequality right-hand-side. Up to 8 conditions may be used.
Optional arguments are var,value pairs where var is a string.
Supported are:
var value meaning
"sign" +1 or -1 +1:trace along B, -1:trace antiparallel to B
"tiltangle" real dipole tilt angle (radians), if not given,
computed from epoch, can be used only if
internal field model is DIP or none.
"maxstep" real maximum step size in R_E (default: 0.3)
"maxsteps" pos.int maximum steps to take (default: 2000)
This function calls the GEOPACK Fortran routines by N. Tsyganenko et al.
The GEOPACK package operates in single precision. Therefore, this function
uses a simple and robust midpoint method for integrating the field line.
Using more sophisticated methods (Bulirsch-Stoer or quality-controlled
Runge-Kutta) was tried, but did not work well in this case, because of
lack of precision. This is a warning to those who wouldlike to improve
the speed of geopack_trace by implementing a better ODE integrator.
With the default arguments, the error when mapping from x=-13 to
ionosphere is about 1 km in the ionospheric plane. By decreasing maxstep
from the default (0.3), the accuracy can be improved.
The optional output arguments X,Y,Z, if given, become vectors containing
the full traced trajectory. The seventh output argument (success) is
returned as 1 unless the number of maxsteps was exceeded, in which case
it will be returned as 0.
Notice that tracing can fail sometimes in the sense that the point
starts to circling around in the magnetosphere, never hitting the
defined boundaries. To avoid such cases from taking too long time
you can set the parameter "maxsteps" to smaller value than its default
2000 and quaery the success argument.
Error codes:
-1: First arg (model) not a string
-2: Second arg (params) is not a real vector
-3: Third arg (domain) is not a string
-4: Fourth arg (x0) is not int or real scalar
-5: Fifth arg (y0) is not int or real scalar
-6: Sixth arg (z0) is not int or real scalar
-7: Seventh arg (epoch) is not int or real scalar
-8: Odd number of optional args
-9: Optional args must be var,value,var,value,... where var is a string
-10: First arg (model) is an invalid string
-11: Two Tsyganenko models cannot be combined (the other must be IGRF)
-12: Second arg (params) is of improper length (must be 1 for T89, 4 for T96/T96_NOFAC)
-13: Invalid third arg (domain): must be "{R|X|Y|Z}={realvalue},..."
-14: Invalid optional argument (supported are: sign,tiltangle,maxstep)
-15: Invalid value for optional argument "sign": must be +1 or -1
-16: Invalid value for optional argument "tiltangle" (must be int or real scalar)
-17: Invalid value for optional argument "maxstep" (must be int or real scalar)
-18: Invalid value for optional argument "maxsteps" (must be positive int)
1: tiltangle setting ignored since IGRF model in use (use DIP instead)