tsyganenko

tsyganenko.spherical_to_cartesian(r, theta, phi)

r > 0 0 < theta < pi -pi < phi < pi all are assumed to be numpy arrays of equal dimensions

returns: x, y, z [tuple]

tsyganenko.tsyganenko_b(x, y, z, Txx='t01', InternalB='dipole', Dst=-30, Kp=4, Vx_sw=-750.0, N_sw=1.0, Bx_imf=0.0, By_imf=0.0, Bz_imf=-5.0)

Wrapper for Geopack’s trace() routine, for tracing field lines along Tsyganenko model

Inputs:

x0: x-coordinate(s) (GSE) to evaluate the field [R_E] (float) y0: y-coordinate(s) (GSE) to evaluate the field [R_E] (float) z0: z-coordinate(s) (GSE) to evaluate the field [R_E] (float)

–Keywords–

Txx: (external) field model, by Tsyganenko publication year. options: ‘t89’, ‘t96’, ‘t01’: Need to test: does ‘t04’ work? Is geomagnetic activity estimated with Kp or Dst in that case?

InternalB: internal model. options: ‘dipole’, ‘igrf’ Dst: Dst index in nT (geomagnetic activity), used for Txx= ‘t96’, ‘t01’ (‘t04’?) Kp: Kp index 0-9 (geomagnetic activity), used for Txx=’T89’ Vx_sw: solar wind x-component of velocity [km/s] (GSE), other components assumed zero N_sw: solar wind density [cm-3] Bx_imf: driving solar wind imf Bx [nT] (GSE) By_imf: driving solar wind GSE imf By [nT] (GSE) Bz_imf: driving solar wind GSE imf Bz [nT] (GSE) R_inner: inner radius [R_E] of the tracing, if the tracing goes r<R_inner it stops R_outer: outer radius [R_E] of the tracing, if the tracing goes r>R_outer it stops

dir: direction of the tracing relative to the magnetic field direction (parallel: dir= 1, anti-parallel: dir= -1)

If unspecified (dir=None), dir traces against the field when z0>0 with the field when z0<0

*** this is the opposite convention used by geopack’s trace() function?: From geopack.py docs: “dir: Direction of tracing. dir = -1 for parallel; dir = 1 for anti-parallel.”

Returns:

3-element tuple bx,by,bz bx: x-component(s) of field [nT] by: y-component(s) of field [nT] bz: z-component(s) of field [nT]

** All positional inputs can either be single values or numpy arrays (or lists) ** ** Depending on the inputs, the outputs bx, by, bz will either be single numbers or numpy arrays ** ** All inputs and outputs are in GSE coordinate system **

Example:

bx,by,bz = tsyganenko_b(0,0, 1., Txx = ‘t01’, Dst = -80, Kp = 4, Vx_sw = -750., N_sw = 4., Bx_imf = 0., By_imf = 0., Bz_imf = -10. )

bx,by,bz = tsyganenko_b([0,0,0],[0,0,0], [1.,2,3], Txx = ‘t01’, Dst = -80, Kp = 4, Vx_sw = -750., N_sw = 4., Bx_imf = 0., By_imf = 0., Bz_imf = -10. )

Notes:

Earth’s dipole is assumed to point (~exactly) in the -z GSE direction

Default solar wind and IMF parameters are for the EGI Vlasiator run, see Grandin et al. (2022?)

Other runs:

EGL (note: pulse arrives at magnetopause at roughly t=857 sec)
(~before pulse arrival): Dst = -30 (Grandin et al. 2022), N_sw = 1, Bz_imf = -5 (~after pulse arrival): Dst = -80 (Horaites et al.), N_sw = 4, Bz_imf = -10

The geopack package doesn’t allow for easy specification of the dipole tilt angle. Rather, a UT was found when the tilt was nearly zero (see gp.recalc() line below) The specified UT results in a tilt angle of theta~1e-5 radians, or 6e-4 degrees Technically, the solutions should be rotated back by theta, to be compared with Vlasiator’s zero-tilt runs But this small theta is within tolerance for most applications.

tsyganenko.tsyganenko_ocb(phi, lat_range=[0, 90], nsteps=10, **kwargs)

Find the open/closed field line boundary (OCB) algorithm uses a binary search within a specified latitude range

Inputs:

phi: ~longitude, in degrees -180<=phi<=180 lat_range: 2-element list or numpy array,

containing min. and max. latidues [degrees] to search within -90<=lat<=90

kwargs are passed to tsyanenko_open()

Returns:

Estimate of the OCB latitude at the given phi, in degrees

Notes:

Algorithm assumes OBC latitude is a single-valued function of phi

Theoretical accuracy of the OCB determination is ~ (lat_range[1]-lat_range[0]) / 2^nsteps

Example: # dayside (noon) cusp

tsyganenko_ocb(0, lat_range = [60,80], nsteps = 10,
Txx = ‘t01’, Dst = -80, Kp = 4, Vx_sw = -750., N_sw = 4., Bx_imf = 0., By_imf = 0., Bz_imf = -10., R_inner = 1., R_outer=15., dir = None, maxloop = 10000)

tsyganenko.tsyganenko_open(phi, lat, R_inner=1, R_outer=15, **kwargs)

Checks whether the field line starting at radius ~R_inner will trace out to beyond R_outer. R_outer is chosen to be large, so if a magnetic field line makes it out this far, it may be assumed to be open If the tracing crosses R_inner, the field line is closed

Inputs:

phi: ~longitude, in degrees -180<=phi<=180 lat: geographic latitude, in degrees -90<=lat<=90

e.g.,
(phi=0, lat = 0) corresponds with subsolar point (phi=anything, lat = 90) corresponds with geographic north pole

R_inner: inner radius [R_E] of the tracing, if the tracing goes r<R_inner it stops R_outer: outer radius [R_E] of the tracing, if the tracing goes r>R_outer it stops

Keywords (and kwargs) all get passed to tsyganenko_trace()

Returns:

Boolean—: True (if open) False (if closed)

Example:

tsyganenko_open(0, 45) # returns False tsyganenko_open(0, 80) # returns True

tsyganenko.tsyganenko_trace(x0, y0, z0, Txx='t01', InternalB='dipole', Dst=-30, Kp=4, Vx_sw=-750.0, N_sw=1.0, Bx_imf=0.0, By_imf=0.0, Bz_imf=-5.0, R_inner=0.99, R_outer=4.8, dir=None, maxloop=20000)

Wrapper for Geopack’s trace() routine, for tracing field lines along Tsyganenko model

Inputs:

x0: initial x-coordinate (GSE) of field tracing [R_E] (float) y0: initial y-coordinate (GSE) of field tracing [R_E] (float) z0: initial z-coordinate (GSE) of field tracing [R_E] (float)

–Keywords–

Txx:

(external) field model, by Tsyganenko publication year. options: ‘t89’, ‘t96’, ‘t01’: Need to test: does ‘t04’ work? Is geomagnetic activity estimated with Kp or Dst in that case?

InternalB: internal model. options: ‘dipole’, ‘igrf’ Dst: Dst index in nT (geomagnetic activity), used for Txx= ‘t96’, ‘t01’ (‘t04’?) Kp: Kp index 0-9 (geomagnetic activity), used for Txx=’T89’ Vx_sw: solar wind x-component of velocity [km/s] (GSE), other components assumed zero N_sw: solar wind density [cm-3] Bx_imf: driving solar wind imf Bx [nT] (GSE) By_imf: driving solar wind GSE imf By [nT] (GSE) Bz_imf: driving solar wind GSE imf Bz [nT] (GSE) R_inner: inner radius [R_E] of the tracing, if the tracing goes r<R_inner it stops R_outer: outer radius [R_E] of the tracing, if the tracing goes r>R_outer it stops

dir: direction of the tracing relative to the magnetic field direction (parallel: dir= 1, anti-parallel: dir= -1)

If unspecified (dir=None), dir traces against the field when z0>0 with the field when z0<0

*** this is the opposite convention used by geopack’s trace() function?: From geopack.py docs: “dir: Direction of tracing. dir = -1 for parallel; dir = 1 for anti-parallel.”

Returns:

6-element tuple x,y,z,xx,yy,zz x: final x-coordinate(s) of field tracing [R_E] y: final y-coordinate(s) of field tracing [R_E] z: final z-coordinate(s) of field tracing [R_E] xx: numpy array containing the traced field line x-coordinates yy: numpy array containing the traced field line y-coordinates zz: numpy array containing the traced field line z-coordinates

** All inputs and outputs are in GSE coordinate system **

Example:

x,y,z,xx,yy,zz = tsyganenko_trace(0,0, 1., Txx = ‘t01’, Dst = -80, Kp = 4, Vx_sw = -750., N_sw = 4., Bx_imf = 0., By_imf = 0., Bz_imf = -10., R_inner = 1., R_outer=5., dir = None, maxloop = 20000 )

Notes:

Earth’s dipole is assumed to point (~exactly) in the -z GSE direction

Default solar wind and IMF parameters are for the EGI Vlasiator run, see Grandin et al. (2022?)

Other runs:

EGL (note: pulse arrives at magnetopause at roughly t=857 sec)
(~before pulse arrival): Dst = -30 (Grandin et al. 2022), N_sw = 1, Bz_imf = -5 (~after pulse arrival): Dst = -80 (Horaites et al.), N_sw = 4, Bz_imf = -10

The geopack package doesn’t allow for easy specification of the dipole tilt angle. Rather, a UT was found when the tilt was nearly zero (see gp.recalc() line below) The specified UT results in a tilt angle of theta~1e-5 radians, or 6e-4 degrees Technically, the solutions should be rotated back by theta, to be compared with Vlasiator’s zero-tilt runs But this small theta is within tolerance for most applications.