API

Core

Primary functions for calculating magnetic basis vectors.

OMMBV._core.calculate_geomagnetic_basis(latitude, longitude, altitude, datetimes, **kwargs)

Calculate local geomagnetic basis vectors and mapping scalars.

Parameters:

• latitude (array-like of floats (degrees) [-90., 90]) – Latitude of location, degrees, WGS84

• longitude (array-like of floats (degrees) [-180., 360.]) – Longitude of location, degrees, WGS84

• altitude (array-like of floats (km)) – Altitude of location, height above surface, WGS84

• datetimes (array-like of datetimes) – Time to calculate vectors

Returns:

zon_x (y,z): zonal unit vector along ECEF X, Y, and Z directions fa_x (y,z): field-aligned unit vector along ECEF X, Y, and Z directions mer_x (y,z): meridional unit vector along ECEF X, Y, and Z directions

d_zon_mag: D zonal vector magnitude d_fa_mag: D field-aligned vector magnitude d_mer_mag: D meridional vector magnitude

d_zon_x (y,z) : D zonal vector components. ECEF X, Y, and Z directions d_mer_x (y,z) : D meridional vector components. ECEF X, Y, and Z. d_fa_x (y,z) : D field aligned vector components. ECEF X, Y, and Z.

e_zon_mag: E zonal vector magnitude e_fa_mag: E field-aligned vector magnitude e_mer_mag: E meridional vector magnitude

e_zon_x (y,z) : E zonal vector components. ECEF X, Y, and Z directions. e_mer_x (y,z) : E meridional vector components. ECEF X, Y, and Z. e_fa_x (y,z) : E field aligned vector components. ECEF X, Y, and Z.

Return type:

dict

Note

Thin wrapper around calculate_mag_drift_unit_vectors_ecef set to default parameters and with more organization of the outputs.

OMMBV._core.calculate_mag_drift_unit_vectors_ecef(latitude, longitude, altitude, datetimes, step_size=0.5, tol=0.0001, tol_zonal_apex=0.0001, max_loops=15, ecef_input=False, centered_diff=True, full_output=False, include_debug=False, scalar=None, edge_steps=None, dstep_size=0.5, max_steps=None, ref_height=None, steps=None, pole_tol=1e-05, location_info=<function apex_location_info>, mag_fcn=None, step_fcn=None, min_loops=3, apex_kwargs=None)

Calculate local geomagnetic basis vectors and mapping scalars.

Zonal - Generally Eastward (+East); surface of constant apex height Field Aligned - Generally Northward (+North); points along geomagnetic field Meridional - Generally Vertical (+Up); gradient in apex height

The apex height is the geodetic height of the field line at its highest point. Unit vectors are expressed in Earth Centered Earth Fixed (ECEF) coordinates.

Parameters:

• latitude (array-like of floats (degrees) [-90., 90]) – Latitude of location, degrees, WGS84

• longitude (array-like of floats (degrees) [-180., 360.]) – Longitude of location, degrees, WGS84

• altitude (array-like of floats (km)) – Altitude of location, height above surface, WGS84

• datetimes (array-like of datetimes) – Time to calculate vectors

• step_size (float) – Step size (km) to use when calculating changes in apex height (default=0.5)

• tol (float) – Tolerance goal for the magnitude of the change in unit vectors per loop (default=1.E-4)

• tol_zonal_apex (float) – Maximum allowed change in apex height along zonal direction (default=1.E-4)

• max_loops (int) – Maximum number of iterations (default=100)

• ecef_input (bool) – If True, inputs latitude, longitude, altitude are interpreted as x, y, and z in ECEF coordinates (km). (default=False)

• full_output (bool) – If True, return an additional dictionary with the E and D mapping vectors. (default=False)

• include_debug (bool) – If True, include stats about iterative process in optional dictionary. Requires full_output=True. (default=False)

• centered_diff (bool) – If True, a symmetric centered difference is used when calculating the change in apex height along the zonal direction, used within the zonal unit vector calculation. (default=True)

• scalar (NoneType) – Deprecated.

• edge_steps (NoneType) – Deprecated.

• dstep_size (float) – Step size (km) used when calculating the expansion of field line surfaces. Generally, this should be the same as step_size. (default=0.5)

• max_steps (NoneType) – Deprecated

• ref_height (NoneType) – Deprecated

• steps (NoneType) – Deprecated

• location_info (function) – Function used to determine a consistent relative position along a field line. Should not generally be modified. (default=apex_location_info)

• pole_tol (float) – When upward component of magnetic is within pole_tol of 1, the system will treat location as a pole and will not attempt to calculate unit vectors and scalars. (default=1.E-5)

• mag_fcn (function) – Function used to get information on local magnetic field. If None, uses default functions for IGRF. (default=None).

• step_fcn (function) – Function used to step along magnetic field. If None, uses default functions for IGRF. (default=None).

• min_loops (int) – Minimum number of iterations to attempt when calculating basis. (default=3)

• apex_kwargs (dict or NoneType) – If dict supplied, passed to apex_location_info as keyword arguments. (default=None)

Returns:

• zon_x, zon_y, zon_z, fa_x, fa_y, fa_z, mer_x, mer_y, mer_z,

• (optional dictionary)

• Optional output dictionary

• ————————–

• Full Output Parameters

• d_zon_x (y,z) (D zonal vector components along ECEF X, Y, and Z directions)

• d_mer_x (y,z) (D meridional vector components along ECEF X, Y, and Z)

• d_fa_x (y,z) (D field aligned vector components along ECEF X, Y, and Z)

• e_zon_x (y,z) (E zonal vector components along ECEF X, Y, and Z directions)

• e_mer_x (y,z) (E meridional vector components along ECEF X, Y, and Z)

• e_fa_x (y,z) (E field aligned vector components along ECEF X, Y, and Z)

Debug Parameters

diff_mer_apex : rate of change in apex height (km) along meridional vector diff_mer_vec : magnitude of vector change for last loop diff_zonal_apex : rate of change in apex height (km) along zonal vector diff_zonal_vec : magnitude of vector change for last loop loops : Number of loops vector_seed_type : Initial vector used for starting calculation (deprecated)

Note

The zonal and meridional vectors are calculated by using the observed apex-height gradient to rotate a pair of vectors orthogonal to eachother and the geomagnetic field such that one points along no change in apex height (zonal), the other along the max (meridional). The rotation angle theta is given by

Tan(theta) = apex_height_diff_zonal/apex_height_diff_meridional

The method terminates when successive updates to both the zonal and meridional unit vectors differ (magnitude of difference) by less than tol, and the change in apex_height from input location is less than tol_zonal_apex.

OMMBV._core.cross_product(x1, y1, z1, x2, y2, z2)

Cross product of two vectors, v1 x v2.

Deprecated since version 1.0.0: Function moved to OMMBV.vector.cross_product, this wrapper will be removed after v1.2.

Parameters:

• x1 (float or array-like) – X component of vector 1

• y1 (float or array-like) – Y component of vector 1

• z1 (float or array-like) – Z component of vector 1

• x2 (float or array-like) – X component of vector 2

• y2 (float or array-like) – Y component of vector 2

• z2 (float or array-like) – Z component of vector 2

Returns:

Unit vector x,y,z components

Return type:

x, y, z

OMMBV._core.ecef_to_enu_vector(x, y, z, glat, glong)

Convert vector from ECEF X,Y,Z components to East, North, Up.

Deprecated since version 1.0.0: Function moved to OMMBV.vector.ecef_to_enu, this wrapper will be removed after v1.2.

Position of vector in geospace may be specified in either geocentric or geodetic coordinates, with corresponding expression of the vector using radial or ellipsoidal unit vectors.

Parameters:

• x (float or array-like) – ECEF-X component of vector

• y (float or array-like) – ECEF-Y component of vector

• z (float or array-like) – ECEF-Z component of vector

• glat (float or array_like) – Geodetic or geocentric latitude (degrees)

• glong (float or array_like) – Geodetic or geocentric longitude (degrees)

Returns:

east, north, up – Vector components along east, north, and up directions

Return type:

np.array

OMMBV._core.ecef_to_geocentric(x, y, z, ref_height=6371.0)

Convert ECEF into geocentric coordinates.

Deprecated since version 1.0.0: Function moved to OMMBV.trans.ecef_to_geocentric, this wrapper will be removed after v1.2.

Parameters:

• x (float or array_like) – ECEF-X in km

• y (float or array_like) – ECEF-Y in km

• z (float or array_like) – ECEF-Z in km

• ref_height (float or array_like) – Reference radius used for calculating height in km. (default=trans.earth_geo_radius)

Returns:

latitude, longitude, altitude – Locations in latitude (degrees), longitude (degrees), and altitude above reference_height in km.

Return type:

np.array

OMMBV._core.ecef_to_geodetic(*args, **kwargs)

Convert ECEF into Geodetic WGS84 coordinates.

Deprecated since version 1.0.0: Function moved to OMMBV.trans.geodetic_to_ecef, this wrapper will be removed after v1.2.

OMMBV._core.enu_to_ecef_vector(east, north, up, glat, glong)

Convert vector from East, North, Up components to ECEF.

Deprecated since version 1.0.0: Function moved to OMMBV.vector.enu_to_ecef, this wrapper will be removed after v1.2.

Position of vector in geospace may be specified in either geocentric or geodetic coordinates, with corresponding expression of the vector using radial or ellipsoidal unit vectors.

Parameters:

• east (float or array-like) – Eastward component of vector

• north (float or array-like) – Northward component of vector

• up (float or array-like) – Upward component of vector

• glat (float or array_like) – Geodetic or geocentric latitude (degrees)

• glong (float or array_like) – Geodetic or geocentric longitude (degrees)

Returns:

x, y, z – Vector components along ECEF x, y, and z directions

Return type:

np.array

OMMBV._core.geocentric_to_ecef(latitude, longitude, altitude)

Convert geocentric coordinates into ECEF.

Deprecated since version 1.0.0: Function moved to OMMBV.trans.geocentric_to_ecef, this wrapper will be removed after v1.2.

Parameters:

• latitude (float or array_like) – Geocentric latitude (degrees)

• longitude (float or array_like) – Geocentric longitude (degrees)

• altitude (float or array_like) – Height (km) above presumed spherical Earth with radius 6371 km.

Returns:

x, y, z – x, y, z ECEF locations in km

Return type:

np.array

OMMBV._core.geodetic_to_ecef(latitude, longitude, altitude)

Convert WGS84 geodetic coordinates into ECEF.

Deprecated since version 1.0.0: Function moved to OMMBV.trans.geodetic_to_ecef, this wrapper will be removed after v1.2.

Parameters:

• latitude (float or array_like) – Geodetic latitude (degrees)

• longitude (float or array_like) – Geodetic longitude (degrees)

• altitude (float or array_like) – Geodetic Height (km) above WGS84 reference ellipsoid.

Returns:

x, y, z – x, y, z ECEF locations in km

Return type:

np.array

OMMBV._core.normalize_vector(x, y, z)

Normalize vector to produce a unit vector.

Deprecated since version 1.0.0: Function moved to OMMBV.vector.normalize, this wrapper will be removed after v1.2.

Parameters:

• x (float or array-like) – X component of vector

• y (float or array-like) – Y component of vector

• z (float or array-like) – Z component of vector

Returns:

Unit vector x,y,z components

Return type:

x, y, z

OMMBV._core.project_ECEF_vector_onto_basis(x, y, z, xx, xy, xz, yx, yy, yz, zx, zy, zz)

Project vector onto different basis.

Deprecated since version 1.0.0: Function moved to OMMBV.vector.project_onto_basis, this wrapper will be removed after v1.2.

Parameters:

• x (float or array-like) – X component of vector

• y (float or array-like) – Y component of vector

• z (float or array-like) – Z component of vector

• xx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• yx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• zx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• xy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• yy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• zy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• xz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

• yz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

• zz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

Returns:

Vector projected onto new basis

Return type:

x, y, z

OMMBV._core.python_ecef_to_geodetic(x, y, z, method='closed')

Convert ECEF into Geodetic WGS84 coordinates using Python code.

Deprecated since version 1.0.0: Function moved to OMMBV.trans.geodetic_to_ecef, this wrapper will be removed after v1.2.

Parameters:

• x (float or array_like) – ECEF-X in km

• y (float or array_like) – ECEF-Y in km

• z (float or array_like) – ECEF-Z in km

• method (str) – Supports ‘iterative’ or ‘closed’ to select method of conversion. ‘closed’ for mathematical solution (page 96 section 2.2.1, http://www.epsg.org/Portals/0/373-07-2.pdf) or ‘iterative’ (http://www.oc.nps.edu/oc2902w/coord/coordcvt.pdf). (default = ‘closed’)

Returns:

latitude, longitude, altitude – Locations in latitude (degrees), longitude (degrees), and altitude above WGS84 (km)

Return type:

np.array

OMMBV._core.scalars_for_mapping_ion_drifts(glats, glons, alts, dates, max_steps=None, e_field_scaling_only=None, edge_length=None, edge_steps=None, **kwargs)

Translate ion drifts and electric fields to equator and footpoints.

Parameters:

• glats (list-like of floats (degrees)) – Geodetic (WGS84) latitude

• glons (list-like of floats (degrees)) – Geodetic (WGS84) longitude

• alts (list-like of floats (km)) – Geodetic (WGS84) altitude, height above surface

• dates (list-like of datetimes) – Date and time for determination of scalars

• e_field_scaling_only (Deprecated)

• max_steps (Deprecated)

• edge_length (Deprecated)

• edge_steps (Deprecated)

• **kwargs (Additional keywords) – Passed to calculate_mag_drift_unit_vectors_ecef. step_fcn, if present, is also passed to footpoint_location_info.

Returns:

array-like of scalars for translating ion drifts. Keys are, ‘north_zonal_drifts_scalar’, ‘north_mer_drifts_scalar’, and similarly for southern locations. ‘equator_mer_drifts_scalar’ and ‘equator_zonal_drifts_scalar’ cover the mappings to the equator.

Return type:

dict

OMMBV._core.step_along_mag_unit_vector(x, y, z, date, direction, num_steps=1, step_size=25.0, scalar=1, **kwargs)

Move by following specified magnetic unit vector direction.

Moving along the field is effectively the same as a field line trace though extended movement along a field should use the specific field_line_trace method.

Parameters:

• x (ECEF-x (km)) – Location to step from in ECEF (km).

• y (ECEF-y (km)) – Location to step from in ECEF (km).

• z (ECEF-z (km)) – Location to step from in ECEF (km).

• date (list-like of datetimes) – Date and time for magnetic field

• direction (str) – String identifier for which unit vector direction to move along. Supported inputs, ‘meridional’, ‘zonal’, ‘aligned’

• num_steps (int) – Number of steps to take along unit vector direction (default=1)

• step_size (float) – Distance taken for each step (km) (default=25.)

• scalar (int) – Scalar modifier for step size distance. Input a -1 to move along negative unit vector direction. (default=1)

• **kwargs (Additional keywords) – Passed to calculate_mag_drift_unit_vectors_ecef.

Returns:

[x, y, z] of ECEF location after taking num_steps along direction, each step_size long.

Return type:

np.array

Note

centered_diff=True is passed along to calculate_mag_drift_unit_vectors_ecef when direction=’meridional’, while centered_diff=False is used for the ‘zonal’ direction. This ensures that when moving along the zonal direction there is a minimal change in apex height.

Heritage

Heritage functions for OMMBV. Will be removed in v2.0.0.

OMMBV.heritage.apex_distance_after_footpoint_step(glats, glons, alts, dates, direction, vector_direction, step_size=100.0, max_steps=1000, steps=None, edge_length=25.0, edge_steps=5, ecef_input=False)

Calculate distance between apex locations after vector_direction step.

Using the input location, the footpoint location is calculated. From here, a step along both the positive and negative vector_direction is taken, and the apex locations for those points are calculated. The difference in position between these apex locations is the total centered distance between magnetic field lines at the magnetic apex when starting from the footpoints with a field line half distance of edge_length.

Parameters:

• glats (list-like of floats) – Geodetic (WGS84) latitude in degrees.

• glons (list-like of floats) – Geodetic (WGS84) longitude in degrees.

• alts (list-like of floats) – Geodetic (WGS84) altitude, height above surface in km.

• dates (list-like of datetimes) – Date and time for determination of scalars.

• direction (str) – ‘north’ or ‘south’ for tracing towards northern (field-aligned) or southern (anti field-aligned) footpoint locations.

• vector_direction (str) – ‘meridional’ or ‘zonal’ magnetic unit vector directions.

• step_size (float) – Step size (km) used for field line integration. (default=100.)

• max_steps (int) – Number of steps taken for field line integration. (default=1000)

• steps (np.array or NoneType) – Integration steps array passed to full_field_line. (default=np.arange(max_steps+1) if steps is None)

• edge_length (float (km)) – Half of total edge length (step) taken at footpoint location. edge_length step in both positive and negative directions. (default=25.)

• edge_steps (int) – Number of steps taken from footpoint towards new field line in a given direction (positive/negative) along unit vector. (default=5)

• ecef_input (bool) – If True, latitude, longitude, and altitude are treated as ECEF positions (km). (default=False)

Returns:

A closed loop field line path through input location and footpoint in northern/southern hemisphere and back is taken. The return edge length through input location is provided.

Return type:

np.array,

OMMBV.heritage.apex_distance_after_local_step(glats, glons, alts, dates, vector_direction, edge_length=25.0, edge_steps=5, ecef_input=False, return_geodetic=False, location_info=<function apex_location_info>)

Calculate the distance between apex locations after local step.

Using the input location, the apex location is calculated. Also from the input location, a step along both the positive and negative vector_direction is taken, and the apex locations for those points are calculated. The difference in position between these apex locations is the total centered distance between magnetic field lines at the magnetic apex when starting locally with a field line half distance of edge_length.

Parameters:

• glats (list-like of floats (degrees)) – Geodetic (WGS84) latitude

• glons (list-like of floats (degrees)) – Geodetic (WGS84) longitude

• alts (list-like of floats (km)) – Geodetic (WGS84) altitude, height above surface

• dates (list-like of datetimes) – Date and time for determination of scalars

• vector_direction (string) – ‘meridional’ or ‘zonal’ unit vector directions

• edge_length (float (km)) – Half of total edge length (step) taken at footpoint location. edge_length step in both positive and negative directions.

• edge_steps (int) – Number of steps taken from footpoint towards new field line in a given direction (positive/negative) along unit vector

Returns:

The change in field line apex locations.

Return type:

np.array

Note

vector direction refers to the magnetic unit vector direction

OMMBV.heritage.apex_edge_lengths_via_footpoint(*args, **kwargs)

Calculate distance between apex locations.

Deprecated since version 1.0.0: Function moved to apex_distance_after_footpoint_step, this wrapper will be removed after v1.2.

OMMBV.heritage.calculate_integrated_mag_drift_unit_vectors_ecef(latitude, longitude, altitude, datetimes, steps=None, max_steps=1000, step_size=100.0, ref_height=120.0, filter_zonal=True)

Calculate field line integrated geomagnetic basis vectors.

Unit vectors are expressed in ECEF coordinates.

Parameters:

• latitude (array-like of floats (degrees)) – Latitude of location, degrees, WGS84

• longitude (array-like of floats (degrees)) – Longitude of location, degrees, WGS84

• altitude (array-like of floats (km)) – Altitude of location, height above surface, WGS84

• datetimes (array-like of datetimes) – Time to calculate vectors

• max_steps (int) – Maximum number of steps allowed for field line tracing

• step_size (float) – Maximum step size (km) allowed when field line tracing

• ref_height (float) – Altitude used as cutoff for labeling a field line location a footpoint

• filter_zonal (bool) – If True, removes any field aligned component from the calculated zonal unit vector. Resulting coordinate system is not-orthogonal.

Return type:

zon_x, zon_y, zon_z, fa_x, fa_y, fa_z, mer_x, mer_y, mer_z

Note

The zonal vector is calculated by field-line tracing from the input locations toward the footpoint locations at ref_height. The cross product of these two vectors is taken to define the plane of the magnetic field. This vector is not always orthogonal with the local field-aligned vector (IGRF), thus any component of the zonal vector with the field-aligned direction is removed (optional). The meridional unit vector is defined via the cross product of the zonal and field-aligned directions.

OMMBV.heritage.heritage_scalars_for_mapping_ion_drifts(glats, glons, alts, dates, step_size=None, max_steps=None, e_field_scaling_only=False, edge_length=25.0, edge_steps=1, **kwargs)

Heritage technique for mapping ion drifts and electric fields.

Deprecated since version 0.6.0: Use OMMBV.scalars_for_mapping_ion_drifts instead. Will be removed after 1.0.0.

Parameters:

• glats (list-like of floats (degrees)) – Geodetic (WGS84) latitude

• glons (list-like of floats (degrees)) – Geodetic (WGS84) longitude

• alts (list-like of floats (km)) – Geodetic (WGS84) altitude, height above surface

• dates (list-like of datetimes) – Date and time for determination of scalars

• e_field_scaling_only (boolean (False)) – If True, method only calculates the electric field scalar, ignoring changes in magnitude of B. Note ion velocity related to E/B.

Returns:

array-like of scalars for translating ion drifts. Keys are, ‘north_zonal_drifts_scalar’, ‘north_mer_drifts_scalar’, and similarly for southern locations. ‘equator_mer_drifts_scalar’ and ‘equator_zonal_drifts_scalar’ cover the mappings to the equator.

Return type:

dict

Note

Directions refer to the ion motion direction e.g. the zonal scalar applies to zonal ion motions (meridional E field assuming ExB ion motion)

Satellite

Provide support for adding OMMBV to NASA Ionospheric Connections Explorer.

OMMBV.satellite.add_footpoint_and_equatorial_drifts(inst, equ_mer_scalar='equ_mer_drifts_scalar', equ_zonal_scalar='equ_zon_drifts_scalar', north_mer_scalar='north_footpoint_mer_drifts_scalar', north_zon_scalar='north_footpoint_zon_drifts_scalar', south_mer_scalar='south_footpoint_mer_drifts_scalar', south_zon_scalar='south_footpoint_zon_drifts_scalar', mer_drift='iv_mer', zon_drift='iv_zon')

Translate ion velocities to those at footpoints and magnetic equator.

Note

Presumes scalar values for mapping ion velocities are already in the inst, labeled by ‘north_footpoint_zon_drifts_scalar’, ‘north_footpoint_mer_drifts_scalar’, ‘equ_mer_drifts_scalar’, ‘equ_zon_drifts_scalar’.

Also presumes that ion motions in the geomagnetic system are present and labeled as ‘iv_mer’ and ‘iv_zon’ for meridional and zonal ion motions.

This naming scheme is used by the other pysat oriented routines in this package.

Parameters:

• inst (pysat.Instrument)

• equ_mer_scalar (str) – Label used to identify equatorial scalar for meridional ion drift. (default=’equ_mer_drifts_scalar’)

• equ_zonal_scalar (str) – Label used to identify equatorial scalar for zonal ion drift. (default=’equ_zon_drifts_scalar’)

• north_mer_scalar (str) – Label used to identify northern footpoint scalar for meridional ion drift. (default=’north_footpoint_mer_drifts_scalar’)

• north_zon_scalar (str) – Label used to identify northern footpoint scalar for zonal ion drift. (default=’north_footpoint_zon_drifts_scalar’)

• south_mer_scalar (str) – Label used to identify northern footpoint scalar for meridional ion drift. (default=’south_footpoint_mer_drifts_scalar’)

• south_zon_scalar (str) – Label used to identify southern footpoint scalar for zonal ion drift. (default=’south_footpoint_zon_drifts_scalar’)

• mer_drift (str) – Label used to identify meridional ion drifts within inst. (default=’iv_mer’)

• zon_drift (str) – Label used to identify zonal ion drifts within inst. (default=’iv_zon’)

Returns:

Modifies pysat.Instrument object in place. Drifts mapped to the magnetic equator are labeled ‘equ_mer_drift’ and ‘equ_zon_drift’. Mappings to the northern and southern footpoints are labeled ‘south_footpoint_mer_drift’ and ‘south_footpoint_zon_drift’. Similarly for the northern hemisphere.

Return type:

None

OMMBV.satellite.add_mag_drift_unit_vectors(inst, lat_label='latitude', long_label='longitude', alt_label='altitude', **kwargs)

Add geomagnetic basis vectors expressed in S/C coordinates.

Internally, routine calls add_mag_drift_unit_vectors_ecef, which requires the orientation of the S/C basis vectors in ECEF using the following naming, ‘sc_*hat_*’ where hat (*=x,y,z) is the S/C basis vector and _ (*=x,y,z) is the ECEF direction.

Parameters:

• inst (pysat.Instrument object) – Instrument object to be modified

• lat_label (str) – Label used within inst to identify latitude information. (default=’latitude’)

• long_label (str) – Label used within inst to identify longitude information. (default=’longitude’)

• alt_label (str) – Label used within inst to identify altitude information. (default=’altitude’)

• **kwargs – Passed along to calculate_mag_drift_unit_vectors_ecef

Returns:

Modifies instrument object in place. Adds ‘unit_zon_*’ where * = x,y,z ‘unit_fa_*’ and ‘unit_mer_*’ for zonal, field aligned, and meridional directions. Note that vector components are expressed in the S/C basis.

Return type:

None

OMMBV.satellite.add_mag_drift_unit_vectors_ecef(inst, lat_label='latitude', long_label='longitude', alt_label='altitude', **kwargs)

Add geomagnetic basis vectors expressed in ECEF coordinates.

Parameters:

• inst (pysat.Instrument) – Instrument object that will get unit vectors

• lat_label (str) – Label used within inst to identify latitude information. (default=’latitude’)

• long_label (str) – Label used within inst to identify longitude information. (default=’longitude’)

• alt_label (str) – Label used within inst to identify altitude information. (default=’altitude’)

• **kwargs – Passed along to calculate_mag_drift_unit_vectors_ecef

Returns:

unit vectors are added to the passed Instrument object with a naming scheme:

’unit_zon_ecef_*’ : unit zonal vector, component along ECEF-(X,Y,Z) ‘unit_fa_ecef_*’ : unit field-aligned vector ‘unit_mer_ecef_*’ : unit meridional vector

Return type:

None

OMMBV.satellite.add_mag_drifts(inst)

Add ion drifts expressed along geomagnetic basis vectors.

Note

Requires ion drifts under labels ‘iv_*’ where * = (x,y,z) along with unit vectors labels ‘unit_zonal_*’, ‘unit_fa_*’, and ‘unit_mer_*’, where the unit vectors are expressed in S/C coordinates. These vectors are calculated by add_mag_drift_unit_vectors.

Parameters:

inst (pysat.Instrument) – Instrument object will be modified to include new ion drift magnitudes

Returns:

Instrument object modified in place

Return type:

None

Trace

Support field-line tracing.

OMMBV.trace.apex_location_info(glats, glons, alts, dates, step_size=100.0, fine_step_size=1e-05, fine_max_steps=5, return_geodetic=False, ecef_input=False, validate_input=False, max_steps=None, **kwargs)

Determine apex location for the field line passing through input point.

Employs a two stage method. A broad step (step_size) field line trace spanning Northern/Southern footpoints is used to find the location with the largest geodetic (WGS84) height. A binary search higher resolution trace is then used to get a better fix on this location. Each loop, the step_size halved. Greatest geodetic height is once again selected once the step_size is below fine_step_size.

Parameters:

• glats (list-like of floats (degrees)) – Geodetic (WGS84) latitude

• glons (list-like of floats (degrees)) – Geodetic (WGS84) longitude

• alts (list-like of floats (km)) – Geodetic (WGS84) altitude, height above surface

• dates (list-like of datetimes) – Date and time for determination of scalars

• step_size (float) – Step size (km) used for tracing coarse field line. (default=100)

• fine_step_size (float) – Fine step size (km) for refining apex location height. (default=1.E-5)

• fine_max_steps (int) – Fine number of steps passed along to full_field_trace. Do not change, generally. (default=5)

• return_geodetic (bool) – If True, also return location in geodetic coordinates

• ecef_input (bool) – If True, glats, glons, and alts are treated as x, y, z (ECEF). (default=False)

• validate_input (bool) – If True, will check input locations to ensure they are above the surface of the Earth. (default=False)

• **kwargs (Additional keywords) – Passed to trace.full_field_line.

Returns:

• (float, float, float, float, float, float) – ECEF X (km), ECEF Y (km), ECEF Z (km),

• if return_geodetic, also includes – Geodetic Latitude (degrees), Geodetic Longitude (degrees), Geodetic Altitude (km)

Warning

The altitude of the input point must be at least 1 km above the Earth. Set validate_input to True to test inputs and set locations that don’t satisfy requirements to np.nan.

Does not work at the geographic pole due to the use of the ecef_to_geodetic transformation.

OMMBV.trace.field_line_trace(init, date, direction, height, steps=None, max_steps=10000.0, step_size=10.0, recursive_loop_count=None, recurse=True, min_check_flag=False, step_fcn=<function _stub_fcn>)

Perform field line tracing using IGRF and scipy.integrate.odeint.

Parameters:

• init (array-like of floats) – Position to begin field line tracing from in ECEF (x,y,z) km

• date (datetime or float) – Date to perform tracing on (year + day/365 + hours/24. + etc.) Accounts for leap year if datetime provided.

• direction (int) – 1 : field aligned, generally south to north. -1 : anti-field aligned, generally north to south.

• height (float) – Altitude to terminate trace, geodetic WGS84 (km)

• steps (array-like of ints, floats, or NoneType) – Number of steps along field line when field line trace positions should be reported. By default, each step is reported; steps=np.arange(max_steps). (default=None)

• max_steps (float) – Maximum number of steps along field line that should be taken (default=1E4)

• step_size (float) – Distance in km for each large integration step. Multiple substeps are taken as determined by scipy.integrate.odeint. (default=10.)

• recursive_loop_count (int) – Used internally by the method. Not intended for the user.

• recurse (bool) – If True, method will recursively call itself to complete field line trace as necessary. (default=True)

• min_check_flag (bool) – If True, performs an additional check that the field line tracing reached the target altitude. Removes any redundant steps below the target altitude. (default=False)

• step_fcn (function) – Function used by scipy.integrate.odeint to step along the magnetic field. (default=`OMMBV.sources.igrf_step`)

Returns:

2D array. [0,:] has the x,y,z location for initial point [:,0] is the x positions over the integration. Positions are reported in ECEF (km).

Return type:

numpy array

Note

After 500 recursive iterations this method will increase the step size by 3% every subsequent iteration. Fails at 900 iterations.

OMMBV.trace.footpoint_location_info(glats, glons, alts, dates, step_size=100.0, num_steps=1000, return_geodetic=False, ecef_input=False, height=120.0, **kwargs)

Return ECEF location of footpoints in Northern/Southern hemisphere.

Parameters:

• glats (list-like of floats (degrees)) – Geodetic (WGS84) latitude

• glons (list-like of floats (degrees)) – Geodetic (WGS84) longitude

• alts (list-like of floats (km)) – Geodetic (WGS84) altitude, height above surface

• dates (list-like of datetimes) – Date and time for determination of scalars

• step_size (float (100. km)) – Step size (km) used for tracing coarse field line

• num_steps (int (1.E-5 km)) – Number of steps passed along to field_line_trace as max_steps.

• return_geodetic (bool) – If True, footpoint locations returned as lat, long, alt.

• ecef_input (bool) – If True, glats, glons, and alts are treated as x, y, z (ECEF).

• height (float) – Geodetic altitude in km to consider footpoint. (default=120.)

• **kwargs (Additional keywords) – Passed to trace.field_line_trace.

Returns:

Northern and Southern ECEF X,Y,Z locations

Return type:

array(len(glats), 3), array(len(glats), 3)

OMMBV.trace.full_field_line(init, date, height, step_size=100.0, max_steps=1000, steps=None, **kwargs)

Perform field line tracing using IGRF and scipy.integrate.odeint.

Parameters:

• init (array-like of floats) – Position to begin field line tracing from in ECEF (x,y,z) km

• date (datetime or float) – Date to perform tracing on (year + day/365 + hours/24. + etc.) Accounts for leap year if datetime provided.

• height (float) – Altitude to terminate trace, geodetic WGS84 (km)

• max_steps (float) – Maximum number of steps along each direction that should be taken

• step_size (float) – Distance in km for each large integration step. Multiple substeps are taken as determined by scipy.integrate.odeint.

• steps (array-like of ints or floats) –

  Number of steps along field line when field line trace positions should be reported. By default, each step is reported, plus origin;

  steps=np.arange(max_steps+1).

  Two traces are made, one north, the other south, thus the output array could have double max_steps, or more via recursion.

• **kwargs (Additional keywords) – Passed to trace.field_line_trace.

Returns:

2D array. [0,:] has the x,y,z location for southern footpoint [:,0] is the x positions over the integration. Positions are reported in ECEF (km).

Return type:

numpy array

OMMBV.trace.magnetic_vector(x, y, z, dates, normalize=False, mag_fcn=<function _stub_fcn>)

Use IGRF to calculate geomagnetic field.

Parameters:

• x (array-like of floats) – Position in ECEF (km), X

• y (array-like of floats) – Position in ECEF (km), Y

• z (array-like of floats) – Position in ECEF (km), Z

• dates (array-like of datetimes) – Datetimes to calculate magnetic field

• normalize (bool) – If True, return unit vector. (default=False)

• mag_fcn (function) – Function that returns magnetic field from a model. The call signature must match that of igrf.igrf14syn. (default=OMMBV.igrf.igrf14syn)

Returns:

Magnetic field along ECEF directions

Return type:

array, array, array

OMMBV.trace.ommbv_mag_fcn()

Magnetic field/step function stub.

OMMBV.trace.ommbv_step_fcn()

Magnetic field/step function stub.

Trans

Supporting routines for coordinate transformations used by OMMBV.

OMMBV.trans.configure_geocentric_earth(test_mode=True)

Engage test configuration where Earth treated as geocentric.

Parameters:

test_mode (bool) – If True, test mode will be engaged and geodetic calls are replaced with geocentric calls. If False, the original functions are restored. Test mode persists until disabled.

OMMBV.trans.ecef_to_geocentric(x, y, z, ref_height=6371.0)

Convert ECEF into geocentric coordinates.

Parameters:

• x (float or array_like) – ECEF-X in km

• y (float or array_like) – ECEF-Y in km

• z (float or array_like) – ECEF-Z in km

• ref_height (float or array_like) – Reference radius used for calculating height in km. (default=earth_geo_radius)

Returns:

latitude, longitude, altitude – Locations in latitude (degrees), longitude (degrees), and altitude above reference_height in km.

Return type:

np.array

OMMBV.trans.geocentric_to_ecef(latitude, longitude, altitude)

Convert geocentric coordinates into ECEF.

Parameters:

• latitude (float or array_like) – Geocentric latitude (degrees)

• longitude (float or array_like) – Geocentric longitude (degrees)

• altitude (float or array_like) – Height (km) above presumed spherical Earth with radius 6371 km.

Returns:

x, y, z – x, y, z ECEF locations in km

Return type:

np.array

OMMBV.trans.geodetic_to_ecef(latitude, longitude, altitude)

Convert WGS84 geodetic coordinates into ECEF.

Parameters:

• latitude (float or array_like) – Geodetic latitude (degrees)

• longitude (float or array_like) – Geodetic longitude (degrees)

• altitude (float or array_like) – Geodetic Height (km) above WGS84 reference ellipsoid.

Returns:

x, y, z – x, y, z ECEF locations in km

Return type:

np.array

OMMBV.trans.python_ecef_to_geodetic(x, y, z, method='closed')

Convert ECEF into Geodetic WGS84 coordinates using Python code.

Parameters:

• x (float or array_like) – ECEF-X in km

• y (float or array_like) – ECEF-Y in km

• z (float or array_like) – ECEF-Z in km

• method (str) – Supports ‘iterative’ or ‘closed’ to select method of conversion. ‘closed’ for mathematical solution (page 96 section 2.2.1, http://www.epsg.org/Portals/0/373-07-2.pdf) or ‘iterative’ (http://www.oc.nps.edu/oc2902w/coord/coordcvt.pdf). (default = ‘closed’)

Returns:

latitude, longitude, altitude – Locations in latitude (degrees), longitude (degrees), and altitude above WGS84 (km)

Return type:

np.array

Utils

General utilities needed to support OMMBV.

OMMBV.utils.datetimes_to_doubles(dates)

Convert input datetimes to normalized double for IGRF.

Parameters:

dates (list-like of dt.datetimes)

Returns:

ddates – Dates cast as year.fractional_year

Return type:

np.array, dtype=np.float64

Vector

Supporting routines for vector operations used within OMMBV.

OMMBV.vector.cross_product(x1, y1, z1, x2, y2, z2)

Cross product of two vectors, v1 x v2.

Parameters:

• x1 (float or array-like) – X component of vector 1

• y1 (float or array-like) – Y component of vector 1

• z1 (float or array-like) – Z component of vector 1

• x2 (float or array-like) – X component of vector 2

• y2 (float or array-like) – Y component of vector 2

• z2 (float or array-like) – Z component of vector 2

Returns:

Unit vector x,y,z components

Return type:

x, y, z

OMMBV.vector.ecef_to_enu(x, y, z, glat, glong)

Convert vector from ECEF X,Y,Z components to East, North, Up.

Position of vector in geospace may be specified in either geocentric or geodetic coordinates, with corresponding expression of the vector using radial or ellipsoidal unit vectors.

Parameters:

• x (float or array-like) – ECEF-X component of vector

• y (float or array-like) – ECEF-Y component of vector

• z (float or array-like) – ECEF-Z component of vector

• glat (float or array_like) – Geodetic or geocentric latitude (degrees)

• glong (float or array_like) – Geodetic or geocentric longitude (degrees)

Returns:

east, north, up – Vector components along east, north, and up directions

Return type:

np.array

OMMBV.vector.enu_to_ecef(east, north, up, glat, glong)

Convert vector from East, North, Up components to ECEF.

Position of vector in geospace may be specified in either geocentric or geodetic coordinates, with corresponding expression of the vector using radial or ellipsoidal unit vectors.

Parameters:

• east (float or array-like) – Eastward component of vector

• north (float or array-like) – Northward component of vector

• up (float or array-like) – Upward component of vector

• glat (float or array_like) – Geodetic or geocentric latitude (degrees)

• glong (float or array_like) – Geodetic or geocentric longitude (degrees)

Returns:

x, y, z – Vector components along ECEF x, y, and z directions

Return type:

np.array

OMMBV.vector.normalize(x, y, z)

Normalize vector to produce a unit vector.

Parameters:

• x (float or array-like) – X component of vector

• y (float or array-like) – Y component of vector

• z (float or array-like) – Z component of vector

Returns:

Unit vector x,y,z components

Return type:

x, y, z

OMMBV.vector.project_onto_basis(x, y, z, xx, xy, xz, yx, yy, yz, zx, zy, zz)

Project vector onto different basis.

Parameters:

• x (float or array-like) – X component of vector

• y (float or array-like) – Y component of vector

• z (float or array-like) – Z component of vector

• xx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• yx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• zx (float or array-like) – X component of the x, y, z unit vector of new basis in original basis

• xy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• yy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• zy (float or array-like) – Y component of the x, y, z unit vector of new basis in original basis

• xz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

• yz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

• zz (float or array-like) – Z component of the x, y, z unit vector of new basis in original basis

Returns:

Vector projected onto new basis

Return type:

x, y, z