spherical_geometry

This module implements various algorithms from spherical geometry which are useful in geospace or spacecraft data analysis.

For example, one algorithm implemented here can be used to integrate values sampled on a regular latitude/longitude grid at a single altitude, which is a common format of geospace model output.

API

geospacepy.spherical_geometry.angle_difference(ang1, ang2, aziunit)[source]

Difference between two angles in degrees or hours (ang2-ang1), taking into account wrapping

Parameters:
  • ang1 (float or np.ndarray) – Angle(s) to subtract
  • ang2 (float or np.ndarray) – Angle(s) to subtract from
  • degorhour (str, optional) – ‘deg’ for input angles and result in degrees ‘hour’ for input angles in hours
Returns:

diff – Difference (ang2-ang1)
Return type:

float or np.ndarray
geospacepy.spherical_geometry.angle_midpoint(ang1, ang2, aziunit)[source]

Midpoint between two angles in degrees or hours

geospacepy.spherical_geometry.great_circle_distance(lat1, azi1, lat2, azi2, aziunit, algorithm='lawofcosines')[source]

Computes great circle distance between any number of paired locations

Parameters:
  • lat1 (float or np.ndarray) – Latitude(s) of first location(s)
  • azi1 (float or np.ndarray) – Azimuth(s) (longitude,localtime) of first location(s) in pair(s)
  • theta2 (float or np.ndarray) – Latitude(s) of second location(s)
  • azi2 (float or np.ndarray) – Azimuth(s) (longitude,localtime) of second location(s) in pair(s)
  • aziunit (str) – Unit of passed azimuth(s), valid values: hour, deg or rad
  • algorithm (str,optional) – Which formula to use in computing the great circle distance. Valid values are ‘lawofcosines’ or ‘haversine’.
Returns:

dist – Distance (in aziunit) between location(s) 1 and 2
Return type:

float or np.ndarray
geospacepy.spherical_geometry.great_circle_rectangle_area(lats_bottom, lats_top, azis_left, azis_right, r, aziunit)[source]

Calculate the surface area of any number of ‘great-circle rectangles’ (spherical quadrilaterals, whose 4 sides are all great circle arcs) on the surface of a sphere of radius r.

Parameters:
  • - float or np.ndarray (r) – Latitude(s) specifying the bottom arc of the great-circle rectangle(s)
  • - float or np.ndarray – Latitude(s) specifying the top arc of the great-circle rectangle(s)
  • - float or np.ndarray – Azimuth/Longitude(s) specifying the left side arc of the great-circle rectangle(s)
  • - float or np.ndarray – Azimuth/Longitude(s) specifying the right side arc of the great-circle rectangle(s)
  • - float or np.ndarray – Radius of the sphere on which to calculate the area
  • - str (aziunit) – Units of the azimuth/longitude (‘deg’ for degrees, ‘hour’ for hours, ‘rad’ for radians)
Returns:

Surface areas of the great circle rectangles
Return type:

areas - float or np.ndarray
geospacepy.spherical_geometry.grid_surface_integral(grid_lats, grid_azis, grid_values, sphere_radius, aziunit)[source]

Calculate the approximate surface integral of a field of values specified on a grid of m latitudes and n longitudes

Parameters:
  • - np.ndarray, shape=(m,n) (grid_values) – The latitude values of the grid points. Latitudes must change along dimension 0, and stay constant along dimension 1
  • - np.ndarray, shape=(m,n) – The azimuth/longitude values of the grid points. Longitudes must change along dimension 1, and stay constant along dimension 0
  • - np.ndarray, shape=(m,n) – The values of the field be integrated at the grid points
  • - float (sphere_radius) – The radius of the sphere on which the surface integral will be computed
  • - str (aziunit) – The unit of the azimuthal angles (‘deg’ for longitude, ‘hour’ for localtimes)
Returns:

The result of the surface integral, units: units of grid_values * units of sphere_radius ** 2
Return type:

integrated_values - float