geoist.magmod package

Subpackages

Submodules

geoist.magmod.dipole_coords module

geoist.magmod.dipole_coords.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.

geoist.magmod.dipole_coords.get_dipole_rotation_matrix(latitude, longitude)[源代码]

Get rotation matrix for given north pole coordinates.

geoist.magmod.dipole_coords.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.

geoist.magmod.magnetic_time module

geoist.magmod.magnetic_time.get_subsol(mjd2000)[源代码]

Calculate sub-solar point coordinates for the given MJD2000 time.

geoist.magmod.magnetic_time.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.

geoist.magmod.sheval_dipole module

geoist.magmod.sheval_dipole.rotate_vectors_from_dipole(vectors, lat_ngp, lon_ngp, coords_dipole, coord_in, coord_type_in=0, coord_type_out=0)[源代码]

Rotate vectors from the Dipole spherical coordinate frame to the requested output coordinate frame.

geoist.magmod.sheval_dipole.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.

参数

  • - array of 3D coordinates (arr_in) --

  • - degree of the spherical harmonic model. (degree) --

  • - vector of spherical harmonic model coefficients. (coef_h) --

  • - vector of spherical harmonic model coefficients. --

  • - North Geomagnetic Pole latitude. (lat_ngp) --

  • - North Geomagnetic Pole longitude. (lon_ngp) --

  • - type of the input coordinates. (coord_type_in) --

  • - quantity to be evaluated (mode) -- POTENTIAL GRADIENT (default) POTENTIAL_AND_GRADIENT

  • - reference (rad_ref) --

  • - boolean flag set to True by default. When set to False (is_internal) -- external field evaluation is used.

  • - scalar value multiplied with the result potentials. (scale_potential) --

  • - scalar or 3 element array multiplied with the result (scale_gradient) -- gradient components.

geoist.magmod.solar_position module

geoist.magmod.solar_position.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]

geoist.magmod.solar_position.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)

geoist.magmod.time_util module

geoist.magmod.time_util.decimal_year_to_mjd2000_simple(decimal_year)[源代码]

Convert (Julian) decimal year to Modified Julian Date since 2000 using the simplified conversion method:

mjd2000 = (decimal_year - 2000.0) * 365.25

geoist.magmod.time_util.mjd2000_to_decimal_year_simple(mjd2000)[源代码]

Convert Modified Julian Date since 2000 to (Julian) decimal year using the simplified conversion method:

decimal_year = 2000.0 + mjd2000/365.25

geoist.magmod.time_util.mjd2000_to_year_fraction_simple(mjd2000)[源代码]

Convert Modified Julian Date since 2000 to (Julian) year fraction using the simplified conversion method:

year_fraction = mjd2000/365.25 - floor(mjd2000/365.25)

geoist.magmod.util module

geoist.magmod.util.datetime_to_decimal_year(time)[源代码]

Convert time given by a datetime.datetime object to a decimal year value.

geoist.magmod.util.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.

geoist.magmod.util.vnorm(arr)[源代码]

Calculate norm for each vector form an input array of vectors: |v| = sqrt(dot(v, v))

geoist.magmod.util.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

Module contents

class geoist.magmod.ComposedGeomagneticModel(*models)[源代码]

基类：geoist.magmod.magnetic_model.model.GeomagneticModel

Composed Earth magnetic field model aggregating multiple models into one.

eval(time, location, input_coordinate_system=1, output_coordinate_system=1, **options)[源代码]

Evaluate magnetic field for the given MJD2000 times and coordinates.

property parameters

required parameters.

push(model, scale=1.0, **parameters)[源代码]

Add model.

property validity

Get model's validity range as a tuple of two MJD2000 times. In case of an unconstrained validity rage (-inf, +inf) tuple is returned.

geoist.magmod.convert()

arr_out = convert(arr_in, coord_type_in=GEODETIC_ABOVE_WGS84, coord_type_out=GEODETIC_ABOVE_WGS84)

Convert coordinates between different coordinate systems.

geoist.magmod.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.

geoist.magmod.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).

geoist.magmod.get_dipole_rotation_matrix(latitude, longitude)[源代码]

Get rotation matrix for given north pole coordinates.

geoist.magmod.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.

geoist.magmod.load_model_emm(path_static, path_secvar)[源代码]

Load model from a EMM coefficient files.

geoist.magmod.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.

geoist.magmod.load_model_shc(path, **kwargs)[源代码]

Load model from an SHC file.

geoist.magmod.load_model_shc_combined(*paths, **kwargs)[源代码]

Load model with coefficients combined from multiple SHC files.

geoist.magmod.load_model_swarm_mio_external(path, above_ionosphere=None)[源代码]

Load external (primary field) model from a Swarm MIO_SHA_2* product.

geoist.magmod.load_model_swarm_mio_internal(path)[源代码]

Load internal (secondary field) model from a Swarm MIO_SHA_2* product.

geoist.magmod.load_model_wmm(path)[源代码]

Load model from a WMM COF file.

geoist.magmod.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.

geoist.magmod.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).

geoist.magmod.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.

geoist.magmod.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).

geoist.magmod.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) .

geoist.magmod.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

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.

geoist.magmod.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.

参数

  • - array of 3D coordinates (arr_in) --

  • - degree of the spherical harmonic model. (degree) --

  • - vector of spherical harmonic model coefficients. (coef_h) --

  • - vector of spherical harmonic model coefficients. --

  • - North Geomagnetic Pole latitude. (lat_ngp) --

  • - North Geomagnetic Pole longitude. (lon_ngp) --

  • - type of the input coordinates. (coord_type_in) --

  • - quantity to be evaluated (mode) -- POTENTIAL GRADIENT (default) POTENTIAL_AND_GRADIENT

  • - reference (rad_ref) --

  • - boolean flag set to True by default. When set to False (is_internal) -- external field evaluation is used.

  • - scalar value multiplied with the result potentials. (scale_potential) --

  • - scalar or 3 element array multiplied with the result (scale_gradient) -- gradient components.

geoist.magmod.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.

geoist.magmod.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.

geoist.magmod.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]

geoist.magmod.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)

geoist.magmod.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.

参数

  • - MJD2000 time used by the field model. (time) --

  • - stating point (point) --

  • - options used by the field line tracing. (trace_options) --

  • - dictionary of model options passed to the model.eval() (model_options) -- method.

geoist.magmod.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.

geoist.magmod.vnorm(arr)[源代码]

Calculate norm for each vector form an input array of vectors: |v| = sqrt(dot(v, v))

geoist.magmod.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.

geoist.magmod.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.

geoist.magmod.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.

geoist.magmod.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.

geoist.magmod.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