| Name | ppigrf JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Pure Python IGRF |
| upload_time | 2024-10-04 16:37:52 |
| maintainer | None |
| docs_url | None |
| author | Karl Laundal |
| requires_python | >=3.6 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pure Python International Geomagnetic Reference Field
[](https://zenodo.org/badge/latestdoi/352365168)
Pure Python code to calculate IGRF model predictions. The IGRF is a model of the Earth's main magnetic field that is updated every 5 years.
See https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html for details and https://doi.org/10.1186/s40623-020-01163-9 for even more details.
The code is vectorized, so calculations should be pretty fast.
## Install
The only dependencies are Numpy and Pandas. Install by either
```
pip install ppigrf
```
or clone the repository and run
```
python setup.py install
```
Also, if you don't want to install a module but use the code in your project, just grap ppigrf.py and the .shc file (from src/ppigrf) and place it in your working directory. That's all.
## Example
All the above choices should enable you to import like this:
```python
import ppigrf
```
IGRF model values depend on time and position. Time can be given as one or more datetimes. The position can be specified in either geodetic or geocentric coordinates. Example with geodetic coordinates:
```python
from datetime import datetime
lon = 5.32415 # degrees east
lat = 60.39299 # degrees north
h = 0 # kilometers above sea level
date = datetime(2021, 3, 28)
Be, Bn, Bu = ppigrf.igrf(lon, lat, h, date) # returns east, north, up
```
Geodetic coordinates take the ellipsoidal shape of the Earth into account. The northward component returned by the igrf function is tangential to the ellipsoid, and in general not tangential to an Earth centered sphere. The upward component is perpendicular to the ellipsoid, and in general not perpendicular to the sphere.
In some cases it is more convenient to work in geocentric coordinates, which are purely spherical. To do that, use the igrf_gc function:
```python
r = 6500 # kilometers from center of Earht
theta = 30 # colatitude in degrees
phi = 4 # degrees east (same as lon)
Br, Btheta, Bphi = ppigrf.igrf_gc(r, theta, phi, date) # returns radial, south, east
```
It is also possible to calculate magnetic field values on a grid. The code uses broadcasting rules for the coordinate inputs. You can also pass multiple dates. If you pass `K` time stamps, together with coordinates with a combined shape of e.g., `(L, M, N)`, the output will have shape `(K, L, M, N)`. Example:
```python
lon = np.array([20, 120, 220])
lat = np.array([[60, 60, 60], [-60, -60, -60]])
h = 0
dates = [datetime(y, 1, 1) for y in np.arange(1960, 2021, 20)]
Be, Bn, Bu = ppigrf.igrf(lon, lat, h, dates)
```
The output will have shape `(4, 2, 3)`.
## How to test?
It is possible to run some tests that corroborates that `ppigrf` works as
expected. To do so you need to install [`pytest`](https://docs.pytest.org). You
can do so through `pip`:
```
pip install pytest
```
Then you need to clone this repository and install `ppigrf`:
```
python setup.py install
```
Finally you can test the installed version of `ppigrf` with:
```
pytest -v
```
## Why?
There are lots of Python modules that can calculate IGRF values. Most are wrappers of Fortran code, which can be tricky to compile. This version is pure Python. For most applications it is still quite fast. I also prefer the ppigrf interface over the alternatives.
The code is also super portable: Just copy ppigrf.py and the .shc file to your project and you're done.
## Notes
The model coefficients are read from an .shc file. This is a file format that is used for certain spherical harmonic magnetic field models. See a selection of .shc model files here:
https://github.com/ESA-VirES/MagneticModel/blob/staging/eoxmagmod/eoxmagmod/data/
It should be straightforward to swap the IGRF .shc file with another model, but keep in mind that the time dependence may be implemented differently in other models. IGRF, and this code, uses linear interpolation between model updates, and changing the model file will not change the ppigrf interpolation setup.
The code is vectorized, so it will be quite fast, but probably not as fast as compiled Fortran code. One application which may require more optimization is field line tracing: In the current implementation, the coefficients are loaded and interpolated in time for every function call, which gives a lot of unnecessary overhead.
Thanks to Juha Vierinen for the setup script, and for making ppigrf available via PyPI.
## Contact
If you find errors, please let me know!
You don't need permission to copy or use this code, but I would be happy to know if it is useful for anyone else.
karl.laundal at uib.no
Raw data
{
"_id": null,
"home_page": null,
"name": "ppigrf",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Karl Laundal",
"author_email": "readme@file.md",
"download_url": null,
"platform": null,
"description": "# Pure Python International Geomagnetic Reference Field\n[](https://zenodo.org/badge/latestdoi/352365168)\n\nPure Python code to calculate IGRF model predictions. The IGRF is a model of the Earth's main magnetic field that is updated every 5 years.\nSee https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html for details and https://doi.org/10.1186/s40623-020-01163-9 for even more details.\n\nThe code is vectorized, so calculations should be pretty fast. \n\n\n## Install\nThe only dependencies are Numpy and Pandas. Install by either\n```\npip install ppigrf\n```\nor clone the repository and run \n```\npython setup.py install\n```\n\nAlso, if you don't want to install a module but use the code in your project, just grap ppigrf.py and the .shc file (from src/ppigrf) and place it in your working directory. That's all. \n\n## Example\nAll the above choices should enable you to import like this:\n```python\nimport ppigrf\n```\nIGRF model values depend on time and position. Time can be given as one or more datetimes. The position can be specified in either geodetic or geocentric coordinates. Example with geodetic coordinates:\n```python\nfrom datetime import datetime\nlon = 5.32415 # degrees east\nlat = 60.39299 # degrees north\nh = 0 # kilometers above sea level\ndate = datetime(2021, 3, 28)\n\nBe, Bn, Bu = ppigrf.igrf(lon, lat, h, date) # returns east, north, up\n```\nGeodetic coordinates take the ellipsoidal shape of the Earth into account. The northward component returned by the igrf function is tangential to the ellipsoid, and in general not tangential to an Earth centered sphere. The upward component is perpendicular to the ellipsoid, and in general not perpendicular to the sphere. \n\nIn some cases it is more convenient to work in geocentric coordinates, which are purely spherical. To do that, use the igrf_gc function:\n```python\nr = 6500 # kilometers from center of Earht\ntheta = 30 # colatitude in degrees\nphi = 4 # degrees east (same as lon)\n\nBr, Btheta, Bphi = ppigrf.igrf_gc(r, theta, phi, date) # returns radial, south, east\n```\n\nIt is also possible to calculate magnetic field values on a grid. The code uses broadcasting rules for the coordinate inputs. You can also pass multiple dates. If you pass `K` time stamps, together with coordinates with a combined shape of e.g., `(L, M, N)`, the output will have shape `(K, L, M, N)`. Example:\n```python\nlon = np.array([20, 120, 220])\nlat = np.array([[60, 60, 60], [-60, -60, -60]])\nh = 0\ndates = [datetime(y, 1, 1) for y in np.arange(1960, 2021, 20)]\nBe, Bn, Bu = ppigrf.igrf(lon, lat, h, dates)\n```\nThe output will have shape `(4, 2, 3)`.\n\n## How to test?\n\nIt is possible to run some tests that corroborates that `ppigrf` works as\nexpected. To do so you need to install [`pytest`](https://docs.pytest.org). You\ncan do so through `pip`:\n\n```\npip install pytest\n```\n\nThen you need to clone this repository and install `ppigrf`:\n\n```\npython setup.py install\n```\n\nFinally you can test the installed version of `ppigrf` with:\n\n```\npytest -v\n```\n\n\n## Why?\nThere are lots of Python modules that can calculate IGRF values. Most are wrappers of Fortran code, which can be tricky to compile. This version is pure Python. For most applications it is still quite fast. I also prefer the ppigrf interface over the alternatives. \n\nThe code is also super portable: Just copy ppigrf.py and the .shc file to your project and you're done.\n\n## Notes\nThe model coefficients are read from an .shc file. This is a file format that is used for certain spherical harmonic magnetic field models. See a selection of .shc model files here:\nhttps://github.com/ESA-VirES/MagneticModel/blob/staging/eoxmagmod/eoxmagmod/data/\n\nIt should be straightforward to swap the IGRF .shc file with another model, but keep in mind that the time dependence may be implemented differently in other models. IGRF, and this code, uses linear interpolation between model updates, and changing the model file will not change the ppigrf interpolation setup. \n\nThe code is vectorized, so it will be quite fast, but probably not as fast as compiled Fortran code. One application which may require more optimization is field line tracing: In the current implementation, the coefficients are loaded and interpolated in time for every function call, which gives a lot of unnecessary overhead.\n\nThanks to Juha Vierinen for the setup script, and for making ppigrf available via PyPI.\n\n## Contact\nIf you find errors, please let me know! \n\nYou don't need permission to copy or use this code, but I would be happy to know if it is useful for anyone else. \n\nkarl.laundal at uib.no\n",
"bugtrack_url": null,
"license": null,
"summary": "Pure Python IGRF",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4167d680b10d6dea663032374e17e45b1c375ff9a49415208653ad17415ef1a",
"md5": "635f8bba880bacc83373b71a78b13c90",
"sha256": "0ffe31783449c4f07ca6af6a5a707cf42cf4c445407eb3dafcea945b60655e66"
},
"downloads": -1,
"filename": "ppigrf-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "635f8bba880bacc83373b71a78b13c90",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 18827,
"upload_time": "2024-10-04T16:37:52",
"upload_time_iso_8601": "2024-10-04T16:37:52.293804Z",
"url": "https://files.pythonhosted.org/packages/a4/16/7d680b10d6dea663032374e17e45b1c375ff9a49415208653ad17415ef1a/ppigrf-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 16:37:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ppigrf"
}
