solarmach

Python package of the multi-spacecraft longitudinal configuration plotter Solar-MACH

https://github.com/jgieseler/solarmach

Keywords

Repository

Python package of the multi-spacecraft longitudinal configuration plotter Solar-MACH

README.rst

solarmach
=========

|pypi Version| |conda version| |python version| |pytest| |codecov| |docs| |repostatus| |license| |zenodo|

.. |pypi Version| image:: https://img.shields.io/pypi/v/solarmach?style=flat&logo=pypi
   :target: https://pypi.org/project/solarmach/
.. |conda version| image:: https://img.shields.io/conda/vn/conda-forge/solarmach?style=flat&logo=anaconda
   :target: https://anaconda.org/conda-forge/solarmach/
.. |python version| image:: https://img.shields.io/pypi/pyversions/solarmach?style=flat&logo=python
.. |pytest| image:: https://github.com/jgieseler/solarmach/actions/workflows/pytest.yml/badge.svg?branch=main
   :target: https://github.com/jgieseler/solarmach/actions/workflows/pytest.yml
.. |codecov| image:: https://codecov.io/gh/jgieseler/solarmach/branch/main/graph/badge.svg?token=CT2P8AQU3B
   :target: https://codecov.io/gh/jgieseler/solarmach
.. |docs| image:: https://readthedocs.org/projects/solarmach/badge/?version=latest
   :target: https://solarmach.readthedocs.io/en/latest/?badge=latest
.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
   :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
   :target: https://www.repostatus.org/#active
.. |license| image:: https://img.shields.io/conda/l/conda-forge/solarmach?style=flat
   :target: https://github.com/jgieseler/solarmach/blob/main/LICENSE.rst
.. |zenodo| image:: https://zenodo.org/badge/469735286.svg
   :target: https://zenodo.org/badge/latestdoi/469735286



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:

.. code:: bash

    pip install solarmach
    
or from `conda `_ using:

.. code:: bash

    conda install -c conda-forge solarmach

Basic usage
-----------

.. code:: python

   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 = 'solarmach.png'                       # define filename of output figure. can be .png or .pdf
 
   # 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
   )
   
   # obtain data as Pandas DataFrame
   display(sm.coord_table)

.. image:: https://github.com/jgieseler/solarmach/raw/main/examples/solarmach.png
  :alt: Example output figure
  

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 example notebook `_ |nbviewer1|
  
 
.. |nbviewer1| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg
 :target: https://nbviewer.org/github/jgieseler/solarmach/blob/main/examples/example.ipynb
 

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 Europe research and innovation programme under grant agreement No 101134999 (SOLER) and from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 101004159 (SERPENTINE).

Powered by: |matplotlib| |sunpy| |speasy| |plotly|

.. |matplotlib| image:: https://matplotlib.org/stable/_static/logo_dark.svg
   :height: 25px
   :target: https://matplotlib.org
.. |sunpy| image:: https://raw.githubusercontent.com/sunpy/sunpy-logo/master/generated/sunpy_logo_landscape.svg
   :height: 30px
   :target: https://sunpy.org
.. |speasy| image:: https://raw.githubusercontent.com/SciQLop/speasy/main/logo/logo_speasy.svg
   :height: 30px
   :target: https://pypi.org/project/speasy/
.. |plotly| image:: https://avatars.githubusercontent.com/u/5997976?s=64&v=4
   :height: 30px
   :target: https://github.com/plotly/plotly.py

Owner

Citation (CITATION.cff)

# YAML 1.2
# Metadata for citation of this software according to the CFF format (https://citation-file-format.github.io/)
cff-version: 1.0.3
message: If you use this software, please cite it using these metadata.
title: solarmach
doi: 10.5281/zenodo.16882017
authors:
- given-names: Jan
  family-names: Gieseler
  affiliation: University of Turku
  orcid: https://orcid.org/0000-0003-1848-7067
- given-names: Nina
  family-names: Dresing
  affiliation: University of Turku
  orcid: https://orcid.org/0000-0003-3903-4649
- given-names: Johan
  family-names: Freiherr von Forstner
  name-particle: L.
  affiliation: Paradox Cat GmbH
- given-names: Christian
  family-names: Palmroos
  affiliation: University of Turku
  orcid: https://orcid.org/0000-0002-7778-5454
- given-names: Seve
  family-names: Nyberg
  affiliation: University of Turku
  orcid: https://orcid.org/0000-0003-2672-5491
- given-names: Rami
  family-names: Vainio
  affiliation: University of Turku
  orcid: https://orcid.org/0000-0002-3298-2067
- given-names: drazerd
  family-names: ''
  affiliation: ''
version: 0.5.1
date-released: 2025-08-15
repository-code: https://github.com/jgieseler/solarmach
license: BSD-3-Clause
preferred-citation:
  type: article
  authors:
  - given-names: Jan
    family-names: Gieseler
    orcid: https://orcid.org/0000-0003-1848-7067
  - given-names: Nina
    family-names: Dresing
    orcid: https://orcid.org/0000-0003-3903-4649
  - given-names: Christian
    family-names: Palmroos
    orcid: https://orcid.org/0000-0002-7778-5454
  - given-names: "Johan L."
    family-names: "Freiherr von Forstner"
  - given-names: "Daniel J."
    family-names: Price
    orcid: https://orcid.org/0000-0003-2672-5491
  - given-names: Rami
    family-names: Vainio
    orcid: https://orcid.org/0000-0002-3298-2067
  - given-names: Athanasios
    family-names: Kouloumvakos
    orcid: https://orcid.org/0000-0001-6589-4509
  - given-names: Laura 
    family-names: "Rodríguez-García"
    orcid: https://orcid.org/0000-0003-2361-5510
  - given-names: Domenico
    family-names: Trotta
    orcid: https://orcid.org/0000-0002-0608-8897
  - given-names: Vincent
    family-names: Génot
    orcid: https://orcid.org/0000-0002-7708-8077
  - given-names: Arnaud
    family-names: Masson
    orcid: https://orcid.org/0000-0002-5602-1957
  - given-names: Markus
    family-names: Roth
    orcid: https://orcid.org/0000-0002-1430-7172
  - given-names: Astrid
    family-names: Veronig
    orcid: https://orcid.org/0000-0003-2073-002X
  doi: 10.3389/fspas.2022.1058810
  url: http://dx.doi.org/10.3389/fspas.2022.1058810
  issn: 2296-987X
  journal: Frontiers in Astronomy and Space Sciences
  month: 2
  title: 'Solar-MACH: An open-source tool to analyze solar magnetic connection configurations'
  volume: 9
  year: 2023

GitHub Events

Committers

Last synced: about 2 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages