Metadata-Version: 2.1
Name: solarmach
Version: 0.3.2
Summary: Multi-spacecraft longitudinal configuration plotter
Home-page: https://github.com/jgieseler/solarmach
Author: Jan Gieseler
Author-email: jan.gieseler@utu.fi
License: BSD 3-clause
Project-URL: Documentation, https://solarmach.readthedocs.io
Project-URL: Changelog, https://github.com/jgieseler/solarmach/releases
Project-URL: Issue Tracker, https://github.com/jgieseler/solarmach/issues
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
License-File: licenses/LICENSE.rst
Requires-Dist: astropy
Requires-Dist: astroquery
Requires-Dist: cmasher
Requires-Dist: drms
Requires-Dist: imageio>=2.31.6
Requires-Dist: Jinja2
Requires-Dist: lxml
Requires-Dist: matplotlib==3.5.3
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pfsspy
Requires-Dist: plotly
Requires-Dist: python-dateutil
Requires-Dist: scipy
Requires-Dist: speasy>=1.2.0
Requires-Dist: sunpy
Requires-Dist: zeep
Provides-Extra: all
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-doctestplus; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-automodapi; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"

solarmach
=========

|pypi Version| |conda version| |python version| |pytest| |codecov| |docs| |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/workflows/pytest/badge.svg
.. |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
.. |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 <https://solar-mach.github.io>`_, see `github.com/jgieseler/Solar-MACH <https://github.com/jgieseler/Solar-MACH>`_.

Installation
------------

solarmach requires python >= 3.8.

It can be installed either from `PyPI <https://pypi.org/project/solarmach/>`_ using:

.. code:: bash

    pip install solarmach
    
or from `conda <https://anaconda.org/conda-forge/solarmach/>`_ 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 = '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)

.. 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 simple example notebook <https://nbviewer.org/github/jgieseler/solarmach/blob/main/examples/example.ipynb>`_ |nbviewer1|
 
- `Show extended example notebook <https://nbviewer.org/github/serpentine-h2020/serpentine/blob/main/notebooks/solarmach/solarmach.ipynb>`_ |nbviewer2| (provided by `SERPENTINE <https://serpentine-h2020.eu>`_ project)
 
 
.. |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
 
.. |nbviewer2| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg
 :target: https://nbviewer.org/github/serpentine-h2020/serpentine/blob/main/notebooks/solarmach/solarmach.ipynb
 
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 <https://doi.org/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) <https://www.cosmos.esa.int/web/esdc/archives-user-groups/heliophysics>`_ group.

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

Powered by: |matplotlib| |sunpy|

.. |matplotlib| image:: https://matplotlib.org/stable/_static/logo2_compressed.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
