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.10.
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
Raw data
{
"_id": null,
"home_page": "https://github.com/jgieseler/solarmach",
"name": "solarmach",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Jan Gieseler",
"author_email": "jan.gieseler@utu.fi",
"download_url": "https://files.pythonhosted.org/packages/9c/23/b8a9eef75e26a1a0a419d306aab4ea2f63819eb793d69fafa2888a462ca7/solarmach-0.4.1.tar.gz",
"platform": null,
"description": "solarmach\n=========\n\n|pypi Version| |conda version| |python version| |pytest| |codecov| |docs| |license| |zenodo|\n\n.. |pypi Version| image:: https://img.shields.io/pypi/v/solarmach?style=flat&logo=pypi\n :target: https://pypi.org/project/solarmach/\n.. |conda version| image:: https://img.shields.io/conda/vn/conda-forge/solarmach?style=flat&logo=anaconda\n :target: https://anaconda.org/conda-forge/solarmach/\n.. |python version| image:: https://img.shields.io/pypi/pyversions/solarmach?style=flat&logo=python\n.. |pytest| image:: https://github.com/jgieseler/solarmach/workflows/pytest/badge.svg\n.. |codecov| image:: https://codecov.io/gh/jgieseler/solarmach/branch/main/graph/badge.svg?token=CT2P8AQU3B\n :target: https://codecov.io/gh/jgieseler/solarmach\n.. |docs| image:: https://readthedocs.org/projects/solarmach/badge/?version=latest\n :target: https://solarmach.readthedocs.io/en/latest/?badge=latest\n.. |license| image:: https://img.shields.io/conda/l/conda-forge/solarmach?style=flat\n :target: https://github.com/jgieseler/solarmach/blob/main/LICENSE.rst\n.. |zenodo| image:: https://zenodo.org/badge/469735286.svg\n :target: https://zenodo.org/badge/latestdoi/469735286\n\n\n\nThe 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>`_.\n\nInstallation\n------------\n\nsolarmach requires python >= 3.10.\n\nIt can be installed either from `PyPI <https://pypi.org/project/solarmach/>`_ using:\n\n.. code:: bash\n\n pip install solarmach\n \nor from `conda <https://anaconda.org/conda-forge/solarmach/>`_ using:\n\n.. code:: bash\n\n conda install -c conda-forge solarmach\n\nBasic usage\n-----------\n\n.. code:: python\n\n from solarmach import SolarMACH, print_body_list\n\n # optional: get list of available bodies/spacecraft\n print(print_body_list().index)\n\n # necessary options\n body_list = ['STEREO-A', 'Earth', 'BepiColombo', 'PSP', 'Solar Orbiter', 'Mars']\n date = '2021-10-28 15:15:00'\n\n # Previously you needed to define position-sensitive solar wind speed per\n # body in body_list, e.g., vsw_list = [400, 400, 400, 400, 400, 400, 400]\n # Now you can skip this parameter or provide an empty list. Then solarmach\n # will try to automatically obtain measured solar wind speeds from each\n # spacecraft\n vsw_list = []\n\n # optional parameters\n coord_sys = 'Carrington' # 'Carrington' (default) or 'Stonyhurst'\n reference_long = 273 # longitude of reference (None to omit)\n reference_lat = 0 # latitude of reference (None to omit)\n plot_spirals = True # plot Parker spirals for each body\n plot_sun_body_line = True # plot straight line between Sun and body\n long_offset = 270 # longitudinal offset for polar plot; defines where Earth's longitude is (by default 270, i.e., at \"6 o'clock\")\n reference_vsw = 400 # define solar wind speed at reference\n return_plot_object = False # figure and axis object of matplotib are returned, allowing further adjustments to the figure\n transparent = False # make output figure background transparent\n markers = 'numbers' # use 'numbers' or 'letters' for the body markers (use False for colored squares)\n filename = 'Solar-MACH_'+date.replace(' ', '_') # define filename of output figure\n\n # initialize\n sm = SolarMACH(date, body_list, vsw_list, reference_long, reference_lat, coord_sys)\n\n # make plot\n sm.plot(\n plot_spirals=plot_spirals,\n plot_sun_body_line=plot_sun_body_line,\n reference_vsw=reference_vsw,\n transparent=transparent,\n markers=markers,\n long_offset=long_offset,\n return_plot_object=return_plot_object,\n outfile=filename+'.png'\n )\n \n # obtain data as Pandas DataFrame\n display(sm.coord_table)\n\n.. image:: https://github.com/jgieseler/solarmach/raw/main/examples/solarmach.png\n :alt: Example output figure\n \n\nDocumentation\n-------------\nFull documentation for the package can be found at https://solarmach.readthedocs.io\n\n \nExample Notebooks\n-----------------\n\n**solarmach** can easily be run in a Jupyter Notebook. \n\n- `Show simple example notebook <https://nbviewer.org/github/jgieseler/solarmach/blob/main/examples/example.ipynb>`_ |nbviewer1|\n \n- `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)\n \n \n.. |nbviewer1| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg\n :target: https://nbviewer.org/github/jgieseler/solarmach/blob/main/examples/example.ipynb\n \n.. |nbviewer2| image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg\n :target: https://nbviewer.org/github/serpentine-h2020/serpentine/blob/main/notebooks/solarmach/solarmach.ipynb\n \nCitation\n--------\n\nPlease cite the following paper if you use **solarmach** in your publication:\n\nGieseler, J., Dresing, N., Palmroos, C., von Forstner, J.L.F., Price, D.J., Vainio, R. et al. (2022).\nSolar-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>`_ \n \nAcknowledgements\n----------------\n \nThe 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.\n\nThis project has received funding from the European Union\u2019s Horizon 2020 research and innovation programme under grant agreement No 101004159.\n\nPowered by: |matplotlib| |sunpy|\n\n.. |matplotlib| image:: https://matplotlib.org/stable/_static/logo2_compressed.svg\n :height: 25px\n :target: https://matplotlib.org\n.. |sunpy| image:: https://raw.githubusercontent.com/sunpy/sunpy-logo/master/generated/sunpy_logo_landscape.svg\n :height: 30px\n :target: https://sunpy.org\n",
"bugtrack_url": null,
"license": "BSD 3-clause",
"summary": "Multi-spacecraft longitudinal configuration plotter",
"version": "0.4.1",
"project_urls": {
"Changelog": "https://github.com/jgieseler/solarmach/releases",
"Documentation": "https://solarmach.readthedocs.io",
"Homepage": "https://github.com/jgieseler/solarmach",
"Issue Tracker": "https://github.com/jgieseler/solarmach/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b7f3119f11b85acd2b01bd1ceb5be246b0ce8ae08ef88f47a16cf53400397e4",
"md5": "2f3fef08e6c3d6c1b6893e2fe4b76f8e",
"sha256": "402cc943b46e94723314c157d3c0c9f64ac807171b2664cbb998a92ee16bc9e3"
},
"downloads": -1,
"filename": "solarmach-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f3fef08e6c3d6c1b6893e2fe4b76f8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 38334,
"upload_time": "2024-06-12T14:48:24",
"upload_time_iso_8601": "2024-06-12T14:48:24.616797Z",
"url": "https://files.pythonhosted.org/packages/3b/7f/3119f11b85acd2b01bd1ceb5be246b0ce8ae08ef88f47a16cf53400397e4/solarmach-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c23b8a9eef75e26a1a0a419d306aab4ea2f63819eb793d69fafa2888a462ca7",
"md5": "9c6d75b4ea4b920f8589df1e60ff2447",
"sha256": "8dbeb5620a4f96a69e703516d8d1af86668c1ac38c64d9cd7650b45c98ddfd5a"
},
"downloads": -1,
"filename": "solarmach-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "9c6d75b4ea4b920f8589df1e60ff2447",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3728668,
"upload_time": "2024-06-12T14:49:46",
"upload_time_iso_8601": "2024-06-12T14:49:46.981651Z",
"url": "https://files.pythonhosted.org/packages/9c/23/b8a9eef75e26a1a0a419d306aab4ea2f63819eb793d69fafa2888a462ca7/solarmach-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-12 14:49:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jgieseler",
"github_project": "solarmach",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "solarmach"
}
JSON
