# PyEPPAurora
**Atmospheric ionization from particle precipitation**
[](https://github.com/st-bender/pyeppaurora/actions/workflows/ci_build_and_test.yml)
[](https://pyeppaurora.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/eppaurora)
[](https://pypi.org/project/eppaurora)
[](https://pypi.org/project/eppaurora)
[](https://codecov.io/gh/st-bender/pyeppaurora)
[](https://coveralls.io/github/st-bender/pyeppaurora)
[](https://scrutinizer-ci.com/g/st-bender/pyeppaurora/?branch=master)
[](https://doi.org/10.5281/zenodo.4298136)
Bundles some of the parametrizations for middle and upper atmospheric
ionization and recombination rates for precipitating
auroral and radiation-belt electrons as well as protons.
Includes also some recombination rate parametrizations to convert
the ionization rates to electron densities in the upper atmosphere.
See [References](#references) for a list of included parametrizations.
:warning: This package is in **beta** stage, that is, it works for the most part
and the interface should not change (much) in future versions.
Documentation is available at <https://pyeppaurora.readthedocs.io>.
## Install
### Requirements
- `numpy` - required
- `scipy` - required for 2-D interpolation
- `h5netcdf` - optional for the empirical models, install with `eppaurora[models]`
- `xarray` - optional for the empirical models, install with `eppaurora[models]`
- `pytest` - optional, for testing
### eppaurora
An installable `pip` package called `eppaurora` is available from the
main package repository, it can be installed with:
```sh
$ pip install eppaurora
```
The latest development version can be installed
with [`pip`](https://pip.pypa.io) directly from github
(see <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>
and <https://pip.pypa.io/en/stable/reference/pip_install/#git>):
```sh
$ pip install [-e] git+https://github.com/st-bender/pyeppaurora.git
```
The other option is to use a local clone:
```sh
$ git clone https://github.com/st-bender/pyeppaurora.git
$ cd pyeppaurora
```
and then using `pip` (optionally using `-e`, see
<https://pip.pypa.io/en/stable/reference/pip_install/#install-editable>):
```sh
$ pip install [-e] .
```
or using `setup.py`:
```sh
$ python setup.py install
```
Optionally, test the correct function of the module with
```sh
$ py.test [-v]
```
or even including the [doctests](https://docs.python.org/library/doctest.html)
in this document:
```sh
$ py.test [-v] --doctest-glob='*.md'
```
## Usage
The python module itself is named `eppaurora` and is imported as usual.
All functions should be `numpy`-compatible and work with scalars
and appropriately shaped arrays.
### Energetic particle input in the atmosphere
This module include various parametrizations that describe the
energy dissipation of electrons and protons entering the middle
and upper atmosphere (see [References](#references) below).
The functions are correspondingly named
- `rr1987()` for the parametrization by Roble and Ridley, 1987,
- `fang2008()` for the parametrization described in Fang et al., 2008,
- `fang2010()` for the parametrization described in Fang et al., 2010, and
- `fang2013()` for the proton parametrization by Fang et al., 2013
For example, they are called like this:
```python
>>> import eppaurora as aur
>>> ediss = aur.rr1987(1., 1., 8e5, 5e-10)
>>> ediss
3.3693621076457477e-10
>>> import numpy as np
>>> energies = np.logspace(-1, 2, 4)
>>> fluxes = np.ones_like(energies)
>>> # ca. 100, 150, 200 km
>>> scale_heights = np.array([6e5, 27e5, 40e5])
>>> rhos = np.array([5e-10, 1.7e-12, 2.6e-13])
>>> # energy dissipation "profiles"
>>> # broadcast to the right shape
>>> ediss_prof = aur.fang2008(
... energies[None, :], fluxes[None, :],
... scale_heights[:, None], rhos[:, None]
... )
>>> ediss_prof
array([[1.37708081e-49, 3.04153876e-09, 4.44256875e-07, 2.52699970e-08],
[1.60060833e-09, 8.63248169e-08, 3.64564419e-09, 1.62591310e-10],
[5.19369952e-08, 2.34089350e-08, 5.17379303e-10, 3.19504690e-11]])
```
All functions need additional input for the background atmosphere,
the scale height and the mass density as described in the listed publications.
These can be obtained, for example, from the `nrlmsise00` module
<https://github.com/st-bender/pynrlmsise00>.
Profiles can then be calculated by passing the respective scale height
and density profiles in addition to the energy and flux.
`fang1020()` and `fang2013()` are for mono-energetic particles and to
obtain a realistic description, the results should be integrated
over the respective energy spectrum.
For this there are spectra functions available for Gaussian, Maxwellian,
and power-law distribution.
### Recombination rates
Some atmospheric recombination rates $\alpha$ are available within
`eppaurora.recombination` to convert the ionization rates $q$
to electron densities $n_e$ via $q = \alpha n_e^2$.
The recombination rates are parametrized according to altitude,
see [References](#references).
### Conductivity and conductance
Estimators for the Hall and Pedersen conductivity and conductance
are available via the `eppaurora.conductivity` module.
It contains the approximate solution "Robinson formula" for the conductances,
and the functions for the conductivities that need the electron density
and a model for the magnetic field,
see [References](#references).
For example the "Robinson" conductances for an average energy `en_avg` and flux `flx`
can be obtained by calling `SigmaH_robinson1987(<en_avg>, <flx>)`:
and `SigmaP_robinson1987(<en_avg>, <flx>)`:
```python
>>> import eppaurora as aur
>>> aur.SigmaH_robinson1987(10.0, 1.0)
10.985365619753862
>>> aur.SigmaP_robinson1987(10.0, 1.0)
3.4482758620689653
```
### Empirical ionization rate models
This package provides the coefficients and evaluation function
for the SSUSI-derived ionization rate model.
It is imported via `eppaurora.models` and the coefficients are
available through `ssusiq2023_coeffs()`.
The model itself can be evaluated with `ssusiq2023()`
for a certain geomagnetic latitude (gmlat),
magnetic local time (mlt), and altitude by providing the space-weather
coefficients of Kp, PC, Ap, and the 81-day averaged F10.7 fluxes as inputs:
`ssusiq2023(<gmlat>, <mlt>, <altitude>, [<list of index values>])`.
Note that this returns the natural logarithm of the ionization rate,
normalized to 1 cm⁻³ s⁻¹.
Instead of a list or `numpy`-array, an `xarray.DataArray` can be used for
the indices which will promote the coordinates to the result,
such as an extra time dimension.
```python
>>> from eppaurora.models import ssusiq2023
>>> ssusiq2023(65.0, 3.0, 100.0, [4.0, 10.0, 100.0, 157.0]) # doctest: +SKIP
<xarray.DataArray 'log_q' (dim_0: 1)>
array([18.80679417])
Coordinates:
altitude float32 100.0
latitude float32 66.6
mlt float32 3.0
Dimensions without coordinates: dim_0
Attributes:
long_name: natural logarithm of ionization rate
units: log(cm-3 s-1)
```
Various options to use different coefficients or to interpolate
to a finer grid exist, check the docstring of `ssusiq2023()`.
The geomagnetic indices can be obtained, for example,
from the `spaceweather` module
<https://github.com/st-bender/pyspaceweather>.
### Other
Basic class and method documentation is accessible via `pydoc`:
```sh
$ pydoc eppaurora
$ pydoc eppaurora.brems
$ pydoc eppaurora.conductivity
$ pydoc eppaurora.electrons
$ pydoc eppaurora.protons
$ pydoc eppaurora.recombination
$ pydoc eppaurora.models.ssusiq2023
```
## References
### Electron ionization
[1]: Roble and Ridley, Ann. Geophys., 5A(6), 369--382, 1987
[2]: Fang et al., J. Geophys. Res. Space Phys., 113, A09311, 2008,
doi: [10.1029/2008JA013384](https://doi.org/10.1029/2008JA013384)
[3]: Fang et al., Geophys. Res. Lett., 37, L22106, 2010,
doi: [10.1029/2010GL045406](https://doi.org/10.1029/2010GL045406)
### Ionization by secondary electrons from bremsstrahlung
[4]: Berger et al., Journal of Atmospheric and Terrestrial Physics,
Volume 36, Issue 4, 591--617, April 1974,
doi: [10.1016/0021-9169(74)90085-3](https://doi.org/10.1016/0021-9169%2874%2990085-3)
### Proton ionization
[5]: Fang et al., J. Geophys. Res. Space Phys., 118, 5369--5378, 2013,
doi: [10.1002/jgra.50484](https://doi.org/10.1002/jgra.50484)
### Recombination rates
[6]: Vickrey et al., J. Geophys. Res. Space Phys., 87, A7, 5184--5196,
doi: [10.1029/ja087ia07p05184](https://doi.org/10.1029/ja087ia07p05184)
[7]: Gledhill, Radio Sci., 21, 3, 399-408,
doi: [10.1029/rs021i003p00399](https://doi.org/10.1029/rs021i003p00399)
[8]: https://ssusi.jhuapl.edu/data_algorithms
### Conductivity and conductance
[9]: Brekke et al., J. Geophys. Res., 79(25), 3773--3790, Sept. 1974,
doi: [10.1029/JA079i025p03773](https://doi.org/10.1029/JA079i025p03773)
[10]: Vickrey et al., J. Geophys. Res., 86(A1), 65--75, Jan. 1981,
doi: [10.1029/JA086iA01p00065](https://doi.org/10.1029/JA086iA01p00065)
[11]: Robinson et al., J. Geophys. Res. Space Phys., 92(A3), 2565--2569, Mar. 1987,
doi: [10.1029/JA092iA03p02565](https://doi.org/10.1029/JA092iA03p02565)
## License
This python interface is free software: you can redistribute it or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 2 (GPLv2), see [local copy](./LICENSE)
or [online version](http://www.gnu.org/licenses/gpl-2.0.html).
Raw data
{
"_id": null,
"home_page": "https://github.com/st-bender/pyeppaurora",
"name": "eppaurora",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Stefan Bender",
"author_email": "stefan.bender@ntnu.no",
"download_url": "https://files.pythonhosted.org/packages/5d/dc/1ad9b022251dd3e18c8a011ca700df03fa99bebd4b0b1ff51ed83f5405f5/eppaurora-0.3.1.tar.gz",
"platform": null,
"description": "# PyEPPAurora\n\n**Atmospheric ionization from particle precipitation**\n\n[](https://github.com/st-bender/pyeppaurora/actions/workflows/ci_build_and_test.yml)\n[](https://pyeppaurora.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/eppaurora)\n[](https://pypi.org/project/eppaurora)\n[](https://pypi.org/project/eppaurora)\n[](https://codecov.io/gh/st-bender/pyeppaurora)\n[](https://coveralls.io/github/st-bender/pyeppaurora)\n[](https://scrutinizer-ci.com/g/st-bender/pyeppaurora/?branch=master)\n\n[](https://doi.org/10.5281/zenodo.4298136)\n\nBundles some of the parametrizations for middle and upper atmospheric\nionization and recombination rates for precipitating\nauroral and radiation-belt electrons as well as protons.\nIncludes also some recombination rate parametrizations to convert\nthe ionization rates to electron densities in the upper atmosphere.\nSee [References](#references) for a list of included parametrizations.\n\n:warning: This package is in **beta** stage, that is, it works for the most part\nand the interface should not change (much) in future versions.\n\nDocumentation is available at <https://pyeppaurora.readthedocs.io>.\n\n## Install\n\n### Requirements\n\n- `numpy` - required\n- `scipy` - required for 2-D interpolation\n- `h5netcdf` - optional for the empirical models, install with `eppaurora[models]`\n- `xarray` - optional for the empirical models, install with `eppaurora[models]`\n- `pytest` - optional, for testing\n\n### eppaurora\n\nAn installable `pip` package called `eppaurora` is available from the\nmain package repository, it can be installed with:\n```sh\n$ pip install eppaurora\n```\nThe latest development version can be installed\nwith [`pip`](https://pip.pypa.io) directly from github\n(see <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>\nand <https://pip.pypa.io/en/stable/reference/pip_install/#git>):\n\n```sh\n$ pip install [-e] git+https://github.com/st-bender/pyeppaurora.git\n```\n\nThe other option is to use a local clone:\n\n```sh\n$ git clone https://github.com/st-bender/pyeppaurora.git\n$ cd pyeppaurora\n```\nand then using `pip` (optionally using `-e`, see\n<https://pip.pypa.io/en/stable/reference/pip_install/#install-editable>):\n\n```sh\n$ pip install [-e] .\n```\n\nor using `setup.py`:\n\n```sh\n$ python setup.py install\n```\n\nOptionally, test the correct function of the module with\n\n```sh\n$ py.test [-v]\n```\n\nor even including the [doctests](https://docs.python.org/library/doctest.html)\nin this document:\n\n```sh\n$ py.test [-v] --doctest-glob='*.md'\n```\n\n## Usage\n\nThe python module itself is named `eppaurora` and is imported as usual.\n\nAll functions should be `numpy`-compatible and work with scalars\nand appropriately shaped arrays.\n\n### Energetic particle input in the atmosphere\n\nThis module include various parametrizations that describe the\nenergy dissipation of electrons and protons entering the middle\nand upper atmosphere (see [References](#references) below).\nThe functions are correspondingly named\n\n- `rr1987()` for the parametrization by Roble and Ridley, 1987,\n- `fang2008()` for the parametrization described in Fang et al., 2008,\n- `fang2010()` for the parametrization described in Fang et al., 2010, and\n- `fang2013()` for the proton parametrization by Fang et al., 2013\n\nFor example, they are called like this:\n\n```python\n>>> import eppaurora as aur\n>>> ediss = aur.rr1987(1., 1., 8e5, 5e-10)\n>>> ediss\n3.3693621076457477e-10\n>>> import numpy as np\n>>> energies = np.logspace(-1, 2, 4)\n>>> fluxes = np.ones_like(energies)\n>>> # ca. 100, 150, 200 km\n>>> scale_heights = np.array([6e5, 27e5, 40e5])\n>>> rhos = np.array([5e-10, 1.7e-12, 2.6e-13])\n>>> # energy dissipation \"profiles\"\n>>> # broadcast to the right shape\n>>> ediss_prof = aur.fang2008(\n... \tenergies[None, :], fluxes[None, :],\n... \tscale_heights[:, None], rhos[:, None]\n... )\n>>> ediss_prof\narray([[1.37708081e-49, 3.04153876e-09, 4.44256875e-07, 2.52699970e-08],\n [1.60060833e-09, 8.63248169e-08, 3.64564419e-09, 1.62591310e-10],\n [5.19369952e-08, 2.34089350e-08, 5.17379303e-10, 3.19504690e-11]])\n\n```\n\nAll functions need additional input for the background atmosphere,\nthe scale height and the mass density as described in the listed publications.\nThese can be obtained, for example, from the `nrlmsise00` module\n<https://github.com/st-bender/pynrlmsise00>.\nProfiles can then be calculated by passing the respective scale height\nand density profiles in addition to the energy and flux.\n\n`fang1020()` and `fang2013()` are for mono-energetic particles and to\nobtain a realistic description, the results should be integrated\nover the respective energy spectrum.\nFor this there are spectra functions available for Gaussian, Maxwellian,\nand power-law distribution.\n\n### Recombination rates\n\nSome atmospheric recombination rates $\\alpha$ are available within\n`eppaurora.recombination` to convert the ionization rates $q$\nto electron densities $n_e$ via $q = \\alpha n_e^2$.\nThe recombination rates are parametrized according to altitude,\nsee [References](#references).\n\n### Conductivity and conductance\n\nEstimators for the Hall and Pedersen conductivity and conductance\nare available via the `eppaurora.conductivity` module.\nIt contains the approximate solution \"Robinson formula\" for the conductances,\nand the functions for the conductivities that need the electron density\nand a model for the magnetic field,\nsee [References](#references).\n\nFor example the \"Robinson\" conductances for an average energy `en_avg` and flux `flx`\ncan be obtained by calling `SigmaH_robinson1987(<en_avg>, <flx>)`:\nand `SigmaP_robinson1987(<en_avg>, <flx>)`:\n\n```python\n>>> import eppaurora as aur\n>>> aur.SigmaH_robinson1987(10.0, 1.0)\n10.985365619753862\n>>> aur.SigmaP_robinson1987(10.0, 1.0)\n3.4482758620689653\n\n```\n\n### Empirical ionization rate models\n\nThis package provides the coefficients and evaluation function\nfor the SSUSI-derived ionization rate model.\nIt is imported via `eppaurora.models` and the coefficients are\navailable through `ssusiq2023_coeffs()`.\n\nThe model itself can be evaluated with `ssusiq2023()`\nfor a certain geomagnetic latitude (gmlat),\nmagnetic local time (mlt), and altitude by providing the space-weather\ncoefficients of Kp, PC, Ap, and the 81-day averaged F10.7 fluxes as inputs:\n`ssusiq2023(<gmlat>, <mlt>, <altitude>, [<list of index values>])`.\nNote that this returns the natural logarithm of the ionization rate,\nnormalized to 1 cm\u207b\u00b3 s\u207b\u00b9.\n\nInstead of a list or `numpy`-array, an `xarray.DataArray` can be used for\nthe indices which will promote the coordinates to the result,\nsuch as an extra time dimension.\n\n```python\n>>> from eppaurora.models import ssusiq2023\n>>> ssusiq2023(65.0, 3.0, 100.0, [4.0, 10.0, 100.0, 157.0]) # doctest: +SKIP\n<xarray.DataArray 'log_q' (dim_0: 1)>\narray([18.80679417])\nCoordinates:\n altitude float32 100.0\n latitude float32 66.6\n mlt float32 3.0\nDimensions without coordinates: dim_0\nAttributes:\n long_name: natural logarithm of ionization rate\n units: log(cm-3 s-1)\n\n```\n\nVarious options to use different coefficients or to interpolate\nto a finer grid exist, check the docstring of `ssusiq2023()`.\nThe geomagnetic indices can be obtained, for example,\nfrom the `spaceweather` module\n<https://github.com/st-bender/pyspaceweather>.\n\n### Other\n\nBasic class and method documentation is accessible via `pydoc`:\n\n```sh\n$ pydoc eppaurora\n$ pydoc eppaurora.brems\n$ pydoc eppaurora.conductivity\n$ pydoc eppaurora.electrons\n$ pydoc eppaurora.protons\n$ pydoc eppaurora.recombination\n$ pydoc eppaurora.models.ssusiq2023\n```\n\n## References\n\n### Electron ionization\n\n[1]: Roble and Ridley, Ann. Geophys., 5A(6), 369--382, 1987 \n[2]: Fang et al., J. Geophys. Res. Space Phys., 113, A09311, 2008,\ndoi: [10.1029/2008JA013384](https://doi.org/10.1029/2008JA013384) \n[3]: Fang et al., Geophys. Res. Lett., 37, L22106, 2010,\ndoi: [10.1029/2010GL045406](https://doi.org/10.1029/2010GL045406) \n\n### Ionization by secondary electrons from bremsstrahlung\n\n[4]: Berger et al., Journal of Atmospheric and Terrestrial Physics,\nVolume 36, Issue 4, 591--617, April 1974,\ndoi: [10.1016/0021-9169(74)90085-3](https://doi.org/10.1016/0021-9169%2874%2990085-3)\n\n### Proton ionization\n\n[5]: Fang et al., J. Geophys. Res. Space Phys., 118, 5369--5378, 2013,\ndoi: [10.1002/jgra.50484](https://doi.org/10.1002/jgra.50484)\n\n### Recombination rates\n\n[6]: Vickrey et al., J. Geophys. Res. Space Phys., 87, A7, 5184--5196,\ndoi: [10.1029/ja087ia07p05184](https://doi.org/10.1029/ja087ia07p05184) \n[7]: Gledhill, Radio Sci., 21, 3, 399-408,\ndoi: [10.1029/rs021i003p00399](https://doi.org/10.1029/rs021i003p00399) \n[8]: https://ssusi.jhuapl.edu/data_algorithms\n\n### Conductivity and conductance\n\n[9]: Brekke et al., J. Geophys. Res., 79(25), 3773--3790, Sept. 1974,\ndoi: [10.1029/JA079i025p03773](https://doi.org/10.1029/JA079i025p03773) \n[10]: Vickrey et al., J. Geophys. Res., 86(A1), 65--75, Jan. 1981,\ndoi: [10.1029/JA086iA01p00065](https://doi.org/10.1029/JA086iA01p00065) \n[11]: Robinson et al., J. Geophys. Res. Space Phys., 92(A3), 2565--2569, Mar. 1987,\ndoi: [10.1029/JA092iA03p02565](https://doi.org/10.1029/JA092iA03p02565) \n\n## License\n\nThis python interface is free software: you can redistribute it or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, version 2 (GPLv2), see [local copy](./LICENSE)\nor [online version](http://www.gnu.org/licenses/gpl-2.0.html).\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "Atomspheric ionization from auroral particle precipitation",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/st-bender/pyeppaurora"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9660f05d170110d4da7774dba79fcbf7343fb86dc3dd4de170455aec8cc73135",
"md5": "484ac1daa559d9b4f5def63829e43e3b",
"sha256": "e5cb8e865e08790e68743e77be609ddaf6570b3cdee3d5676748e9ddb4b7e1a7"
},
"downloads": -1,
"filename": "eppaurora-0.3.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "484ac1daa559d9b4f5def63829e43e3b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 180128,
"upload_time": "2023-10-31T17:21:05",
"upload_time_iso_8601": "2023-10-31T17:21:05.161826Z",
"url": "https://files.pythonhosted.org/packages/96/60/f05d170110d4da7774dba79fcbf7343fb86dc3dd4de170455aec8cc73135/eppaurora-0.3.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ddc1ad9b022251dd3e18c8a011ca700df03fa99bebd4b0b1ff51ed83f5405f5",
"md5": "3da213350557f72aeb52e26d085aa3e7",
"sha256": "fc667f3c702478c9f5cc5384f18855cacf3d38ab913a21ac6c6922e421adb8b2"
},
"downloads": -1,
"filename": "eppaurora-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "3da213350557f72aeb52e26d085aa3e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 186670,
"upload_time": "2023-10-31T17:21:08",
"upload_time_iso_8601": "2023-10-31T17:21:08.394527Z",
"url": "https://files.pythonhosted.org/packages/5d/dc/1ad9b022251dd3e18c8a011ca700df03fa99bebd4b0b1ff51ed83f5405f5/eppaurora-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-31 17:21:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "st-bender",
"github_project": "pyeppaurora",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "eppaurora"
}
JSON
