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.