Help on package eoxmagmod:
NAME
eoxmagmod
DESCRIPTION
#-------------------------------------------------------------------------------
#
# EOX Magnetic Model Library
#
# Author: Martin Paces <martin.paces@eox.at>
#
#-------------------------------------------------------------------------------
# Copyright (C) 2014 EOX IT Services GmbH
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all
# copies of this Software or works derived from this Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#-------------------------------------------------------------------------------
PACKAGE CONTENTS
_pymm
_pyqd
_pysunpos
_pytimeconv
data (package)
dipole_coords
magnetic_model (package)
magnetic_time
quasi_dipole_coordinates
sheval_dipole
solar_position
tests (package)
util
FUNCTIONS
convert(...)
arr_out = convert(arr_in, coord_type_in=GEODETIC_ABOVE_WGS84, coord_type_out=GEODETIC_ABOVE_WGS84)
Convert coordinates between different coordinate systems.
convert_to_dipole(coords, lat_ngp, lon_ngp, coord_type_in=1)
Convert coordinates (by default geocentric spherical)
to dipole coordinates defined by the given latitude and longitude
of the geomagnetic pole.
The dipole coordinates are a simple rotated coordinate frame in which
the North pole (dipole latitude == 0) is aligned with the geomagnetic pole
and the prime meridian (dipole longitude == 0) is the meridian
passing trough the geomagnetic pole.
decimal_year_to_mjd2000(...)
time_mjd2k = decimal_year_to_mjd2000(decimal_year)
Output:
time_mjd2k - array of the calculated MJD2000 times.
Parameters:
decimal_year - array of decimal years (up to 15 dimensions).
eval_mlt(qdlon, time, fname='/usr/local/conda/lib/python3.7/site-packages/eoxmagmod/data/apexsh_1980-2020.txt')
Evaluate magnetic local time for given quasi dipole longitudes.
Inputs:
qdlon - quasi-dipole longitudes(s).
time - MJD2000 time(s)
fname - file-name of the model text file.
Outputs:
mlt - magnetic local time(s).
eval_qdlatlon(gclat, gclon, gcrad, time, fname='/usr/local/conda/lib/python3.7/site-packages/eoxmagmod/data/apexsh_1980-2020.txt')
Evaluate magnetic quasi-dipole coordinates a single or multiple input
points.
Inputs:
gclat - geocentric latitude(s).
gclon - geocentric longitude(s).
gcrad - geocentric radial coordinate(s) in km.
time - decimal year time(s)
fname - file-name of the model text file.
Outputs:
qdlat - quasi-dipole latitude(s).
qdlon - quasi-dipole longitude(s).
eval_qdlatlon_with_base_vectors(gclat, gclon, gcrad, time, fname='/usr/local/conda/lib/python3.7/site-packages/eoxmagmod/data/apexsh_1980-2020.txt')
Evaluate magnetic quasi-dipole coordinates a single or multiple input
coordinates.
Inputs:
gclat - geocentric latitude(s).
gclon - geocentric longitude(s).
gcrad - geocentric radial coordinate(s) in km.
time - decimal year time(s)
fname - file-name of the model text file.
Outputs:
qdlat - quasi-dipole latitude(s).
qdlon - quasi-dipole longitude(s).
f11 - base vector F1 component 1
f12 - base vector F1 component 2
f21 - base vector F2 component 1
f22 - base vector F2 component 2
f - | F1 x F2 | value
eval_subsol(time)
Evaluate sub-solar point coordinates.
Inputs:
time - MJD2000 time(s)
Outputs:
gdlat - sub-solar point latitude(s).
gdlon - sub-solar point longitude(s).
get_dipole_rotation_matrix(latitude, longitude)
Get rotation matrix for given north pole coordinates.
legendre(...)
p, dp = legendre(latitude, degree)
For given the 'latitude' in degrees and the model's 'degree' evaluate
the Schmidt semi-normalised associated Legendre functions and its
and its derivatives:
P_n^m(sin(latitude)) and dP_n^m(sin(latitude))
where n = 0..degree and m = 0..n
The input parameters are:
latitude - spherical latitude in degrees.
degree - degree of the spherical harmonic model.
load_model_emm(path_static, path_secvar)
Load model from a EMM coefficient files.
load_model_igrf(path)
Load model from an IGRF coefficient file.
Note: IGRF file format was discontinued after IGRF11. Starting by IGRF12
the IRFF models uses SHC format which is loaded by the SHC file loader.
load_model_shc(path)
Load model from an SHC file.
load_model_shc_combined(*paths)
Load model with coefficients combined from multiple SHC files.
load_model_swarm_mio_external(path, above_ionosphere=None)
Load external (primary field) model from a Swarm MIO_SHA_2* product.
load_model_swarm_mio_internal(path)
Load internal (secondary field) model from a Swarm MIO_SHA_2* product.
load_model_swarm_mma_2c_external(path, lat_ngp=80.08, lon_ngp=-72.22000000000003)
Load external (primary field) model from a Swarm MMA_SHA_2C product.
load_model_swarm_mma_2c_internal(path, lat_ngp=80.08, lon_ngp=-72.22000000000003)
Load internal (secondary field) model from a Swarm MMA_SHA_2C product.
load_model_swarm_mma_2f_geo_external(path)
Load geographic frame internal (primary field) model from a Swarm
MMA_SHA_2F product.
load_model_swarm_mma_2f_geo_internal(path)
Load geographic frame internal (secondary field) model from a Swarm
MMA_SHA_2F product.
load_model_swarm_mma_2f_sm_external(path)
Load solar magnetic frame internal (primary field) model from a Swarm
MMA_SHA_2F product.
load_model_swarm_mma_2f_sm_internal(path)
Load solar magnetic frame internal (secondary field) model from a Swarm
MMA_SHA_2F product.
load_model_wmm(path)
Load model from a WMM COF file.
lonsincos(...)
lonsin, loncos = lonsincos(longitude, degree, fast_alg=True)
For given 'longitude' (geocentric spherical) and 'degree', evaluate
the following sine and cosine series:
cos(i*longitude) for i in range(0, degree+1)
sin(i*longitude) for i in range(0, degree+1)
The longitude has to be entered in dg..
The 'fast_alg' boolean options forces the subroutine to use a faster
but slightly less precise evaluation algorithm.
mjd2000_to_decimal_year(...)
decimal_year = mjd2000_to_decimal_year(time_mjd2k)
Output:
decimal_year - array of the calculated decimal years.
Parameters:
time_mjd2k - array of MJD2000 times (up to 15 dimensions).
mjd2000_to_magnetic_universal_time(mjd2000, lat_ngp, lon_ngp, lat_sol=None, lon_sol=None)
Evaluate magnetic universal time for the given MJD2000 and
coordinates of the North Geomagnetic Pole.
The magnetic universal time is geometrically equivalent
to the magnetic dipole longitude of the sub-solar point.
Function allows specification of user defined sub-solar
latitude and longitude lat_sol and lon_sol in degrees
overriding the default Sun model.
mjd2000_to_year_fraction(...)
year_fraction = mjd2000_to_year_fraction(time_mjd2k)
Output:
year_fraction - fraction of the year since the latest *-01-01T00:00Z
Parameters:
time_mjd2k - array of MJD2000 times (up to 15 dimensions).
relradpow(...)
rrp = relradpow(radius, degree, reference_radius=6371.2, is_internal=True)
By default when the 'is_internal' flag is set to True, evaluate
for the given 'radius' and 'reference_radius' relative radius power
series:
(reference_radius/radius)**(i+2) for i in range(0, degree+1) .
When the 'is_internal' flag is set to False, evaluate
for the given 'radius' and 'reference_radius' relative radius power
series:
(radius/reference_radius)**(i+1) for i in range(0, degree+1) .
sheval(...)
arr_out = sheval(arr_in, degree, coef_g, coef_h, coord_type_in=GEODETIC_ABOVE_WGS84,
coord_type_out=GEODETIC_ABOVE_WGS84, mode=GRADIENT, is_internal=True,
scale_potential=1.0, scale_gradient=1.0)
Parameters:
arr_in - array of 3D coordinates (up to 16 dimensions).
degree - degree of the spherical harmonic model.
coef_g - vector of spherical harmonic model coefficients.
coef_h - vector of spherical harmonic model coefficients.
coord_type_in - type of the input coordinates.
mode - quantity to be evaluated:
POTENTIAL
GRADIENT (default)
POTENTIAL_AND_GRADIENT
rad_ref - reference (Earth) radius
is_internal - boolean flag set to True by default. When set to False
external field evaluation is used.
scale_potential - scalar value multiplied with the result potentials.
scale_gradient - scalar or 3 element array multiplied with the result
gradient components.
sheval_dipole(arr_in, degree, coef_g, coef_h, lat_ngp, lon_ngp, coord_type_in=0, coord_type_out=0, mode=2, is_internal=True, scale_potential=1.0, scale_gradient=1.0)
Evaluate spherical harmonic model in the dipole coordinate frame given
by the provided North Geomagnetic Pole coordinates.
Parameters:
arr_in - array of 3D coordinates (up to 16 dimensions).
degree - degree of the spherical harmonic model.
coef_g - vector of spherical harmonic model coefficients.
coef_h - vector of spherical harmonic model coefficients.
lat_ngp - North Geomagnetic Pole latitude.
lon_ngp - North Geomagnetic Pole longitude.
coord_type_in - type of the input coordinates.
mode - quantity to be evaluated:
POTENTIAL
GRADIENT (default)
POTENTIAL_AND_GRADIENT
rad_ref - reference (Earth) radius
is_internal - boolean flag set to True by default. When set to False
external field evaluation is used.
scale_potential - scalar value multiplied with the result potentials.
scale_gradient - scalar or 3 element array multiplied with the result
gradient components.
sphargrd(...)
v_grad = sphargrd(latitude, degree, coef_g, coef_h, leg_p, leg_dp, rrp, lonsin, loncos, is_internal=True)
Spherical harmonic evaluation of the gradient of the potential
(scalar) field in the geocentric spherical coordinates (latitude,
longitude, radius).
The input parameters are:
latitude - spherical (or geodetic) latitude in degrees at the evaluated
location.
degree - degree of the spherical harmonic model.
coef_g - vector of spherical harmonic model coefficients.
coef_h - vector of spherical harmonic model coefficients.
leg_p - vector the Legendre polynomials.
leg_dp - vector the Legendre polynomials' derivations.
rrp - vector the relative radius powers.
lonsin - vector of the longitude cosines.
lonsin - vector of the longitude sines.
is_internal - boolean flag set to True by default. When set to False
external field evaluation is used.
spharpot(...)
v_grad = spharpot(radius, degree, coef_g, coef_h, leg_p, rrp, lonsin, loncos)
Spherical harmonic evaluation of the value of the potential
(scalar) field in the (geocentric) spherical coordinates (latitude,
longitude, radius).
The input parameters are:
radius - radius, i.e., distance from the earth centre, at the
evaluated location.
degree - degree of the spherical harmonic model.
coef_g - vector of spherical harmonic model coefficients.
coef_h - vector of spherical harmonic model coefficients.
leg_p - vector the Legendre polynomials.
rrp - vector the relative radius powers.
lonsin - vector of the longitude cosines.
lonsin - vector of the longitude sines.
sunpos(time_mjd2k, lat, lon, rad=6371.2, dtt=0)
Calculate solar equatorial and horizontal coordinates
for given MJD2000 times and geocentric coordinates (lat, lon, rad).
Outputs: arrays of the Sun equatorial and horizontal coordinates:
declination
right ascension
local hour angle (global hour angle for 0, 0 latitude and longitude)
local azimuth
local zenith
Parameters:
time_mjd2k - array of MJD2000 times (up to 15 dimensions).
lat - array of latitudes [deg]
lon - array of longitudes [deg]
rad - array of radii [km] (set to 0 to disable the parallax correction)
dtt - array of offsets to TT [sec]
sunpos_original(time_mjd2k, lat, lon, rad=6371.2, dtt=0, pres=1.0, temp=20.0)
Calculate solar equatorial and horizontal coordinates
for given MJD2000 times and geocentric coordinates (lat, lon, rad).
This is the original implementation.
Outputs: arrays of the Sun equatorial and horizontal coordinates:
declination
right ascension
local hour angle (global hour angle for 0, 0 latitude and longitude)
local azimuth
local zenith
Parameters:
time_mjd2k - array of MJD2000 times (up to 15 dimensions).
lat - array of latitudes [deg]
lon - array of longitudes [deg]
rad - array of radii [km] (set to 0 to disable the parallax correction)
dtt - array of offsets to TT [sec]
pres - array of offsets of pressures [atm] (refraction correction)
temp - array of offsets to temperatures [dgC] (refraction coorection)
trace_field_line(model, time, point, input_coordinate_system=1, output_coordinate_system=1, trace_options=None, model_options=None)
Trace field line passing trough the given point.
Output:
coords - array of field line Cartesian coordinates.
field - array of field vectors in the requested in the Cartesian
coordinate frame.
Parameters:
time - MJD2000 time used by the field model.
point - stating point (x, y, z) in kilometres.
trace_options - options used by the field line tracing.
model_options - dictionary of model options passed to the model.eval()
method.
vincdecnorm(arr)
Convenience function converting magnetic field vector in the local
northing, easting, elevation (up-pointing) geodetic frame to inclination
in degrees (from -90 to 90, positive values point down), declination
in degrees (from -180 to 180, 0 points north, clockwise), and vector
intensity (vector norm).
This conversion is equivalent to convert of a Cartesian vector to
spherical coordinates.
The function accepts either one vector or an array of vectors and returns
a tuple of the inclination, declination and norm.
vnorm(arr)
Calculate norm for each vector form an input array of vectors:
|v| = sqrt(dot(v, v))
vrot_cart2sph(...)
arr_out = vrot_cart2sph(arr_in, arr_lat, arr_lon)
Rotate vectors from the Cartesian (XYZ) to
the spherical (NEC) coordinate frame for the given latitude
and longitude in degrees.
The inputs are:
arr_in - array of the input vectors
arr_lat - array of latitudes.
arr_lon - array of longitudes.
Scalar lat/lon values are also accepted for a single vector rotation.
vrot_from_dipole(vectors, lat_ngp, lon_ngp, lat_dipole, lon_dipole, lat_out=None, lon_out=None, coord_type_out=2)
Rotate vectors from dipole (NEC) coordinate frame to the
Cartesian (XYZ) (default), geocentric spherical or geodetic (NEC)
coordinate frame.
vrot_sph2cart(...)
arr_out = vrot_sph2cart(arr_in, arr_lat, arr_lon)
Rotate vectors from the spherical (NEC) to
the Cartesian (XYZ) coordinate frame for the given latitude
and longitude in degrees.
The inputs are:
arr_in - array of the input vectors
arr_lat - array of latitudes.
arr_lon - array of longitudes.
Scalar lat/lon values are also accepted for a single vector rotation.
vrot_sph2geod(...)
arr_out = vrot_sph2geod(arr_in, arr_dlat)
Rotate vectors from the geocentric spherical (NEC) to the geodetic
(NEC) coordinate frame for a given difference of latitudes
in degrees.
This function can be also used for the inverse rotation from the geodetic
(NEC) to the geocentric spherical (NEC) coordinate frame by setting
the negative difference of latitudes.
The inputs are:
arr_in - array of the input vectors
arr_dlat - array of differences of the latitudes.
A scalar value is also accepted for a single vector rotation.
vrotate(arr, coord_in, coord_out, coord_type_in, coord_type_out)
Rotate vectors from one coordinate system to another.
Input:
arr - array of the source vectors
coord_in - source coordinates
coord_out - destination coordinates
coord_type_in - source coordinate system type
coord_type_out - destination coordinate system type
Output:
arr_out - array of the rotated vectors
DATA
GEOCENTRIC_CARTESIAN = 2
GEOCENTRIC_SPHERICAL = 1
GEODETIC_ABOVE_WGS84 = 0
GRADIENT = 2
POTENTIAL = 1
POTENTIAL_AND_GRADIENT = 3
__all__ = ['vnorm', 'vincdecnorm', 'vrotate', 'vrot_sph2geod', 'vrot_s...
__copyright__ = 'Copyright (C) 2014 EOX IT Services GmbH'
__licence__ = 'EOX licence (MIT style)'
VERSION
0.8.0
AUTHOR
Martin Paces (martin.paces@eox.at)
FILE
/usr/local/conda/lib/python3.7/site-packages/eoxmagmod/__init__.py