API reference

solarmach.backmapping(body_pos, reference_long=None, target_solar_radius=1, vsw=400, **kwargs)

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 (in 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 in degrees

solarmach.backmapping_angle(distance, r, lat, vsw, **kwargs)

Calculates the backmapping angle phi(r) - phi_0.

This function computes the backmapping angle as defined in Eq. (1) of https://doi.org/10.3389/fspas.2022.1058810.

Parameters:
  • distance (astropy.units.Quantity) – Distance with astropy units.

  • r (astropy.units.Quantity) – Radial distance with astropy units.

  • lat (astropy.units.Quantity) – Latitude with astropy units.

  • vsw (astropy.units.Quantity) – Solar wind speed with astropy units.

  • **kwargs (dict, optional) –

    Additional keyword arguments: - diff_rot : bool, optional

    If True, differential rotation is considered. Default is True.

Returns:

angle – Backmapping angle with astropy units.

Return type:

astropy.units.Quantity

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.Quantity

solarmach.solar_diff_rot(lat, **kwargs)

Calculate the solar differential rotation rate at a given latitude. Based on rLSQ method of Beljan et al. (2017), doi: 10.1051/0004-6361/201731047

Parameters:

lat (astropy.units.Quantity) – The latitude at which to calculate the differential rotation rate, e.g., “23 * astropy.units.deg”. If no units are provided, it will be treated as radians!

Returns:

Solar angular rotation in deg/sec

Return type:

astropy.units.Quantity

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

pfss_3d(active_area=(None, None, None, None), color_code='object', rss=2.5, plot_spirals=True, plot_sun_body_line=False, numbered_markers=False, plot_equatorial_plane=True, reference_vsw=400, zoom_out=False)

Plots a 3D visualization of the Potential Field Source Surface (PFSS) model using Plotly.

Parameters:

active_areatuple, optional

A tuple specifying the active area in the format (lonmax, lonmin, latmax, latmin). Default is (None, None, None, None).

color_codestr, optional

Specifies the color coding for the field lines. Options are ‘object’ or ‘polarity’. Default is ‘object’.

rssfloat, optional

The source surface radius in solar radii. Default is 2.5.

plot_spiralsbool, optional

If True, plots the Parker spirals. Default is True.

plot_sun_body_linebool, optional

If True, plots the direct line from the Sun to the body. Default is False.

numbered_markersbool, optional

If True, adds numbered markers to the plot. Default is False.

plot_equatorial_planebool, optional

If True, plots the equatorial plane. Default is True.

reference_vswint, optional

The solar wind speed for the reference field line in km/s. Default is 400.

zoom_outbool, optional

If True, zooms out the plot to show the entire field of view. Default is False.

Returns:

None

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!

Returns:

Returns the matplotlib figure and axes if return_plot_object=True (by default set to False), else nothing.

Return type:

matplotlib figure and axes or None

plot_pfss(pfss_solution, rss=2.5, figsize=(15, 10), dpi=200, return_plot_object=False, vary=False, n_varies=1, long_offset=270, reference_vsw=400.0, markers=False, plot_spirals=True, long_sector=None, long_sector_vsw=None, long_sector_color=None, hide_logo=False, numbered_markers=False, outfile='')

Plot the Potential Field Source Surface (PFSS) solution on a polar plot with logarithmic r-axis outside the PFSS. Tracks an open field line down to the photosphere given a point on the PFSS.

Parameters:

pfss_solutionobject

The PFSS solution object containing the magnetic field data.

rssfloat, optional

The source surface radius in solar radii. Default is 2.5.

figsizetuple, optional

The size of the figure in inches. Default is (15, 10).

dpiint, optional

The resolution of the figure in dots per inch. Default is 200.

return_plot_objectbool, optional

If True, return the figure and axis objects. Default is False.

varybool, optional

If True, plot varied field lines. Default is False.

n_variesint, optional

Number of varied field lines to plot if vary is True. Default is 1.

long_offsetfloat, optional

Longitude offset for the plot in degrees. Default is 270.

reference_vswfloat, optional

Solar wind speed for the reference point in km/s. Default is 400.

markersbool or str, optional

If True or ‘letters’/’numbers’, plot markers at body positions. Default is False.

plot_spiralsbool, optional

If True, plot Parker spirals. Default is True.

long_sectorlist or tuple, optional

A 2-element list defining the start and end longitude of the cone in degrees. Default is None.

long_sector_vswlist or tuple, optional

Solar wind speeds for the Parker spirals in the long sector. Default is None.

long_sector_colorstr, optional

Color for the long sector. Default is None.

hide_logobool, optional

If True, hide the Solar-MACH logo. Default is False.

numbered_markersbool, optional

If True, use numbered markers for backward compatibility. Default is False.

outfilestr, optional

If provided, save the plot to the specified file. Default is ‘’.

Returns:

fig, axtuple

The figure and axis objects if return_plot_object is True.

Raises:

Exception

If the PFSS solution and the SolarMACH object use different coordinate systems.

Notes:

This function plots the PFSS solution on a polar plot, including the source surface, solar surface, Parker spirals, and field lines. It also supports plotting varied field lines, long sectors, and markers for different bodies. The plot can be saved to a file or displayed using matplotlib or streamlit.