# planetMagFields
[](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.10685863)
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)
[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).
# 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/60/f0/a540b66a406af20c6f2d7e03ee1f66630f328cff657458d587efaabe0e41/planetmagfields-1.4.2.tar.gz",
"platform": null,
"description": "# planetMagFields\n\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.10685863)\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[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# 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.4.2",
"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": "7a5047ed695af13bf56f5184f729bb7c147c1ee0a640eefed64e961734e16045",
"md5": "d93fa206ce2c1c47895fcd847b1464ea",
"sha256": "f9c48234116a8a19be24be79eb07eb49c4423d81b7ad53e826574ef09d955e18"
},
"downloads": -1,
"filename": "planetMagFields-1.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d93fa206ce2c1c47895fcd847b1464ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 52231,
"upload_time": "2024-04-30T14:55:27",
"upload_time_iso_8601": "2024-04-30T14:55:27.037925Z",
"url": "https://files.pythonhosted.org/packages/7a/50/47ed695af13bf56f5184f729bb7c147c1ee0a640eefed64e961734e16045/planetMagFields-1.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "60f0a540b66a406af20c6f2d7e03ee1f66630f328cff657458d587efaabe0e41",
"md5": "8e124be3ea8005921d7553c221b308dd",
"sha256": "0796c98cdb2e7463129e7b97aa88e53503552467aa82de054b1f4be2ae6cfbf9"
},
"downloads": -1,
"filename": "planetmagfields-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "8e124be3ea8005921d7553c221b308dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49049,
"upload_time": "2024-04-30T14:55:28",
"upload_time_iso_8601": "2024-04-30T14:55:28.923062Z",
"url": "https://files.pythonhosted.org/packages/60/f0/a540b66a406af20c6f2d7e03ee1f66630f328cff657458d587efaabe0e41/planetmagfields-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 14:55:28",
"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
