Skip to main content

Geopack08 wrapper for Python

Project description

PyGeopack

A Python wrapper for Geopack-2008. This includes the T89, T96, T01 and TS05 (or is it TS04? I don't know...) magnetic field models for Earth's magnetosphere. See https://ccmc.gsfc.nasa.gov/modelweb/magnetos/tsygan.html and http://geo.phys.spbu.ru/~tsyganenko/modeling.html for more information.

Requirements

The following Python packages will be installed automatically:

  • numpy
  • PyFileIO
  • RecarrayTools
  • DateTimeTools

The following packages will also be required for running the PyGeopack.UpdateParameters() routine:

  • kpindex
  • pyomnidata

Installation

Firstly a few environment variables need setting up: $KPDATA_PATH, $OMNIDATA_PATH and $GEOPACK_PATH, which will point to the Kp index data, the omni data and the Geopack data, respectively. This can be done by including the following in your ~/.bashrc file, or by running it in the terminal before starting Python:

export KPDATA_PATH=/path/to/kp
export OMNIDATA_PATH=/path/to/omni
export GEOPACK_PATH=/path/to/geopack/data

where both of those directories must be writable by the current user, unless the data already exist in them.

Then simply install using pip3:

pip3 install PyGeopack --user

or by downloading the latest release on GitHub and running:

pip3 install PyGeopack-0.1.0-py3-none-any.whl --user

NOTE: You should uninstall any previous versions before installing this. If you had a version installed before 0.0.12 - you will need to remove the old shared object files - they are likely to be contained somewhere like (depending on the Python version used):

~/.local/lib/python3.6/site-packages/PyGeopack/

It's best just to remove everyting within that folder!

Post-install

After installation, the PyGeopack module will attempt to locate the OMNI data required for the models. If these data exist already in $GEOPACK_PATH then it will load into memory. If they don't exist, then the user will be shown a warning - the next section explains how to fix this.

Usage

There are three main uses for this Python package:

  1. Calculating the model magnetic field at any given point in space.
  2. Tracing along the magnetic field.
  3. Coordinate conversions.

Before doing any of the above, it's recommended that you grab the up to date omni parameters - the UpdateParameters routine will download and update the Kp index and OMNI parameters, then calculate the G and W parameters required for the models:

import PyGeopack as gp
gp.UpdateParameters(SkipWParameters=True)

The SkipWParameters keyword (set to True by default) can be used to skip the lengthy process of calculating the six W parameters for the TS05 magnetic field model - if True then these will be filled with zeros. Apparently they aren't all that important anyway. The code included in this module can calculate them and is Tsyganenko's own code, but it produces different numbers to those given in the files on Tsyganenko's website! No idea why, so use them with caution!

1. Calculating the model field.

To calculate the model field, use the ModelField function:

Bx,By,Bz = gp.ModelField(x,y,z,Date,ut,Model='T96',CoordIn='GSM',CoordOut='GSM',**kwargs)

Where x, y and z are the position(s) you wish to find the magnetic field at in RE - these can be either scalars or numpy.ndarrays. Date is the date as an integer, in the format yyyymmdd. ut is the time in hours, i.e. ut = hours + mins/60 + secs/3600. Model can be set to one of four strings currently: 'T89', 'T96' (default), 'T01' or 'TS05', more information about the models will be discussed further down in this document. CoordIn and CoordOut denote the input and output coordinate systems, respectively, and can be set to one of the three following options: 'GSM' (default), 'GSE' or 'SM'. **kwargs are discussed in detail in the "Model Parameters" section. Bx, By and Bz are the three components of the magnetic field model in nT for each of the input coordinates.

2. Tracing the magnetic field

Trace along the magnetic field from 1 or more starting positions in the magnetosphere x, y and z using the TraceField object:

T = gp.TraceField(x,y,z,Date,ut,Model='T96',CoordIn='GSM',CoordOut='GSM',
		alt=100.0,MaxLen=1000,DSMax=1.0,FlattenSingleTraces=True,Verbose=True,**kwargs)

x, y and z can either be scalars, or arrays of coordinates in RE. Date can either be a single date, for all traces, or an array of dates (one for each trace) where each is an integer in the format yyyymmhh. ut is the time in hours (i.e. ut = hours + mins/60) and can either be a single value for all traces, or an array with a time for each trace. Model denotes the field model being used - 'T89', 'T96' (default), 'T01' or 'TS05'. CoordIn and CoordOut denote the input and output coordinate systems, respectively, and can be set to one of the three following options: 'GSM' (default), 'GSE' or 'SM'. alt is the altitude in km atwhich the trace will be terminated (alt = 100.0 by default). MaxLen is the maximum number of steps for the traces (default is 1000). DSMax is the maximum step length in RE (default 1.0). FlattenSingleTraces if set to True will flatten the 2D arrays stored in the TraceField object if only a single trace is performed. Verbose is True will output the tracing progress to the terminal. **kwargs will be discussed in the "Model Parameters" section.

The TraceField object, T in the above code snippet, contains the following arrays:

x x coordinate along the field trace(s)
y y coordinate along the field trace(s)
z z coordinate along the field trace(s)
Bx x component of the magnetic field along the trace(s)
By y component of the magnetic field along the trace(s)
Bz z component of the magnetic field along the trace(s)
nstep number of steps along the trace(s)
GlatN Geographic latitude of the northern footprint(s)
GlatS Geographic latitude of the southern footprint(s)
MlatN Magnetic latitude of the northern footprint(s)
MlatS Magnetic latitude of the southern footprint(s)
GlonN Geographic longitude of the northern footprint(s)
GlonS Geographic longitude of the southern footprint(s)
MlonN Magnetic longitude of the northern footprint(s)
MlonS Magnetic longitude of the southern footprint(s)
GltN Geographic local time of the northern footprint(s)
GltS Geographic local time of the southern footprint(s)
MltN Magnetic local time of the northern footprint(s)
MltS Magnetic local time of the southern footprint(s)
Lshell L-shell of the field line(s) at the equator
MltE Magnetic local time of the equatorial footprint(s)
FlLen Field line length in planetary radii
R R = sqrt(x**2 + y**2 + z**2)

3. Coordinate conversion

This module contains the following Cartesian coordinate conversion routines:

x1,y1,z1 = gp.GSEtoGSM(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.GSEtoMAG(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.GSEtoSM(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.GSMtoGSE(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.GSMtoSM(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.MAGtoGSE(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.SMtoGSE(x0,y0,z0,Date,ut)
x1,y1,z1 = gp.SMtoGSM(x0,y0,z0,Date,ut)

where x0, y0 and z0 are either scalars or arrays of positions to be transformed. Dateis an integer in the format yyyymmdd and ut is the time in hours (i.e. ut = hours + minutes/60.0). x1, y1 and z1 are the transformed coordinates.

Also included are the following routines:

MLon,MLat = gp.GEOtoMAG(Lat,Lon,Date,ut)
Lon,Lat = gp.MAGtoGEO(MLat,MLon,Date,ut)

which convert between geographic ( Lat and Lon) and magnetic ( MLat and MLon) latitude and longitudes.

And for converting between magnetic longitude (MLon) and magnetic local time (MLT):

MLT = gp.MLONtoMLT(MLon,Date,ut)
MLon = gp.MLTtoMLON(MLT,Date,ut)

Descriptions of the coordinate systems:

Name Description x y z
GSE - Geocentric Solar Ecliptic fixed Towards the Sun Opposite to Earth's orbit Perpendicular to the ecliptic plane
GSM - Geocentric Solar Magnetospheric fixed Towards the Sun Projection of the dipole axis in the Y-Z GSE plane
SM - Solar Magnetic fixed In the plane containing the Earth-Sum line and the dipole axis Along the dipole axis
MAG - Geomagnetic rotating Through intersection of magnetic equator and geographic meridian 90 degrees east of the meridian containing the dipole axis Along the dipole axis
GEO - Geographic rotating Through intersection of equator and Greenwich meridian Along Earth's rotation axis

NOTE: By "fixed", I mean that they do not rotate with the Earth's spin, they are not really fixed.

Model Parameters

In this section, the parameters and relevant **kwargs are discussed for each model. If **kwargs aren't used, then the relevant parameters are found autmoatically for the date and time provided when using the models. Individual parameters amy be altered without affecting the others - if only a single parameter is changed, then the others are still automatically calculated. The **kwargs accepted by ModelField and TraceField are:

Keyword Data Type Description
iopt scalar integer iopt=Kp+1 (iopt=7 for Kp>=6)
parmod 10-element float array Elements 0 - 3 are Pdyn, SymH, IMF By and IMF Bz, respectively. Elements 4 - 9 depend on the model
tilt scalar float The dipole tilt angle in radians
Vx scalar float x component of solar wind velocity
Vy scalar float y component of solar wind velocity
Vz scalar float z component of solar wind velocity
Kp scalar integer Kp index
Pdyn scalar float Dynamic pressure in nPa
SymH scalar float SymH in nT
By scalar float IMF y component in nT
Bz scalar float IMF z component in nT

All models can be affected by the Vx, Vy, and Vz parameters as these are used to aberrate the coordinates into the GSW frame, where GSW is equivalent to GSM in the situation where Vy=0 and Vz=0. tilt is calculated automatically for all models based on the date, time and the IGRF magnetic field model.

T89

The only parameter used here is iopt which can be controlled with either setting iopt or Kp keywords to an integer. Valid values for iopt are integers in the range 1-7, if Kp is set, then iopt is set automatically equal to Kp+1. For Kp>=6 iopt=7.

T96

The first four elements of the parmod array are used for this model where parmod[0] is the dynamic pressure, parmod[1] is the SymH, parmod[2] is the y component of the interplanetary magnetic field (IMF) and parmod[3] is the z component of the IMF. All other elements of this array are ignored. The entire parmod array can be set using the parmod keyword, otherwise individual elements can be edited using the Pdyn, SymH, By and Bz keywords, where other unchanged parameters will be calculated automatically.

T01

This model uses the first six elements of the parmod array, where the first four are set in exactly the same way as in the T96 model. parmod[4] and parmod[5] correspond to the G1 and G2 parameters calculated in Tsyganenko, 2002b. These can, I believe, be set to 0.

TS05

This model uses all of the parmod array, where the first four are as in the T96 model. The last 6 elements are the W1-W6 parameters described in Tsyganenko and Sitnov, 2005.

References

  1. N.A. Tsyganenko, A Magnetospheric Magnetic Field Model with a Warped Tail Current Sheet, Planet. Space Sci. 37, 5-20, 1989.
  2. N.A. Tsyganenko, Modeling the Earth's Magnetospheric Magnetic Field Confined Within a Realistic Magnetopause, J.Geophys.Res., 100, 5599-5612, 1995.
  3. N.A. Tsyganenko and D.P. Stern, Modeling the Global Magnetic Field of the Large-Scale Birkeland Current Systems, J. Geophys.Res., 101, 27187-27198, 1996.
  4. N.A. Tsyganenko, A model of the near magnetosphere with a dawn-dusk asymmetry - 1. Mathematical Structure, J. Geophys.Res., 107, A8, 10.1029/2001JA000219, 2002.
  5. N.A. Tsyganenko, A model of the near magnetosphere with a dawn-dusk asymmetry - 2. Parameterization and fitting to observations, J. Geophys.Res., 107, A7, 10.1029/2001JA000220, 2002.
  6. N.A. Tsyganenko and M. I. Sitnov, Modeling the dynamics of the inner magnetosphere during strong geomagnetic storms, J. Geophys.Res., 110, A3, 10.1029/2004JA010798, 2005.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

PyGeopack-0.2.5-py3-none-any.whl (657.6 kB view details)

Uploaded Python 3

File details

Details for the file PyGeopack-0.2.5-py3-none-any.whl.

File metadata

  • Download URL: PyGeopack-0.2.5-py3-none-any.whl
  • Upload date:
  • Size: 657.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.4.2 requests/2.19.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.6.4

File hashes

Hashes for PyGeopack-0.2.5-py3-none-any.whl
Algorithm Hash digest
SHA256 5e7d39869e3f97e08b7e273259234b0d183baf5ebb5bc33234f2b1f185a06faf
MD5 2ec5b714edc0d9804ae39604cac4542e
BLAKE2b-256 494ae6942eb957a1fb01f838bd5e0891fce6c8df3d2c1e34877a32886ccc2347

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page