# planetMagFields
[](https://doi.org/10.21105/joss.06677)
[](https://mybinder.org/v2/gh/AnkitBarik/planetMagFields/HEAD?labpath=%2FExploreFieldsInteractively.ipynb)
[](https://badge.fury.io/py/planetMagFields)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://doi.org/10.5281/zenodo.11768470)
Software to easily access and analyze information about magnetic fields of planets in our solar system and visualize them in both 2D and 3D.
[Prerequisites](#prerequisites)
[Installation](#installation)
[Features and examples](#features-and-examples)
[Jupyter notebook](#jupyter-notebook)
[Documentation](#documentation)
[Code contribution and reporting issues](#code-contribution-and-reporting-issues)
[Citing `planetMagFields`](#citing-planetmagfields)
[Acknowledgements](#acknowledgements)
# Prerequisites
`planetMagFields` requires [NumPy](https://numpy.org/), [Matplotlib](https://matplotlib.org/) and [SciPy](https://www.scipy.org/). Other than that, the following external libraries are used for a few different functions:
- 2D plotting for map projections other than Hammer : [Cartopy](https://scitools.org.uk/cartopy/docs/latest/) library
- Potential extrapolation: [SHTns](https://bitbucket.org/nschaeff/shtns) library
- Writing vts files for 3D visualisation: [PyEVTK](https://github.com/paulo-herrera/PyEVTK) library
# Installation
`planetMagFields` can be installed in a few different ways:
## Using `pip`
`planetMagFields` is available on [PyPI](https://pypi.org/project/planetMagFields/) and can be installed with
```bash
$ python3 -m pip install planetMagFields
```
## Using `setup.py`
You can also use `setup.py` to install `planetMagFields`:
```bash
$ git clone https://github.com/AnkitBarik/planetMagFields
$ cd planetMagFields
$ pytho3 setup.py install --user
```
Or using `pip`:
```bash
$ git clone https://github.com/AnkitBarik/planetMagFields
$ cd planetMagFields
$ python3 -m pip install . --user
```
## Using `PYTHONPATH`
Download the package from the GitHub repository and add it
to `PYTHONPATH`:
```bash
$ git clone https://github.com/AnkitBarik/planetMagFields
$ export PYTHONPATH=$PYTHONPATH:/path/to/planetMagFields
```
# Features and examples
## The `Planet` class
This gives access to all the relevant properties of a planet and has methods to plot
the field and write a `vts` file for 3D visualization. Usage:
```python
from planetmagfields import Planet
p = Planet(name='earth',datDir='planetmagfields/data/')
```
This displays the some information about the planet
```bash
Planet: Earth
l_max = 13
Dipole tilt (degrees) = -9.410531
```
and gives access to
variables associated with the planet such as:
* ``p.lmax`` : maximum spherical harmonic degree till which data is available
* ``p.glm``, ``p.hlm``: the Gauss coefficients
* ``p.Br`` : computed radial magnetic field at surface
* ``p.dipTheta`` : dipole tilt with respect to the rotation axis
* ``p.dipPhi`` : dipole longitude ( in case zero longitude is known, applicable to Earth )
* ``p.idx`` : indices to get values of Gauss coefficients
* ``p.model`` : the magnetic field model used. Available models can be obtained using the `get_models` function. Selects the latest available model when unspecified.
Example using ``IPython``:
```python
In [1]: from planetmagfields import Planet
In [2]: p = Planet(name='jupiter',model='jrm09')
Planet: Jupiter
Model: jrm09
l_max = 10
Dipole tilt (degrees) = 10.307870
In [3]: p.glm[p.idx[2,0]] # g20
Out[3]: 11670.4
In [4]: p.hlm[p.idx[4,2]] # h42
Out[4]: 27811.2
```
## 2D and 3D visualizations
`planetMagFields` can be used to produce both 2D and 3D visualizations of a planetary field.
While doing so, it also provides the option of potential extrapolation using the [SHTns](https://bitbucket.org/nschaeff/shtns/)
library. Two examples are shown below: Earth's surface field and a 3D visualization of Jupiter's field using
[Paraview](https://www.paraview.org/). This is done by writing a `.vts` file using the [PyEVTK](https://github.com/paulo-herrera/PyEVTK)
library.
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/2d/earth2d.png" width="500">
</p>
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/3d/jupiter3d.png" width=500>
</p>
# Jupyter notebook
For quick and easy visualization we include a [Jupyter](https://jupyter.org/) notebook with a binder link (see badge at the top).
This makes use of [Jupyter widgets](https://ipywidgets.readthedocs.io/) to provide dropdown lists of planets and available magnetic
field models for each as well as a slider for radial level, as shown below
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/jupyter_screenshot2.png" width="500">
</p>
This plots the radial magnetic field at the chosen radial level and the corresponding magnetic field spectrum,
<p align="center" width="100%">
<img src="https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/jupyter_screenshot3.png" width="500">
</p>
# Documentation
Full list of features with examples as well as the magnetic field models used are described in detail in the documentation,
available here: https://ankitbarik.github.io/planetMagFields/
# Code contribution and reporting issues
`planetMagFields` is an open source project and anyone is welcome to contribute to it. If you wish to contribute to this project, please follow the guidelines below:
- Please make sure the tests pass before opening a pull request.
- Please follow Python [PEP-8](https://peps.python.org/pep-0008/) guidelines when it comes to code style.
- If you wish to add new data file, please name it following the convention `<planet>_<model>.dat`, where `planet` and `model` denote the names of the planet and the magnetic field model being used. See the `data` directory for examples.
- If you implement a new feature or data source, please update the documentation accordingly.
Please report any bugs or other issues through [GitHub Issues](https://github.com/AnkitBarik/planetMagFields/issues).
# Citing `planetMagFields`
If you're using `planetMagFields` for your work, please cite the [JOSS paper](https://joss.theoj.org/papers/10.21105/joss.06677#):
Barik et al., (2024). planetMagFields: A Python package for analyzing and plotting planetary magnetic field data. Journal of Open Source Software, 9(97), 6677, https://doi.org/10.21105/joss.06677
```bibtex
@article{Barik2024,
doi = {10.21105/joss.06677},
url = {https://doi.org/10.21105/joss.06677},
year = {2024},
publisher = {The Open Journal},
volume = {9},
number = {97},
pages = {6677},
author = {Barik, Ankit and Angappan, Regupathi},
title = {planetMagFields: A Python package for analyzing and plotting planetary magnetic field data},
journal = {Journal of Open Source Software}
}
```
# Acknowledgements
I would like to thank [Regupathi Angappan](https://github.com/reguang) for motivating me to create this package, testing it and for writing the Jupyter notebook. I thank [Jon Aurnou](https://epss.ucla.edu/people/faculty/543/) for testing it out and pointing out runtime errors. I would like to thank [Thomas Gastine](https://github.com/tgastine) for comparing the plots with real data and pointing out a normalization error which has been fixed. Thanks a lot to [Arthus](https://github.com/arthus701) for adding the `setup.py`.
Raw data
{
"_id": null,
"home_page": null,
"name": "planetMagFields",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Ankit Barik <ankit.barik@gmail.com>, Regupathi Angappan <rangapp1@jhu.edu>",
"keywords": "Spherical Harmonics, Planetary Science, Spectra, Magnetic Field, Visualization, 3D visualization",
"author": "Barik, Ankit",
"author_email": "Ankit Barik <ankit.barik@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/27/28/0968140f396e7f14b91d48871acc436a95f7cc80c4b4a4b4fce069f0c67b/planetmagfields-1.5.3.tar.gz",
"platform": null,
"description": "# planetMagFields\n\n\n[](https://doi.org/10.21105/joss.06677)\n[](https://mybinder.org/v2/gh/AnkitBarik/planetMagFields/HEAD?labpath=%2FExploreFieldsInteractively.ipynb)\n[](https://badge.fury.io/py/planetMagFields)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://doi.org/10.5281/zenodo.11768470)\n\nSoftware to easily access and analyze information about magnetic fields of planets in our solar system and visualize them in both 2D and 3D.\n\n[Prerequisites](#prerequisites)\n\n[Installation](#installation)\n\n[Features and examples](#features-and-examples)\n\n[Jupyter notebook](#jupyter-notebook)\n\n[Documentation](#documentation)\n\n[Code contribution and reporting issues](#code-contribution-and-reporting-issues)\n\n[Citing `planetMagFields`](#citing-planetmagfields)\n\n[Acknowledgements](#acknowledgements)\n\n# Prerequisites\n\n`planetMagFields` requires [NumPy](https://numpy.org/), [Matplotlib](https://matplotlib.org/) and [SciPy](https://www.scipy.org/). Other than that, the following external libraries are used for a few different functions:\n\n - 2D plotting for map projections other than Hammer : [Cartopy](https://scitools.org.uk/cartopy/docs/latest/) library\n - Potential extrapolation: [SHTns](https://bitbucket.org/nschaeff/shtns) library\n - Writing vts files for 3D visualisation: [PyEVTK](https://github.com/paulo-herrera/PyEVTK) library\n\n# Installation\n\n`planetMagFields` can be installed in a few different ways:\n\n## Using `pip`\n\n`planetMagFields` is available on [PyPI](https://pypi.org/project/planetMagFields/) and can be installed with\n\n```bash\n$ python3 -m pip install planetMagFields\n```\n\n## Using `setup.py`\n\nYou can also use `setup.py` to install `planetMagFields`:\n\n```bash\n\n$ git clone https://github.com/AnkitBarik/planetMagFields\n$ cd planetMagFields\n$ pytho3 setup.py install --user\n```\n\nOr using `pip`:\n\n```bash\n\n$ git clone https://github.com/AnkitBarik/planetMagFields\n$ cd planetMagFields\n$ python3 -m pip install . --user\n```\n\n## Using `PYTHONPATH`\n\nDownload the package from the GitHub repository and add it\nto `PYTHONPATH`:\n\n```bash\n\n$ git clone https://github.com/AnkitBarik/planetMagFields\n$ export PYTHONPATH=$PYTHONPATH:/path/to/planetMagFields\n```\n\n# Features and examples\n\n## The `Planet` class\n\nThis gives access to all the relevant properties of a planet and has methods to plot\nthe field and write a `vts` file for 3D visualization. Usage:\n\n```python\nfrom planetmagfields import Planet\np = Planet(name='earth',datDir='planetmagfields/data/')\n```\n\nThis displays the some information about the planet\n\n```bash\nPlanet: Earth\nl_max = 13\nDipole tilt (degrees) = -9.410531\n```\n\nand gives access to\nvariables associated with the planet such as:\n\n * ``p.lmax`` : maximum spherical harmonic degree till which data is available\n * ``p.glm``, ``p.hlm``: the Gauss coefficients\n * ``p.Br`` : computed radial magnetic field at surface\n * ``p.dipTheta`` : dipole tilt with respect to the rotation axis\n * ``p.dipPhi`` : dipole longitude ( in case zero longitude is known, applicable to Earth )\n * ``p.idx`` : indices to get values of Gauss coefficients\n * ``p.model`` : the magnetic field model used. Available models can be obtained using the `get_models` function. Selects the latest available model when unspecified.\n\nExample using ``IPython``:\n\n```python\nIn [1]: from planetmagfields import Planet\n\nIn [2]: p = Planet(name='jupiter',model='jrm09')\nPlanet: Jupiter\nModel: jrm09\nl_max = 10\nDipole tilt (degrees) = 10.307870\n\nIn [3]: p.glm[p.idx[2,0]] # g20\nOut[3]: 11670.4\n\nIn [4]: p.hlm[p.idx[4,2]] # h42\nOut[4]: 27811.2\n```\n\n## 2D and 3D visualizations\n\n`planetMagFields` can be used to produce both 2D and 3D visualizations of a planetary field.\nWhile doing so, it also provides the option of potential extrapolation using the [SHTns](https://bitbucket.org/nschaeff/shtns/)\nlibrary. Two examples are shown below: Earth's surface field and a 3D visualization of Jupiter's field using\n[Paraview](https://www.paraview.org/). This is done by writing a `.vts` file using the [PyEVTK](https://github.com/paulo-herrera/PyEVTK)\nlibrary.\n\n<p align=\"center\" width=\"100%\">\n<img src=\"https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/2d/earth2d.png\" width=\"500\">\n</p>\n\n<p align=\"center\" width=\"100%\">\n<img src=\"https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/3d/jupiter3d.png\" width=500>\n</p>\n\n# Jupyter notebook\n\nFor quick and easy visualization we include a [Jupyter](https://jupyter.org/) notebook with a binder link (see badge at the top).\nThis makes use of [Jupyter widgets](https://ipywidgets.readthedocs.io/) to provide dropdown lists of planets and available magnetic\nfield models for each as well as a slider for radial level, as shown below\n\n<p align=\"center\" width=\"100%\">\n<img src=\"https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/jupyter_screenshot2.png\" width=\"500\">\n</p>\n\nThis plots the radial magnetic field at the chosen radial level and the corresponding magnetic field spectrum,\n\n<p align=\"center\" width=\"100%\">\n<img src=\"https://raw.githubusercontent.com/AnkitBarik/planetMagFields/main/doc/_static/images/jupyter_screenshot3.png\" width=\"500\">\n</p>\n\n# Documentation\n\nFull list of features with examples as well as the magnetic field models used are described in detail in the documentation,\navailable here: https://ankitbarik.github.io/planetMagFields/\n\n# Code contribution and reporting issues\n\n`planetMagFields` is an open source project and anyone is welcome to contribute to it. If you wish to contribute to this project, please follow the guidelines below:\n\n - Please make sure the tests pass before opening a pull request. \n - Please follow Python [PEP-8](https://peps.python.org/pep-0008/) guidelines when it comes to code style.\n - If you wish to add new data file, please name it following the convention `<planet>_<model>.dat`, where `planet` and `model` denote the names of the planet and the magnetic field model being used. See the `data` directory for examples.\n - If you implement a new feature or data source, please update the documentation accordingly. \n\nPlease report any bugs or other issues through [GitHub Issues](https://github.com/AnkitBarik/planetMagFields/issues). \n\n# Citing `planetMagFields`\n\nIf you're using `planetMagFields` for your work, please cite the [JOSS paper](https://joss.theoj.org/papers/10.21105/joss.06677#):\n\nBarik et al., (2024). planetMagFields: A Python package for analyzing and plotting planetary magnetic field data. Journal of Open Source Software, 9(97), 6677, https://doi.org/10.21105/joss.06677\n\n```bibtex\n@article{Barik2024,\n doi = {10.21105/joss.06677},\n url = {https://doi.org/10.21105/joss.06677},\n year = {2024},\n publisher = {The Open Journal},\n volume = {9},\n number = {97},\n pages = {6677},\n author = {Barik, Ankit and Angappan, Regupathi},\n title = {planetMagFields: A Python package for analyzing and plotting planetary magnetic field data},\n journal = {Journal of Open Source Software}\n}\n```\n\n# Acknowledgements\n\nI would like to thank [Regupathi Angappan](https://github.com/reguang) for motivating me to create this package, testing it and for writing the Jupyter notebook. I thank [Jon Aurnou](https://epss.ucla.edu/people/faculty/543/) for testing it out and pointing out runtime errors. I would like to thank [Thomas Gastine](https://github.com/tgastine) for comparing the plots with real data and pointing out a normalization error which has been fixed. Thanks a lot to [Arthus](https://github.com/arthus701) for adding the `setup.py`.\n",
"bugtrack_url": null,
"license": null,
"summary": "Routines to easily access information about magnetic fields of planets in our solar system and visualize them in both 2D and 3D",
"version": "1.5.3",
"project_urls": {
"Homepage": "https://ankitbarik.github.io/planetMagFields/",
"Issues": "https://github.com/AnkitBarik/planetMagFields/issues"
},
"split_keywords": [
"spherical harmonics",
" planetary science",
" spectra",
" magnetic field",
" visualization",
" 3d visualization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e16272858135526051c5d6fd94c2ff643d8cc31f0cc6d8ac87b8eddd5f68717",
"md5": "9b33e292351d536fcafb38c4a6387784",
"sha256": "bbe6247f77ba545139d73be18e086aa59ee8163706a234ce9a64145a9a4a01f0"
},
"downloads": -1,
"filename": "planetMagFields-1.5.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b33e292351d536fcafb38c4a6387784",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 53905,
"upload_time": "2024-12-06T19:46:11",
"upload_time_iso_8601": "2024-12-06T19:46:11.680901Z",
"url": "https://files.pythonhosted.org/packages/9e/16/272858135526051c5d6fd94c2ff643d8cc31f0cc6d8ac87b8eddd5f68717/planetMagFields-1.5.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "27280968140f396e7f14b91d48871acc436a95f7cc80c4b4a4b4fce069f0c67b",
"md5": "fe633f21cce89e08f10dd4feaf15533f",
"sha256": "8296e8cf9c5534e8d44661b13b2c21941cf3433f44a36b4b72d0e0ae187f8481"
},
"downloads": -1,
"filename": "planetmagfields-1.5.3.tar.gz",
"has_sig": false,
"md5_digest": "fe633f21cce89e08f10dd4feaf15533f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 51720,
"upload_time": "2024-12-06T19:46:13",
"upload_time_iso_8601": "2024-12-06T19:46:13.521401Z",
"url": "https://files.pythonhosted.org/packages/27/28/0968140f396e7f14b91d48871acc436a95f7cc80c4b4a4b4fce069f0c67b/planetmagfields-1.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 19:46:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AnkitBarik",
"github_project": "planetMagFields",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "planetmagfields"
}
JSON
