API reference

solarmach.get_sw_speed(body, dtime, trange=1, default_vsw=400.0)

Obtains measured solar wind bulk speed. Downloads solar wind speed measurements for “body” from “trange” hours before “dtime” until “trange” hours after “dtime”, then calculates 1-hour mean values, and finally returns that 1-hour mean measurements that is closest to “dtime”.

Parameters:

body (str) – Name of body, e.g., planet or spacecraft
dtime (datetime object or datetime-compatible str) – Date and time of measurement
trange (int of float) – Timedelta for which measurements are obtainted before and after “dtime”, i.e. dtime +- trange (in hours). Default value 1.
default_vsw (float) – Default solar wind bulk speed in km/s that is returned if no measurements can be obtained. Default value 400.0

Returns:

solar wind bulk speed in km/s

Return type:

float

solarmach.print_body_list(): Prints a selection of body keys and the corresponding body names which may be provided to the SolarMACH class. Visit https://ssd.jpl.nasa.gov/horizons/app.html for a complete list of available bodies.

solarmach.sc_distance(sc1, sc2, dtime)

Obtain absolute distance between two bodies in 3d for a given datetime.

Parameters:

sc1 (str) – Name of body 1, e.g., planet or spacecraft
sc2 (str) – Name of body 2, e.g., planet or spacecraft
dtime (datetime object or datetime-compatible str) – Date (and time) of distance determination

Returns:

Absolute distance between body 1 and 2 in AU.

Return type:

astropy units

class solarmach.SolarMACH(date, body_list, vsw_list=[], reference_long=None, reference_lat=None, coord_sys='Carrington', default_vsw=400.0, **kwargs)

Class handling selected bodies

Parameters:

date (string, datetime.datetime, datetime.date, numpy.datetime64, pandas.Timestamp, tuple) – date (and optional time) of interest in a format understood by https://docs.sunpy.org/en/stable/how_to/parse_time.html
body_list (list) – list of body keys to be used. Keys can be string of int.
vsw_list (list, optional) – list of solar wind bulk speeds in km/s at the position of the different bodies. Must have the same length as body_list. If empty list, obtaining actual measurements is tried. If this is not successful, a default value defined by default_vsw is used.
default_vsw (int or float, optional) – Solar wind bulk speed in km/s to be used if vsw_list is not defined and no vsw measurements could be obtained. By default 400.0.
coord_sys (string, optional) – Defines the coordinate system used: ‘Carrington’ (default) or ‘Stonyhurst’
reference_long (float, optional) – Longitute of reference position at the Sun
reference_lat (float, optional) – Latitude of referene position at the Sun

backmapping(body_pos, reference_long, target_solar_radius=1, vsw=400)

Determine the longitudinal separation angle of a given body and a given reference longitude

Parameters:

body_pos (astropy.coordinates.sky_coordinate.SkyCoord) – coordinates of the body
reference_long (float) – Longitude of reference point at Sun to which we determine the longitudinal separation
target_solar_radius (float) – Target solar radius to which to be backmapped. 0 corresponds to Sun’s center, 1 to 1 solar radius, and e.g. 2.5 to the source surface.
vsw (float) – solar wind speed (km/s) used to determine the position of the magnetic footpoint of the body. Default is 400.

Returns:

sep (float) – longitudinal separation of body magnetic footpoint and reference longitude in degrees
alpha (float) – backmapping angle

plot(plot_spirals=True, plot_sun_body_line=False, show_earth_centered_coord=False, reference_vsw=400, transparent=False, markers=False, return_plot_object=False, long_offset=270, outfile='', figsize=(12, 8), dpi=200, long_sector=None, long_sector_vsw=None, long_sector_color='red', long_sector_alpha=0.5, background_spirals=None, numbered_markers=False, test_plotly=False, test_plotly_template='plotly', test_plotly_legend=(1.0, 1.0), test_plotly_logo=(1.0, 0.0))

Make a polar plot showing the Sun in the center (view from North) and the positions of the selected bodies

Parameters:

plot_spirals (bool, optional) – if True, the magnetic field lines connecting the bodies with the Sun are plotted
plot_sun_body_line (bool, optional) – if True, straight lines connecting the bodies with the Sun are plotted
show_earth_centered_coord (bool, optional) – Deprecated! With the introduction of coord_sys in class SolarMACH() this function is redundant and not functional any more!
reference_vsw (int, optional) – if defined, defines solar wind speed for reference. if not defined, 400 km/s is used
transparent (bool, optional) – if True, output image has transparent background
markers (bool or string, optional) – if defined, body markers contain ‘numbers’ or ‘letters’ for better identification. If False (default), only geometric markers are used.
return_plot_object (bool, optional) – if True, figure and axis object of matplotib are returned, allowing further adjustments to the figure
long_offset (int or float, optional) – longitudinal offset for polar plot; defines where Earth’s longitude is (by default 270, i.e., at “6 o’clock”)
outfile (string, optional) – if provided, the plot is saved with outfile as filename
long_sector (list of 2 numbers, optional) – Start and stop longitude of a shaded area; e.g. [350, 20] to get a cone from 350 to 20 degree longitude (for long_sector_vsw=None).
long_sector_vsw (list of 2 numbers, optional) – Solar wind speed used to calculate Parker spirals (at start and stop longitude provided by long_sector) between which a reference cone should be drawn; e.g. [400, 400] to assume for both edges of the fill area a Parker spiral produced by solar wind speeds of 400 km/s. If None, instead of Parker spirals straight lines are used, i.e. a simple cone wil be plotted. By default None.
long_sector_color (string, optional) – String defining the matplotlib color used for the shading defined by long_sector. By default ‘red’.
long_sector_alpha (float, optional) – Float between 0.0 and 1.0, defining the matplotlib alpha used for the shading defined by long_sector. By default 0.5.W
background_spirals (list of 2 numbers (and 3 optional strings), optional) – If defined, plot evenly distributed Parker spirals over 360°. background_spirals[0] defines the number of spirals, background_spirals[1] the solar wind speed in km/s used for their calculation. background_spirals[2], background_spirals[3], and background_spirals[4] optionally change the plotting line style, color, and alpha setting, respectively (default values ‘:’, ‘grey’, and 0.1). Full example that plots 12 spirals (i.e., every 30°) using a solar wind speed of 400 km/s with solid red lines with alpha=0.2: background_spirals=[12, 400, ‘-’, ‘red’, 0.2]
numbered_markers (bool, deprecated) – Deprecated option, use markers=’numbers’ instead!

solar_diff_rot(lat)

Calculate solar differential rotation wrt. latitude, based on rLSQ method of Beljan et al. (2017), doi: 10.1051/0004-6361/201731047

Parameters:: lat (number (int, flotat)) – Heliographic latitude in degrees
Returns:: Solar angular rotation in rad/sec
Return type:: numpy.float64