solarmach

The Solar MAgnetic Connection Haus (Solar-MACH) tool is a multi-spacecraft longitudinal configuration plotter. This is the repository of the pip/conda package of Solar-MACH, called solarmach. For the corresponding streamlit repository, which is used for solar-mach.github.io, see github.com/jgieseler/Solar-MACH.

Installation

solarmach requires python >= 3.10.

It can be installed either from PyPI using:

pip install solarmach

or from conda using:

conda install -c conda-forge solarmach

Basic usage

from solarmach import SolarMACH, print_body_list

# optional: get list of available bodies/spacecraft
print(print_body_list().index)

# necessary options
body_list = ['STEREO-A', 'Earth', 'BepiColombo', 'PSP', 'Solar Orbiter', 'Mars']
date = '2021-10-28 15:15:00'

# Previously you needed to define position-sensitive solar wind speed per
# body in body_list, e.g., vsw_list = [400, 400, 400, 400, 400, 400, 400]
# Now you can skip this parameter or provide an empty list. Then solarmach
# will try to automatically obtain measured solar wind speeds from each
# spacecraft
vsw_list = []

# optional parameters
coord_sys = 'Carrington'                         # 'Carrington' (default) or 'Stonyhurst'
reference_long = 273                             # longitude of reference (None to omit)
reference_lat = 0                                # latitude of reference (None to omit)
plot_spirals = True                              # plot Parker spirals for each body
plot_sun_body_line = True                        # plot straight line between Sun and body
long_offset = 270                                # longitudinal offset for polar plot; defines where Earth's longitude is (by default 270, i.e., at "6 o'clock")
reference_vsw = 400                              # define solar wind speed at reference
return_plot_object = False                       # figure and axis object of matplotib are returned, allowing further adjustments to the figure
transparent = False                              # make output figure background transparent
markers = 'numbers'                              # use 'numbers' or 'letters' for the body markers (use False for colored squares)
filename = 'Solar-MACH_'+date.replace(' ', '_')  # define filename of output figure

# initialize
sm = SolarMACH(date, body_list, vsw_list, reference_long, reference_lat, coord_sys)

# make plot
sm.plot(
   plot_spirals=plot_spirals,
   plot_sun_body_line=plot_sun_body_line,
   reference_vsw=reference_vsw,
   transparent=transparent,
   markers=markers,
   long_offset=long_offset,
   return_plot_object=return_plot_object,
   outfile=filename+'.png'
)

# obtain data as Pandas DataFrame
display(sm.coord_table)

Documentation

Full documentation for the package can be found at https://solarmach.readthedocs.io

Example Notebooks

solarmach can easily be run in a Jupyter Notebook.

Show simple example notebook
Show extended example notebook (provided by SERPENTINE project)

Contributing

Contributions to this package are very much welcome and encouraged! Contributions can take the form of issues to report bugs and request new features or pull requests to submit new code.

Please make contributions specific to the streamlit web-version that is used for solar-mach.github.io in the corresponding repository at github.com/jgieseler/Solar-MACH.

Citation

Please cite the following paper if you use solarmach in your publication:

Gieseler, J., Dresing, N., Palmroos, C., von Forstner, J.L.F., Price, D.J., Vainio, R. et al. (2022). Solar-MACH: An open-source tool to analyze solar magnetic connection configurations. Front. Astronomy Space Sci. 9. doi:10.3389/fspas.2022.1058810

Acknowledgements

The Solar-MACH tool was originally developed at Kiel University, Germany and further discussed within the ESA Heliophysics Archives USer (HAUS) group.

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 101004159.

jgieseler / solarmach