# AniMAIRE
A Python toolkit for calculating dose rates and aircraft electronics upset rates in Earth's atmosphere based on any incoming proton or alpha particle spectra, with any pitch angle distribution.
**N.B. Currently this tool has only been tested on Linux-based machines (not on Windows yet) and requires that you either have access to output asymptotic directions generated by [OTSO](https://github.com/NLarsen15/OTSO) or that [MAGNETOCOSMICS](http://cosray.unibe.ch/~laurent/magnetocosmics/) is installed on your machine.**
If you use this software for scientific research, please reference AniMAIRE according to the appropriate journal publication rules.
A scientific paper about this software is currently in production, and we recently published a preprint, [which can be found here](https://www.researchgate.net/publication/380403797_AniMAIRE_-_A_New_Openly_Available_Tool_for_Calculating_Atmospheric_Ionising_Radiation_Dose_Rates_and_Single_Event_Effects_During_Anisotropic_Conditions), about AniMAIRE and some interesting scientific findings we've made using our work with AniMAIRE so far.
You can use AniMAIRE to produce dose rate data and maps throughout large space weather events and plot them like this:
<!-- Original inline HTML code:
// <img src="https://raw.githubusercontent.com/ssc-maire/AniMAIRE-public/main/Ani_GLE_only_timestamp1_with_legend.svg" width="350" alt="Dose rate map for a GLE"/> <img src="https://raw.githubusercontent.com/ssc-maire/AniMAIRE-public/main/Ani_GLE_only_timestamp5_with_legend.svg" width="350" alt="Dose rate map for the same GLE at another timestamp"/>
-->
<!--  |  -->
## Table of Contents
- [Installation](#installation)
- [Running AniMAIRE with Precomputed Asymptotic Direction Files (Recommended method if you don't have access to Magnetocosmics)](#running-animaire-with-precomputed-asymptotic-direction-files-recommended-method-if-you-dont-have-access-to-magnetocosmics)
- [Running AniMAIRE with Magnetocosmics (Alternative Method)](#running-animaire-with-magnetocosmics-alternative-method)
- [Usage](#usage)
- [Testing that AniMAIRE is working](#testing-that-animaire-is-working)
- [Calculating dose rates at any location in Earth's atmosphere](#calculating-dose-rates-at-any-location-in-earths-atmosphere)
- [Simple isotropic runs and plotting](#simple-isotropic-runs-and-plotting)
- [Anisotropic runs](#anisotropic-runs)
- [Functions for running AniMAIRE for specific situations and for a past timestamp](#functions-for-running-animaire-for-specific-situations-and-for-a-past-timestamp)
## Installation
To install this toolkit using the common pip Python method, run
```bash
pip install AniMAIRE
```
Otherwise, to install this toolkit from this Github repository, first clone this repository to your local system, and then from the cloned respository, run
```bash
sudo pip3 install .
```
in the cloned directory.
Note that there are quite a few sizeable data files within some of the dependencies for this package that get copied during installation (on the order of about several hundred megabytes in total) so installation may take a couple of minutes.
## Running AniMAIRE with Precomputed Asymptotic Direction Files (Recommended method if you don't have access to Magnetocosmics)
The recommended way to run AniMAIRE is to use precomputed asymptotic direction files. This approach doesn't require having Magnetocosmics installed on your system.
1. **Using OTSO output files (Recommended)**: [OTSO](https://github.com/NLarsen15/OTSO) is an open-source tool specifically designed for calculating asymptotic directions. It's more modern, easier to install, and community-oriented. To generate asymptotic direction files with OTSO:
- Install OTSO following the instructions at their repository
- Use OTSO to generate CSV files containing asymptotic directions
- The files should follow the naming convention: `latitude_longitude.csv` (e.g., `51.5_0.0.csv`). You can also supply a list of files to process multiple locations, i.e. `asymp_dir_file=['51.5_0.0.csv', '52.0_0.0.csv']`.
- We currently recommend running OTSO using rigidities from 0.1 GV to 1010 GV, with 200 steps between 0.1 GV and 20 GV, and 60 steps between 20 GV and 1010 GV. Its very possible that other sets of rigidities will work, but this is the configuration we have tested and found to be accurate.
2. **Using Magnetocosmics output files**: If you have Magnetocosmics installed and prefer to feed files from it into AniMAIRE rather than using the internal Magnetocosmics wrappers, you can also used generated asymptotic direction files from it. This requires having Magnetocosmics properly installed and configured on your system, and you can supply the files to AniMAIRE using the same format as with OTSO files.
Once you have your asymptotic direction files, you can use them with AniMAIRE like this:
```python
from AniMAIRE import AniMAIRE
# Run simulation using a precomputed asymptotic directions file
result = AniMAIRE.run_from_spectra(
proton_rigidity_spectrum=lambda x: 2.56*(x**-3.41),
asymp_dir_file='path/to/your/51.5_0.0.csv'
)
```
**Important Notes:**
- When using `asymp_dir_file`, do not supply additional asymptotic direction parameters such as `Kp_index`, `array_of_lats_and_longs`, `date_and_time`, `cache_magnetocosmics_run`, or any extra keyword arguments intended for Magnetocosmics (i.e. `mag_cos_kwargs`), as these will be ignored.
- The asymptotic direction file must be in CSV format with specific column headers. Both OTSO and Magnetocosmics generate compatible files.
- You can also provide a list of files to process multiple locations: `asymp_dir_file=['51.5_0.0.csv', '52.0_0.0.csv']`
Using precomputed asymptotic directions can greatly reduce run times and is particularly useful for repeated analyses or when integrating external asymptotic data.
## Running AniMAIRE with Magnetocosmics (Alternative Method)
If you prefer to run AniMAIRE with direct Magnetocosmics integration, you'll need to have Magnetocosmics installed on your system. **Note that this method is significantly slower than using precomputed files.**
**To use this package with Magnetocosmics you must have it installed, such that magnetocosmics can be run by typing 'magnetocosmics' in the terminal, i.e. typing:**
```bash
magnetocosmics
```
outputs something like the following:
```text
################################
!!! G4Backtrace is activated !!!
################################
**************************************************************
Geant4 version Name: geant4-11-00-patch-02 [MT] (25-May-2022)
Copyright : Geant4 Collaboration
References : NIM A 506 (2003), 250-303
: IEEE-TNS 53 (2006), 270-278
: NIM A 835 (2016), 186-225
WWW : http://geant4.org/
**************************************************************
/h n m 1900.0 1905.0 1910.0 1915.0 1920.0 1925.0 1930.0 1935.0 1940.0 1945.0 1950.0 1955.0 1960.0 1965.0 1970.0 1975.0 1980.0 1985.0 1990.0 1995.0 2000.0 2005.0 2010.0 2015.0 2020.0 SV
mmm1900
Nyear 25
1900
Nyear 25
...
g 8 8
h 8 8
g 9 0
0.0 0 -999
XGSE in GEI (0.193332,-0.900173,-0.39027)
(0.0573796,-0.172205,0.983389)
-19.4809
Selected index20
XGSE in GEI (0.17509,-0.903305,-0.391643)
(0.0590434,-0.175608,0.982688)
-25.9091
Test93
Test97
Test
G4CashKarpRKF45 is called
```
## Usage
After installation, to import the toolkit into a particular Python script, run
```python
from AniMAIRE import AniMAIRE
```
All of the main useful functions are contained within this `AniMAIRE` module, and all other modules contained in this toolkit are primarily intended to be accessed internally (although don't let that stop you from using or editing them for your own purposes if you wish).
The rest of the README file describes how to run AniMAIRE to produce dose rates for different input parameters. You can also look at and run the examples present in the `AniMAIRE_examples.ipynb` notebook, and the advanced examples in the `notebooks_and_data_and_figures_for_paper/GLE71_plots_for_paper.ipynb` notebook to learn and see in practice how AniMAIRE can be used.
## Testing that AniMAIRE is working
**WORK IN PROGRESS - the rest of this README file currently exclusively discusses running using the 'Magnetocosmics run method' of AniMAIRE. The following tests and run examples will therefore only work if you have Magnetocosmics installed. However if you do want to run using inputted asymptotic direction files from OTSO, all you have to do in each of the examples/functions described is add the `asymp_dir_file` argument with a path/list of paths to your outputted asymptotic direction CSVs, and remove all other arguments related to asymptotic directions, as described previously. In the future the examples given here will be updated to better showcase running AniMAIRE like this.**
To test that AniMAIRE works, you can run:
```python
from AniMAIRE import AniMAIRE
import datetime as dt
test_isotropic_dose_rates = AniMAIRE.run_from_spectra(
proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),
Kp_index=3,
date_and_time=dt.datetime(2006, 12, 13, 3, 0),
array_of_lats_and_longs=[[65.0,25.0]],
)
```
in Python. This should produce some dose rates as output to `test_isotropic_dose_rates` in the format (the meaning of each column is explained later on in this README, under the "Simple isotropic runs and plotting" heading):
```text
latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL
0 65.0 25.0 0.0000 0.010434 0.012526 0.010010 0.004431 0.002726 0.001826 2.725682e-16 2.725682e-11
1 65.0 25.0 3.0480 0.101553 0.117294 0.085010 0.051717 0.033506 0.022912 3.350616e-15 3.350616e-10
2 65.0 25.0 6.0960 0.669389 0.736989 0.456343 0.324250 0.210297 0.144131 2.102967e-14 2.102967e-09
3 65.0 25.0 7.6200 1.432404 1.525608 0.966025 0.658130 0.426616 0.292777 4.266156e-14 4.266156e-09
4 65.0 25.0 8.5344 2.147704 2.220632 1.416257 0.950846 0.614894 0.422072 6.148938e-14 6.148938e-09
5 65.0 25.0 9.4488 3.108676 3.124392 2.063826 1.319292 0.854931 0.586036 8.549315e-14 8.549315e-09
6 65.0 25.0 10.3632 4.377677 4.263813 2.692120 1.767081 1.142345 0.782749 1.142345e-13 1.142345e-08
7 65.0 25.0 11.2776 5.993970 5.643631 3.764450 2.292849 1.480059 1.010255 1.480059e-13 1.480059e-08
8 65.0 25.0 12.1920 7.953998 7.262904 5.017846 2.881359 1.850446 1.263386 1.850446e-13 1.850446e-08
9 65.0 25.0 13.1064 10.414874 9.115408 6.247418 3.514676 2.249009 1.532907 2.249009e-13 2.249009e-08
10 65.0 25.0 14.0208 13.242733 11.101641 7.800097 4.184576 2.665499 1.810092 2.665499e-13 2.665499e-08
11 65.0 25.0 14.9352 16.603692 13.430864 9.571582 4.865316 3.082233 2.086676 3.082233e-13 3.082233e-08
12 65.0 25.0 15.8496 20.842479 15.942018 11.573518 5.568722 3.503950 2.361370 3.503950e-13 3.503950e-08
13 65.0 25.0 16.7640 25.482167 18.658393 13.926003 6.254882 3.914514 2.628245 3.914514e-13 3.914514e-08
14 65.0 25.0 17.6784 31.020574 21.767530 16.937656 6.902852 4.295149 2.869582 4.295149e-13 4.295149e-08
15 65.0 25.0 18.5928 37.203113 24.734609 19.638953 7.495669 4.637948 3.081391 4.637948e-13 4.637948e-08
```
### Calculating dose rates at any location in Earth's atmosphere
The primary function for performing a run to calculate dose rates in `AniMAIRE` is the `run_from_spectra` function, which has the format:
```python
def run_from_spectra(
proton_rigidity_spectrum=None,
alpha_rigidity_spectrum=None,
reference_pitch_angle_latitude=None,
reference_pitch_angle_longitude=None,
proton_pitch_angle_distribution=isotropicPitchAngleDistribution(),
alpha_pitch_angle_distribution=isotropicPitchAngleDistribution(),
altitudes_in_kft=[0,10,20] + [i for i in range(25, 61 + 1, 3)],
altitudes_in_km=None,
Kp_index=None,
date_and_time=dt.datetime.now(),
array_of_lats_and_longs=default_array_of_lats_and_longs,
array_of_zeniths_and_azimuths=np.array([[0.0, 0.0]]),
cache_magnetocosmics_run=True,
generate_NM_count_rates=False,
use_default_9_zeniths_azimuths=False,
**mag_cos_kwargs
)
```
`run_from_spectra` performs a run at a single date and time and Kp index to calculate dose rates across Earth's atmosphere based on proton, alpha particle, or proton + alpha particle spectra. **Particle spectra here must be described in units of cm-2 s-1 sr-1 (GV/n)-1, and with respect to rigidity in units of GV**.
Particle spectra and pitch angle distributions can be set as any 'callable' object in Python, i.e., a function, as shown in examples below. At least one particle spectrum must be specified, as well as a Kp index, so this function to execute successfully. For runs designed to simulate dose rates during particular dates and times, the argument `date_and_time` must also be supplied with a Python `datetime` corresponding to the timestamp being investigated (by default, the function assumes that the current date and time should be used).
Note that while this function can optionally take an alpha particle spectrum as an input, it actually interpolates the dose rates due to alpha particles to those of heavier ions too, so outputted dose rates due to an alpha particle spectrum are in fact the combined total of all ions heavier than protons.
Several types of runs can be performed with AniMAIRE; for instance, only vertical asymptotic directions are used to calculate dose rates by default. You can optionally set `use_default_9_zeniths_azimuths` to `True` to use the mean of nine different asymptotic directions to calculate dose rates, as was done by [Cramp et al. (1997)](https://doi.org/10.1029/97JA01947), to calculate dose rates during particularly complex events (note that this means calculations will take approximately nine times longer). You can also manually set your own choice of asymptotic directions for taking the average using the `array_of_zeniths_and_azimuths` variable.
`AniMAIRE` performs runs of the MAGNETOCOSMICS as part of dose rate calculations (using the [AsympDirsCalculator](https://github.com/ssc-maire/AsymptoticDirectionsCalculator) package), and these currently take up by far the majority of `AniMAIRE` runtime - on the order of over half an hour on the developer's computer versus less than 6 minutes for the rest of the program. Therefore if the `cache_magnetocosmics_run` argument is set to `True`, which it is by default, `AniMAIRE` will cache the results of MAGNETOCOSMICS simulations in the directory that `AniMAIRE` is run from in the generated `cachedMagnetocosmicsRunData` and `cacheAsymptoticDirectionOutputs` directories. This significantly speeds up any tasks where users wish to investigate a constant `Kp_index` and `date_and_time`, but wish to vary the spectrum and pitch angle distribution and investigate how dose rates are impacted, as magnetocosmics runs are only performed once.
You can pass settings and variables to `AsympDirsCalculator` through adding additional keyword arguments to `run_from_spectra` with the same names as the arguments given on the [AsympDirsCalculator Github page](https://github.com/ssc-maire/AsymptoticDirectionsCalculator). These settings and variable get assigned to the `**mag_cos_kwargs` object, and passed to `AsympDirsCalculator` by `AniMAIRE`.
### Simple isotropic runs and plotting
A basic run of the `run_from_spectra` function might look like this:
```python
from AniMAIRE import AniMAIRE
import datetime as dt
test_isotropic_dose_rates = AniMAIRE.run_from_spectra(
proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),
Kp_index=3,
date_and_time=dt.datetime(2006, 12, 13, 3, 0),
)
```
in this example, the proton rigidity spectrum is set to be a power law with a normalisation factor of 2.56 cm-2 s-1 sr-1 (GV/n)-1, and a spectral index of 3.41, using the commonly used `lambda` approach to create a function within a single line. Kp index is set to be 3, and the date and time to simulate are set to be 13th of December 2006, 03:00. This function will likely take at least several minutes to run, depending on the speed of the machine and number of cores, and should output a Pandas DataFrame to `test_isotropic_dose_rates`, giving:
```text
latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL
0 -90.0 0.0 0.0000 0.010442 0.012540 0.010010 0.004437 0.002729 0.001828 2.729229e-16 2.729229e-11
1 -90.0 0.0 3.0480 0.101786 0.117658 0.085755 0.051895 0.033617 0.022979 3.361684e-15 3.361684e-10
2 -90.0 0.0 6.0960 0.672702 0.742332 0.457695 0.326731 0.211853 0.145046 2.118530e-14 2.118530e-09
3 -90.0 0.0 7.6200 1.442377 1.541670 0.975436 0.665785 0.431261 0.295516 4.312608e-14 4.312608e-09
4 -90.0 0.0 8.5344 2.165860 2.249419 1.426324 0.964791 0.623291 0.426927 6.232913e-14 6.232913e-09
```
when `test_isotropic_dose_rates` is printed.
The outputted dose rate (or flux) labels represent the following dose rate/flux types:
|label | dose rate/flux type|
|------|--------------------|
|adose| ambient dose equivalent in µSv/hr |
|edose| effective dose in µSv/hr |
|dosee| dose equivalent in µSv/hr |
|tn1| >1 MeV neutron flux, in n/cm2/s |
|tn2| >10 MeV neutron flux, in n/cm2/s |
|tn3| >60 MeV neutron flux, in n/cm2/s |
|SEU| single event upset rate for an SRAM device in upsets/second/bit |
|SEL| single event latch-up rate for an SRAM device in latch-ups/second/device |
These dose rates are produced by default at every latitude and longitude corresponding to 5 by 5 degree intervals across Earth's surface, and for altitudes of 0 kilofeet, 10 kilofeet, 20 kilofeet and between 25 kilofeet and 61 kilofeet at intervals of 3 kilofeet. This can be altered using the `altitudes_in_kft`, `altitudes_in_km` and `array_of_lats_and_longs`.
Any particular altitudes the user wants to use can be supplied to `altitudes_in_kft` or `altitudes_in_km` as a `list` or numpy array.
If you want to perform calculations only at a specific set of latitudes and longitudes you should use the `array_of_lats_and_longs` argument, supplying it as a 2 dimensional `list` or numpy array, where the first column refers to latitudes and the second column refers to longitudes. All longitudes in this case should be specified in terms of longitude east (i.e. 0.00 degrees - 359.99 degrees). **Using the `array_of_lats_and_longs` argument significantly speeds up the running of `AniMAIRE` if you're only interested in a small number of coordinates, so its use is highly recommended in those situations.**
There are many ways you could plot this data. Several example functions,`plot_dose_map` and `create_single_dose_map_plotly`, have been supplied in `AniMAIRE` that uses matplotlib or plotly to plot the dose rates across Earth (i.e. as a function of latitude and longitude) at a given altitude. Both of these functions are available in the `dose_plotting` submodule supplied with AniMAIRE. Their specifications are the following:
```python
def plot_dose_map(map_to_plot,
plot_title=None,
plot_contours=True,
levels=3,
**kwargs)
```
for matplotlib plots, where map_to_plot is the Pandas DataFrame outputted by a run of `AniMAIRE`, with only one altitude selected. `plot_contours` can be switched on or off to control whether contours are added to the plot, and `levels` can be used to specify to number of contours and/or dose rates for the contours to correspond to. `hue_range` can also be supplied with a 2-value tuple to specify the limits of the colorbar to be plotted with the plot.
To generate a plotly plot, you can run
```python
def create_single_dose_map_plotly(DF_to_use,
selected_altitude_in_km)
```
where `DF_to_use` is the Pandas DataFrame outputted by a run of `AniMAIRE` and altitude is one of the altitudes in kilometers supplied to/outputted by the run.
To use the matplotlib function to create a map of the isotropic situation as given as an example above, you could run
```python
from AniMAIRE import dose_plotting
import matplotlib.pyplot as plt
dose_plotting.plot_dose_map(test_isotropic_dose_rates.query("`altitude (km)` == 12.1920"),
hue_range=(0,9))
plt.show()
```
which should plot the following figure as a matplotlib plot:
and assign the plot to the `isotropic_dose_rate_map` variable for the user to use as they wish.
### Anisotropic runs
`run_from_spectra` defaults to an isotropic spectrum if no pitch angle distribution is supplied for either protons or alpha particles by the user.
To run an anisotropic spectrum, differential pitch angle distributions must be supplied to the `proton_pitch_angle_distribution` and/or `alpha_pitch_angle_distribution` arguments in `run_from_spectra` along with a reference location specified in terms of latitude and longitude in the `reference_pitch_angle_latitude` and `reference_pitch_angle_longitude` arguments respectively. The pitch angle distributions must be supplied as 2 dimensional functions, where the first argument is the pitch angle, and the second argument is particle rigidity (in many cases the pitch angle distribution might not depend on rigidity, but for programmatic reasons the function must at least take in rigidity as an argument although it does not need to have a dependence on it). The pitch angle here must be specified in units of **radians**.
`reference_pitch_angle_latitude` and `reference_pitch_angle_longitude` are the reference latitude and longitude in GEO coordinates representing a pitch angle of 0 in the supplied pitch angle distribution used. `AniMAIRE` currently makes the assumption that incoming particle distributions are cylindrically symmetric about this reference direction, and therefore that only the pitch angle with respect to this latitude and longitude are required to calculate dose rates anisotropically across Earth. Incoming solar particle events are frequently oriented near to the direction of the Interplanetary Magnetic Field (IMF), so you could specify pitch angles relative to the IMF here, and use the latitude and longitude of the IMF as the reference latitude and longitude.
The pitch angle distributions and rigidity spectrum must be specified in units normalised such that the product of the pitch angle distribution and rigidity spectrum multiplied together is in units of **cm-2 s-1 sr-1 (GV/n)-1**.
The pitch angle distributions can be specified using the Python `lambda` as with the rigidity spectra, but with 2 dimensions rather than 1. For example, to specify a Gaussian pitch angle distribution you could use:
```python
import numpy as np
sigma = np.sqrt(0.19)
test_pitch_angle_dist_function = lambda pitch_angle,rigidity:np.exp(-(pitch_angle**2)/(sigma**2))
```
where `sigma` here has arbitrarily been chosen to be the square root of 0.19 for example purposes.
here `pitch_angle_dist_function` would be a viable input as a pitch angle distribution to `run_from_spectra`. While the function itself does not depend on `rigidity`, `rigidity` is specified as the second argument of the function nonetheless, as required for calculations to work.
An example of using this might be:
```python
import numpy as np
from AniMAIRE import AniMAIRE
import datetime as dt
sigma = np.sqrt(0.19)
pitch_angle_reference_latitude = -17.0
pitch_angle_reference_longitude = 148.0
test_pitch_angle_dist_function = lambda pitch_angle,rigidity:np.exp(-(pitch_angle**2)/(sigma**2))
test_anisotropic_dose_rates = AniMAIRE.run_from_spectra(
proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),
proton_pitch_angle_distribution=test_pitch_angle_dist_function,
reference_pitch_angle_latitude=pitch_angle_reference_latitude,reference_pitch_angle_longitude=pitch_angle_reference_longitude,
Kp_index=3,
date_and_time=dt.datetime(2006, 12, 13, 3, 0),
)
```
when run this should output a Pandas DataFrame to `test_anisotropic_dose_rates` with the same general output format as given in the previously described isotropic dose rates case.
In this case printing `test_anisotropic_dose_rates` should output:
```text
latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL
0 -90.0 0.0 0.0000 1.976895e-07 2.027961e-07 3.222401e-07 1.286575e-08 7.877480e-09 5.401425e-09 7.877480e-22 7.877480e-17
1 -90.0 0.0 3.0480 4.838923e-07 4.869626e-07 7.032983e-07 7.429541e-08 4.866265e-08 3.410940e-08 4.866265e-21 4.866265e-16
2 -90.0 0.0 6.0960 1.453834e-06 1.411544e-06 2.045308e-06 2.472576e-07 1.611648e-07 1.136527e-07 1.611648e-20 1.611648e-15
3 -90.0 0.0 7.6200 2.352658e-06 2.382057e-06 3.304989e-06 3.720997e-07 2.420436e-07 1.708843e-07 2.420436e-20 2.420436e-15
4 -90.0 0.0 8.5344 2.970462e-06 2.791970e-06 4.201789e-06 4.473736e-07 2.919136e-07 2.063902e-07 2.919136e-20 2.919136e-15
... ... ... ... ... ... ... ... ... ... ... ...
42619 90.0 355.0 14.9352 1.062397e-06 7.975138e-07 5.902218e-07 2.766678e-07 1.764588e-07 1.216189e-07 1.764588e-20 1.764588e-15
42620 90.0 355.0 15.8496 1.289216e-06 9.183397e-07 6.964574e-07 3.063998e-07 1.945207e-07 1.338582e-07 1.945207e-20 1.945207e-15
42621 90.0 355.0 16.7640 1.525359e-06 1.040969e-06 8.062018e-07 3.339381e-07 2.112220e-07 1.452375e-07 2.112220e-20 2.112220e-15
42622 90.0 355.0 17.6784 1.777447e-06 1.163693e-06 9.297615e-07 3.568426e-07 2.248452e-07 1.543556e-07 2.248452e-20 2.248452e-15
42623 90.0 355.0 18.5928 2.036052e-06 1.275021e-06 1.040287e-06 3.755276e-07 2.357292e-07 1.614028e-07 2.357292e-20 2.357292e-15
```
which will produce the following plot when
```python
from AniMAIRE import dose_plotting
import matplotlib.pyplot as plt
dose_plotting.plot_dose_map(test_anisotropic_dose_rates.query("`altitude (km)` == 12.1920"),
hue_range=(0,9))
plt.show()
```
is run, as was described previously in this README for isotropic plotting:
you can also produce similar plotly plots if you prefer plotly to matplotlib using:
```python
from AniMAIRE import dose_plotting
anisotropic_dose_rate_map = dose_plotting.create_single_dose_map_plotly(test_anisotropic_dose_rates,
selected_altitude_in_km = 12.1920)
```
which generates the following plot:
### Functions for running `AniMAIRE` for specific situations and for a past timestamp
In addition to the quite general `run_from_spectra` function, `AniMAIRE` currently contains several functions for running calculations for specific types of spectra and situations, to make it easier for users to perform runs without having to determine and feed in spectra to `run_from_spectra` themselves.
The `run_from_DLR_cosmic_ray_power_law` function allows users to run full atmospheric dose rate calculations (for cosmic ray only/'quiet' time periods only) from just a date and time, or alternatively from just a single OULU count rate, or just a value of 'W parameter', as well as Kp index. This function utilises the [CosRayModifiedISO package](https://github.com/ssc-maire/CosRayModifiedISO) to determine the spectra due to protons and alpha particles during cosmic ray only time periods, and then runs `run_from_spectra` using both of those spectra under isotropic conditions. The specifications of `run_from_DLR_cosmic_ray_power_law` are:
```python
def run_from_DLR_cosmic_ray_model(OULU_count_rate_in_seconds=None,
W_parameter=None,
Kp_index=None,
date_and_time=None,
**kwargs)
```
`**kwargs` here can be used to supply any arguments you wish to `run_from_spectra` as specified previously, such as the list of altitudes and list of coordinates to perform calculations for. Details on what `OULU_count_rate_in_seconds` and `W_parameter` mean can be found at <https://github.com/ssc-maire/CosRayModifiedISO> . If either `OULU_count_rate_in_seconds` or `W_parameter` are used, only one of them should be specified. Otherwise, `AniMAIRE` will determined their values using the `date_and_time` parameter supplied.
In addition to running from the DLR-ISO isotropic cosmic ray model, you can also run `AniMAIRE` from a combined power law rigidity spectrum and Gaussian pitch angle distribution. This can be done using the `run_from_power_law_gaussian_distribution` function:
```python
def run_from_power_law_gaussian_distribution(J0, gamma, deltaGamma, sigma,
reference_pitch_angle_latitude, reference_pitch_angle_longitude,
Kp_index,date_and_time,
**kwargs)
```
Here `J0`, `gamma`, `deltaGamma`, `sigma`, `reference_pitch_angle_latitude`, `reference_pitch_angle_longitude` are all defined as specified in the format of papers like [Mishev, A., Usoskin, I. Analysis of the Ground-Level Enhancements on 14 July 2000 and 13 December 2006 Using Neutron Monitor Data. Sol Phys 291, 1225–1239 (2016). https://doi.org/10.1007/s11207-016-0877-2](https://link.springer.com/article/10.1007/s11207-016-0877-2).
## References
- Davis, C. S. W. et al. (2024). *AniMAIRE-A New Openly Available Tool for Calculating Atmospheric Ionising Radiation Dose Rates and Single Event Effects During Anisotropic Conditions*. [https://doi.org/10.1029/2024SW003985](https://doi.org/10.1029/2024SW003985)
- Larsen, N. et al.(2024). *A New Open-Source Geomagnetosphere Propagation Tool (OTSO) and Its Applications*. [https://doi.org/10.1029/2022JA031061](https://doi.org/10.1029/2022JA031061)
- Mishev, A. & Usoskin, I. (2016). Analysis of the Ground-Level Enhancements on 14 July 2000 and 13 December 2006 Using Neutron Monitor Data. *Solar Physics, 291*, 1225–1239. [https://doi.org/10.1007/s11207-016-0877-2](https://doi.org/10.1007/s11207-016-0877-2)
- Matthiä, D. et al. (2012). *A ready-to-use galactic cosmic ray model*, [https://doi.org/10.1016/j.asr.2012.09.022](https://doi.org/10.1016/j.asr.2012.09.022)
Raw data
{
"_id": null,
"home_page": "https://github.com/ssc-maire/AniMAIRE-public",
"name": "AniMAIRE",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "anisotropic MAIRE+ atmospheric ionizing radiation dose rates cosmic rays ground level enhancements GLEs protons alpha particles neutrons effective ambient equivalent aircraft aviation Earth solar system sun space magnetic field",
"author": "Space Environment and Protection Group, University of Surrey",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/01/d7/bbe65dec626ed80acddd5bce8a652f3eef4bd24f00f6129975cd84afba9b/animaire-1.2.4.tar.gz",
"platform": null,
"description": "# AniMAIRE\n\n\n\nA Python toolkit for calculating dose rates and aircraft electronics upset rates in Earth's atmosphere based on any incoming proton or alpha particle spectra, with any pitch angle distribution.\n\n**N.B. Currently this tool has only been tested on Linux-based machines (not on Windows yet) and requires that you either have access to output asymptotic directions generated by [OTSO](https://github.com/NLarsen15/OTSO) or that [MAGNETOCOSMICS](http://cosray.unibe.ch/~laurent/magnetocosmics/) is installed on your machine.**\n\nIf you use this software for scientific research, please reference AniMAIRE according to the appropriate journal publication rules.\n\nA scientific paper about this software is currently in production, and we recently published a preprint, [which can be found here](https://www.researchgate.net/publication/380403797_AniMAIRE_-_A_New_Openly_Available_Tool_for_Calculating_Atmospheric_Ionising_Radiation_Dose_Rates_and_Single_Event_Effects_During_Anisotropic_Conditions), about AniMAIRE and some interesting scientific findings we've made using our work with AniMAIRE so far.\n\nYou can use AniMAIRE to produce dose rate data and maps throughout large space weather events and plot them like this:\n\n<!-- Original inline HTML code:\n// <img src=\"https://raw.githubusercontent.com/ssc-maire/AniMAIRE-public/main/Ani_GLE_only_timestamp1_with_legend.svg\" width=\"350\" alt=\"Dose rate map for a GLE\"/> <img src=\"https://raw.githubusercontent.com/ssc-maire/AniMAIRE-public/main/Ani_GLE_only_timestamp5_with_legend.svg\" width=\"350\" alt=\"Dose rate map for the same GLE at another timestamp\"/>\n-->\n\n\n\n<!--  |  -->\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Running AniMAIRE with Precomputed Asymptotic Direction Files (Recommended method if you don't have access to Magnetocosmics)](#running-animaire-with-precomputed-asymptotic-direction-files-recommended-method-if-you-dont-have-access-to-magnetocosmics)\n- [Running AniMAIRE with Magnetocosmics (Alternative Method)](#running-animaire-with-magnetocosmics-alternative-method)\n- [Usage](#usage)\n- [Testing that AniMAIRE is working](#testing-that-animaire-is-working)\n- [Calculating dose rates at any location in Earth's atmosphere](#calculating-dose-rates-at-any-location-in-earths-atmosphere)\n- [Simple isotropic runs and plotting](#simple-isotropic-runs-and-plotting)\n- [Anisotropic runs](#anisotropic-runs)\n- [Functions for running AniMAIRE for specific situations and for a past timestamp](#functions-for-running-animaire-for-specific-situations-and-for-a-past-timestamp)\n\n## Installation\n\nTo install this toolkit using the common pip Python method, run\n\n```bash\npip install AniMAIRE\n```\n\nOtherwise, to install this toolkit from this Github repository, first clone this repository to your local system, and then from the cloned respository, run\n\n```bash\nsudo pip3 install .\n```\n\nin the cloned directory.\n\nNote that there are quite a few sizeable data files within some of the dependencies for this package that get copied during installation (on the order of about several hundred megabytes in total) so installation may take a couple of minutes.\n\n## Running AniMAIRE with Precomputed Asymptotic Direction Files (Recommended method if you don't have access to Magnetocosmics)\n\nThe recommended way to run AniMAIRE is to use precomputed asymptotic direction files. This approach doesn't require having Magnetocosmics installed on your system.\n\n1. **Using OTSO output files (Recommended)**: [OTSO](https://github.com/NLarsen15/OTSO) is an open-source tool specifically designed for calculating asymptotic directions. It's more modern, easier to install, and community-oriented. To generate asymptotic direction files with OTSO:\n - Install OTSO following the instructions at their repository\n - Use OTSO to generate CSV files containing asymptotic directions\n - The files should follow the naming convention: `latitude_longitude.csv` (e.g., `51.5_0.0.csv`). You can also supply a list of files to process multiple locations, i.e. `asymp_dir_file=['51.5_0.0.csv', '52.0_0.0.csv']`.\n - We currently recommend running OTSO using rigidities from 0.1 GV to 1010 GV, with 200 steps between 0.1 GV and 20 GV, and 60 steps between 20 GV and 1010 GV. Its very possible that other sets of rigidities will work, but this is the configuration we have tested and found to be accurate.\n\n2. **Using Magnetocosmics output files**: If you have Magnetocosmics installed and prefer to feed files from it into AniMAIRE rather than using the internal Magnetocosmics wrappers, you can also used generated asymptotic direction files from it. This requires having Magnetocosmics properly installed and configured on your system, and you can supply the files to AniMAIRE using the same format as with OTSO files.\n\nOnce you have your asymptotic direction files, you can use them with AniMAIRE like this:\n\n```python\nfrom AniMAIRE import AniMAIRE\n\n# Run simulation using a precomputed asymptotic directions file\nresult = AniMAIRE.run_from_spectra(\n proton_rigidity_spectrum=lambda x: 2.56*(x**-3.41),\n asymp_dir_file='path/to/your/51.5_0.0.csv'\n)\n```\n\n**Important Notes:**\n\n- When using `asymp_dir_file`, do not supply additional asymptotic direction parameters such as `Kp_index`, `array_of_lats_and_longs`, `date_and_time`, `cache_magnetocosmics_run`, or any extra keyword arguments intended for Magnetocosmics (i.e. `mag_cos_kwargs`), as these will be ignored.\n- The asymptotic direction file must be in CSV format with specific column headers. Both OTSO and Magnetocosmics generate compatible files.\n- You can also provide a list of files to process multiple locations: `asymp_dir_file=['51.5_0.0.csv', '52.0_0.0.csv']`\n\nUsing precomputed asymptotic directions can greatly reduce run times and is particularly useful for repeated analyses or when integrating external asymptotic data.\n\n## Running AniMAIRE with Magnetocosmics (Alternative Method)\n\nIf you prefer to run AniMAIRE with direct Magnetocosmics integration, you'll need to have Magnetocosmics installed on your system. **Note that this method is significantly slower than using precomputed files.**\n\n**To use this package with Magnetocosmics you must have it installed, such that magnetocosmics can be run by typing 'magnetocosmics' in the terminal, i.e. typing:**\n\n```bash\nmagnetocosmics\n```\n\noutputs something like the following:\n\n```text\n\n\n ################################\n !!! G4Backtrace is activated !!!\n ################################\n\n\n**************************************************************\n Geant4 version Name: geant4-11-00-patch-02 [MT] (25-May-2022)\n Copyright : Geant4 Collaboration\n References : NIM A 506 (2003), 250-303\n : IEEE-TNS 53 (2006), 270-278\n : NIM A 835 (2016), 186-225\n WWW : http://geant4.org/\n**************************************************************\n\n/h n m 1900.0 1905.0 1910.0 1915.0 1920.0 1925.0 1930.0 1935.0 1940.0 1945.0 1950.0 1955.0 1960.0 1965.0 1970.0 1975.0 1980.0 1985.0 1990.0 1995.0 2000.0 2005.0 2010.0 2015.0 2020.0 SV\nmmm1900\nNyear 25\n1900\nNyear 25\n\n...\n\ng 8 8\nh 8 8\ng 9 0\n0.0 0 -999\nXGSE in GEI (0.193332,-0.900173,-0.39027)\n(0.0573796,-0.172205,0.983389)\n-19.4809\nSelected index20\nXGSE in GEI (0.17509,-0.903305,-0.391643)\n(0.0590434,-0.175608,0.982688)\n-25.9091\nTest93\nTest97\nTest\nG4CashKarpRKF45 is called\n```\n\n## Usage\n\nAfter installation, to import the toolkit into a particular Python script, run\n\n```python\nfrom AniMAIRE import AniMAIRE\n```\n\nAll of the main useful functions are contained within this `AniMAIRE` module, and all other modules contained in this toolkit are primarily intended to be accessed internally (although don't let that stop you from using or editing them for your own purposes if you wish).\n\nThe rest of the README file describes how to run AniMAIRE to produce dose rates for different input parameters. You can also look at and run the examples present in the `AniMAIRE_examples.ipynb` notebook, and the advanced examples in the `notebooks_and_data_and_figures_for_paper/GLE71_plots_for_paper.ipynb` notebook to learn and see in practice how AniMAIRE can be used.\n\n## Testing that AniMAIRE is working\n\n**WORK IN PROGRESS - the rest of this README file currently exclusively discusses running using the 'Magnetocosmics run method' of AniMAIRE. The following tests and run examples will therefore only work if you have Magnetocosmics installed. However if you do want to run using inputted asymptotic direction files from OTSO, all you have to do in each of the examples/functions described is add the `asymp_dir_file` argument with a path/list of paths to your outputted asymptotic direction CSVs, and remove all other arguments related to asymptotic directions, as described previously. In the future the examples given here will be updated to better showcase running AniMAIRE like this.**\n\nTo test that AniMAIRE works, you can run:\n\n```python\nfrom AniMAIRE import AniMAIRE\nimport datetime as dt\n\ntest_isotropic_dose_rates = AniMAIRE.run_from_spectra(\n proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),\n Kp_index=3,\n date_and_time=dt.datetime(2006, 12, 13, 3, 0),\n array_of_lats_and_longs=[[65.0,25.0]],\n)\n```\n\nin Python. This should produce some dose rates as output to `test_isotropic_dose_rates` in the format (the meaning of each column is explained later on in this README, under the \"Simple isotropic runs and plotting\" heading):\n\n```text\n latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL\n0 65.0 25.0 0.0000 0.010434 0.012526 0.010010 0.004431 0.002726 0.001826 2.725682e-16 2.725682e-11\n1 65.0 25.0 3.0480 0.101553 0.117294 0.085010 0.051717 0.033506 0.022912 3.350616e-15 3.350616e-10\n2 65.0 25.0 6.0960 0.669389 0.736989 0.456343 0.324250 0.210297 0.144131 2.102967e-14 2.102967e-09\n3 65.0 25.0 7.6200 1.432404 1.525608 0.966025 0.658130 0.426616 0.292777 4.266156e-14 4.266156e-09\n4 65.0 25.0 8.5344 2.147704 2.220632 1.416257 0.950846 0.614894 0.422072 6.148938e-14 6.148938e-09\n5 65.0 25.0 9.4488 3.108676 3.124392 2.063826 1.319292 0.854931 0.586036 8.549315e-14 8.549315e-09\n6 65.0 25.0 10.3632 4.377677 4.263813 2.692120 1.767081 1.142345 0.782749 1.142345e-13 1.142345e-08\n7 65.0 25.0 11.2776 5.993970 5.643631 3.764450 2.292849 1.480059 1.010255 1.480059e-13 1.480059e-08\n8 65.0 25.0 12.1920 7.953998 7.262904 5.017846 2.881359 1.850446 1.263386 1.850446e-13 1.850446e-08\n9 65.0 25.0 13.1064 10.414874 9.115408 6.247418 3.514676 2.249009 1.532907 2.249009e-13 2.249009e-08\n10 65.0 25.0 14.0208 13.242733 11.101641 7.800097 4.184576 2.665499 1.810092 2.665499e-13 2.665499e-08\n11 65.0 25.0 14.9352 16.603692 13.430864 9.571582 4.865316 3.082233 2.086676 3.082233e-13 3.082233e-08\n12 65.0 25.0 15.8496 20.842479 15.942018 11.573518 5.568722 3.503950 2.361370 3.503950e-13 3.503950e-08\n13 65.0 25.0 16.7640 25.482167 18.658393 13.926003 6.254882 3.914514 2.628245 3.914514e-13 3.914514e-08\n14 65.0 25.0 17.6784 31.020574 21.767530 16.937656 6.902852 4.295149 2.869582 4.295149e-13 4.295149e-08\n15 65.0 25.0 18.5928 37.203113 24.734609 19.638953 7.495669 4.637948 3.081391 4.637948e-13 4.637948e-08\n```\n\n### Calculating dose rates at any location in Earth's atmosphere\n\nThe primary function for performing a run to calculate dose rates in `AniMAIRE` is the `run_from_spectra` function, which has the format:\n\n```python\ndef run_from_spectra(\n proton_rigidity_spectrum=None,\n alpha_rigidity_spectrum=None,\n reference_pitch_angle_latitude=None,\n reference_pitch_angle_longitude=None,\n proton_pitch_angle_distribution=isotropicPitchAngleDistribution(),\n alpha_pitch_angle_distribution=isotropicPitchAngleDistribution(),\n altitudes_in_kft=[0,10,20] + [i for i in range(25, 61 + 1, 3)],\n altitudes_in_km=None,\n Kp_index=None,\n date_and_time=dt.datetime.now(),\n array_of_lats_and_longs=default_array_of_lats_and_longs,\n array_of_zeniths_and_azimuths=np.array([[0.0, 0.0]]),\n cache_magnetocosmics_run=True,\n generate_NM_count_rates=False,\n use_default_9_zeniths_azimuths=False,\n **mag_cos_kwargs\n)\n```\n\n`run_from_spectra` performs a run at a single date and time and Kp index to calculate dose rates across Earth's atmosphere based on proton, alpha particle, or proton + alpha particle spectra. **Particle spectra here must be described in units of cm-2 s-1 sr-1 (GV/n)-1, and with respect to rigidity in units of GV**.\n\nParticle spectra and pitch angle distributions can be set as any 'callable' object in Python, i.e., a function, as shown in examples below. At least one particle spectrum must be specified, as well as a Kp index, so this function to execute successfully. For runs designed to simulate dose rates during particular dates and times, the argument `date_and_time` must also be supplied with a Python `datetime` corresponding to the timestamp being investigated (by default, the function assumes that the current date and time should be used).\n\nNote that while this function can optionally take an alpha particle spectrum as an input, it actually interpolates the dose rates due to alpha particles to those of heavier ions too, so outputted dose rates due to an alpha particle spectrum are in fact the combined total of all ions heavier than protons.\n\nSeveral types of runs can be performed with AniMAIRE; for instance, only vertical asymptotic directions are used to calculate dose rates by default. You can optionally set `use_default_9_zeniths_azimuths` to `True` to use the mean of nine different asymptotic directions to calculate dose rates, as was done by [Cramp et al. (1997)](https://doi.org/10.1029/97JA01947), to calculate dose rates during particularly complex events (note that this means calculations will take approximately nine times longer). You can also manually set your own choice of asymptotic directions for taking the average using the `array_of_zeniths_and_azimuths` variable.\n\n`AniMAIRE` performs runs of the MAGNETOCOSMICS as part of dose rate calculations (using the [AsympDirsCalculator](https://github.com/ssc-maire/AsymptoticDirectionsCalculator) package), and these currently take up by far the majority of `AniMAIRE` runtime - on the order of over half an hour on the developer's computer versus less than 6 minutes for the rest of the program. Therefore if the `cache_magnetocosmics_run` argument is set to `True`, which it is by default, `AniMAIRE` will cache the results of MAGNETOCOSMICS simulations in the directory that `AniMAIRE` is run from in the generated `cachedMagnetocosmicsRunData` and `cacheAsymptoticDirectionOutputs` directories. This significantly speeds up any tasks where users wish to investigate a constant `Kp_index` and `date_and_time`, but wish to vary the spectrum and pitch angle distribution and investigate how dose rates are impacted, as magnetocosmics runs are only performed once.\n\nYou can pass settings and variables to `AsympDirsCalculator` through adding additional keyword arguments to `run_from_spectra` with the same names as the arguments given on the [AsympDirsCalculator Github page](https://github.com/ssc-maire/AsymptoticDirectionsCalculator). These settings and variable get assigned to the `**mag_cos_kwargs` object, and passed to `AsympDirsCalculator` by `AniMAIRE`.\n\n### Simple isotropic runs and plotting\n\nA basic run of the `run_from_spectra` function might look like this:\n\n```python\nfrom AniMAIRE import AniMAIRE\nimport datetime as dt\n\ntest_isotropic_dose_rates = AniMAIRE.run_from_spectra(\n proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),\n Kp_index=3,\n date_and_time=dt.datetime(2006, 12, 13, 3, 0),\n)\n```\n\nin this example, the proton rigidity spectrum is set to be a power law with a normalisation factor of 2.56 cm-2 s-1 sr-1 (GV/n)-1, and a spectral index of 3.41, using the commonly used `lambda` approach to create a function within a single line. Kp index is set to be 3, and the date and time to simulate are set to be 13th of December 2006, 03:00. This function will likely take at least several minutes to run, depending on the speed of the machine and number of cores, and should output a Pandas DataFrame to `test_isotropic_dose_rates`, giving:\n\n```text\n latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL\n0 -90.0 0.0 0.0000 0.010442 0.012540 0.010010 0.004437 0.002729 0.001828 2.729229e-16 2.729229e-11\n1 -90.0 0.0 3.0480 0.101786 0.117658 0.085755 0.051895 0.033617 0.022979 3.361684e-15 3.361684e-10\n2 -90.0 0.0 6.0960 0.672702 0.742332 0.457695 0.326731 0.211853 0.145046 2.118530e-14 2.118530e-09\n3 -90.0 0.0 7.6200 1.442377 1.541670 0.975436 0.665785 0.431261 0.295516 4.312608e-14 4.312608e-09\n4 -90.0 0.0 8.5344 2.165860 2.249419 1.426324 0.964791 0.623291 0.426927 6.232913e-14 6.232913e-09\n```\n\nwhen `test_isotropic_dose_rates` is printed.\n\nThe outputted dose rate (or flux) labels represent the following dose rate/flux types:\n\n|label | dose rate/flux type|\n|------|--------------------|\n|adose| ambient dose equivalent in \u00b5Sv/hr |\n|edose| effective dose in \u00b5Sv/hr |\n|dosee| dose equivalent in \u00b5Sv/hr |\n|tn1| >1 MeV neutron flux, in n/cm2/s |\n|tn2| >10 MeV neutron flux, in n/cm2/s |\n|tn3| >60 MeV neutron flux, in n/cm2/s |\n|SEU| single event upset rate for an SRAM device in upsets/second/bit |\n|SEL| single event latch-up rate for an SRAM device in latch-ups/second/device |\n\nThese dose rates are produced by default at every latitude and longitude corresponding to 5 by 5 degree intervals across Earth's surface, and for altitudes of 0 kilofeet, 10 kilofeet, 20 kilofeet and between 25 kilofeet and 61 kilofeet at intervals of 3 kilofeet. This can be altered using the `altitudes_in_kft`, `altitudes_in_km` and `array_of_lats_and_longs`.\n\nAny particular altitudes the user wants to use can be supplied to `altitudes_in_kft` or `altitudes_in_km` as a `list` or numpy array.\n\nIf you want to perform calculations only at a specific set of latitudes and longitudes you should use the `array_of_lats_and_longs` argument, supplying it as a 2 dimensional `list` or numpy array, where the first column refers to latitudes and the second column refers to longitudes. All longitudes in this case should be specified in terms of longitude east (i.e. 0.00 degrees - 359.99 degrees). **Using the `array_of_lats_and_longs` argument significantly speeds up the running of `AniMAIRE` if you're only interested in a small number of coordinates, so its use is highly recommended in those situations.**\n\nThere are many ways you could plot this data. Several example functions,`plot_dose_map` and `create_single_dose_map_plotly`, have been supplied in `AniMAIRE` that uses matplotlib or plotly to plot the dose rates across Earth (i.e. as a function of latitude and longitude) at a given altitude. Both of these functions are available in the `dose_plotting` submodule supplied with AniMAIRE. Their specifications are the following:\n\n```python\ndef plot_dose_map(map_to_plot,\n plot_title=None,\n plot_contours=True,\n levels=3,\n **kwargs)\n```\n\nfor matplotlib plots, where map_to_plot is the Pandas DataFrame outputted by a run of `AniMAIRE`, with only one altitude selected. `plot_contours` can be switched on or off to control whether contours are added to the plot, and `levels` can be used to specify to number of contours and/or dose rates for the contours to correspond to. `hue_range` can also be supplied with a 2-value tuple to specify the limits of the colorbar to be plotted with the plot.\n\nTo generate a plotly plot, you can run\n\n```python\ndef create_single_dose_map_plotly(DF_to_use,\n selected_altitude_in_km)\n```\n\nwhere `DF_to_use` is the Pandas DataFrame outputted by a run of `AniMAIRE` and altitude is one of the altitudes in kilometers supplied to/outputted by the run.\n\nTo use the matplotlib function to create a map of the isotropic situation as given as an example above, you could run\n\n```python\nfrom AniMAIRE import dose_plotting\nimport matplotlib.pyplot as plt\n\ndose_plotting.plot_dose_map(test_isotropic_dose_rates.query(\"`altitude (km)` == 12.1920\"),\n hue_range=(0,9))\n\nplt.show()\n```\n\nwhich should plot the following figure as a matplotlib plot:\n\n\nand assign the plot to the `isotropic_dose_rate_map` variable for the user to use as they wish.\n\n### Anisotropic runs\n\n`run_from_spectra` defaults to an isotropic spectrum if no pitch angle distribution is supplied for either protons or alpha particles by the user. \n\nTo run an anisotropic spectrum, differential pitch angle distributions must be supplied to the `proton_pitch_angle_distribution` and/or `alpha_pitch_angle_distribution` arguments in `run_from_spectra` along with a reference location specified in terms of latitude and longitude in the `reference_pitch_angle_latitude` and `reference_pitch_angle_longitude` arguments respectively. The pitch angle distributions must be supplied as 2 dimensional functions, where the first argument is the pitch angle, and the second argument is particle rigidity (in many cases the pitch angle distribution might not depend on rigidity, but for programmatic reasons the function must at least take in rigidity as an argument although it does not need to have a dependence on it). The pitch angle here must be specified in units of **radians**.\n\n`reference_pitch_angle_latitude` and `reference_pitch_angle_longitude` are the reference latitude and longitude in GEO coordinates representing a pitch angle of 0 in the supplied pitch angle distribution used. `AniMAIRE` currently makes the assumption that incoming particle distributions are cylindrically symmetric about this reference direction, and therefore that only the pitch angle with respect to this latitude and longitude are required to calculate dose rates anisotropically across Earth. Incoming solar particle events are frequently oriented near to the direction of the Interplanetary Magnetic Field (IMF), so you could specify pitch angles relative to the IMF here, and use the latitude and longitude of the IMF as the reference latitude and longitude.\n\nThe pitch angle distributions and rigidity spectrum must be specified in units normalised such that the product of the pitch angle distribution and rigidity spectrum multiplied together is in units of **cm-2 s-1 sr-1 (GV/n)-1**.\n\nThe pitch angle distributions can be specified using the Python `lambda` as with the rigidity spectra, but with 2 dimensions rather than 1. For example, to specify a Gaussian pitch angle distribution you could use:\n\n```python\nimport numpy as np\n\nsigma = np.sqrt(0.19)\n\ntest_pitch_angle_dist_function = lambda pitch_angle,rigidity:np.exp(-(pitch_angle**2)/(sigma**2))\n```\n\nwhere `sigma` here has arbitrarily been chosen to be the square root of 0.19 for example purposes.\n\nhere `pitch_angle_dist_function` would be a viable input as a pitch angle distribution to `run_from_spectra`. While the function itself does not depend on `rigidity`, `rigidity` is specified as the second argument of the function nonetheless, as required for calculations to work.\n\nAn example of using this might be:\n\n```python\nimport numpy as np\nfrom AniMAIRE import AniMAIRE\nimport datetime as dt\n\nsigma = np.sqrt(0.19)\npitch_angle_reference_latitude = -17.0\npitch_angle_reference_longitude = 148.0\n\ntest_pitch_angle_dist_function = lambda pitch_angle,rigidity:np.exp(-(pitch_angle**2)/(sigma**2))\n\ntest_anisotropic_dose_rates = AniMAIRE.run_from_spectra(\n proton_rigidity_spectrum=lambda x:2.56*(x**-3.41),\n proton_pitch_angle_distribution=test_pitch_angle_dist_function,\n reference_pitch_angle_latitude=pitch_angle_reference_latitude,reference_pitch_angle_longitude=pitch_angle_reference_longitude,\n Kp_index=3,\n date_and_time=dt.datetime(2006, 12, 13, 3, 0),\n)\n```\n\nwhen run this should output a Pandas DataFrame to `test_anisotropic_dose_rates` with the same general output format as given in the previously described isotropic dose rates case.\n\nIn this case printing `test_anisotropic_dose_rates` should output:\n\n```text\n latitude longitude altitude (km) edose adose dosee tn1 tn2 tn3 SEU SEL\n0 -90.0 0.0 0.0000 1.976895e-07 2.027961e-07 3.222401e-07 1.286575e-08 7.877480e-09 5.401425e-09 7.877480e-22 7.877480e-17\n1 -90.0 0.0 3.0480 4.838923e-07 4.869626e-07 7.032983e-07 7.429541e-08 4.866265e-08 3.410940e-08 4.866265e-21 4.866265e-16\n2 -90.0 0.0 6.0960 1.453834e-06 1.411544e-06 2.045308e-06 2.472576e-07 1.611648e-07 1.136527e-07 1.611648e-20 1.611648e-15\n3 -90.0 0.0 7.6200 2.352658e-06 2.382057e-06 3.304989e-06 3.720997e-07 2.420436e-07 1.708843e-07 2.420436e-20 2.420436e-15\n4 -90.0 0.0 8.5344 2.970462e-06 2.791970e-06 4.201789e-06 4.473736e-07 2.919136e-07 2.063902e-07 2.919136e-20 2.919136e-15\n... ... ... ... ... ... ... ... ... ... ... ...\n42619 90.0 355.0 14.9352 1.062397e-06 7.975138e-07 5.902218e-07 2.766678e-07 1.764588e-07 1.216189e-07 1.764588e-20 1.764588e-15\n42620 90.0 355.0 15.8496 1.289216e-06 9.183397e-07 6.964574e-07 3.063998e-07 1.945207e-07 1.338582e-07 1.945207e-20 1.945207e-15\n42621 90.0 355.0 16.7640 1.525359e-06 1.040969e-06 8.062018e-07 3.339381e-07 2.112220e-07 1.452375e-07 2.112220e-20 2.112220e-15\n42622 90.0 355.0 17.6784 1.777447e-06 1.163693e-06 9.297615e-07 3.568426e-07 2.248452e-07 1.543556e-07 2.248452e-20 2.248452e-15\n42623 90.0 355.0 18.5928 2.036052e-06 1.275021e-06 1.040287e-06 3.755276e-07 2.357292e-07 1.614028e-07 2.357292e-20 2.357292e-15\n```\n\nwhich will produce the following plot when\n\n```python\nfrom AniMAIRE import dose_plotting\nimport matplotlib.pyplot as plt\n\ndose_plotting.plot_dose_map(test_anisotropic_dose_rates.query(\"`altitude (km)` == 12.1920\"),\n hue_range=(0,9))\n\nplt.show()\n```\n\nis run, as was described previously in this README for isotropic plotting:\n\n\n\nyou can also produce similar plotly plots if you prefer plotly to matplotlib using:\n\n```python\nfrom AniMAIRE import dose_plotting\n\nanisotropic_dose_rate_map = dose_plotting.create_single_dose_map_plotly(test_anisotropic_dose_rates,\n selected_altitude_in_km = 12.1920)\n```\n\nwhich generates the following plot:\n\n\n\n### Functions for running `AniMAIRE` for specific situations and for a past timestamp\n\nIn addition to the quite general `run_from_spectra` function, `AniMAIRE` currently contains several functions for running calculations for specific types of spectra and situations, to make it easier for users to perform runs without having to determine and feed in spectra to `run_from_spectra` themselves.\n\nThe `run_from_DLR_cosmic_ray_power_law` function allows users to run full atmospheric dose rate calculations (for cosmic ray only/'quiet' time periods only) from just a date and time, or alternatively from just a single OULU count rate, or just a value of 'W parameter', as well as Kp index. This function utilises the [CosRayModifiedISO package](https://github.com/ssc-maire/CosRayModifiedISO) to determine the spectra due to protons and alpha particles during cosmic ray only time periods, and then runs `run_from_spectra` using both of those spectra under isotropic conditions. The specifications of `run_from_DLR_cosmic_ray_power_law` are:\n\n```python\ndef run_from_DLR_cosmic_ray_model(OULU_count_rate_in_seconds=None,\n W_parameter=None,\n Kp_index=None,\n date_and_time=None,\n **kwargs)\n```\n\n`**kwargs` here can be used to supply any arguments you wish to `run_from_spectra` as specified previously, such as the list of altitudes and list of coordinates to perform calculations for. Details on what `OULU_count_rate_in_seconds` and `W_parameter` mean can be found at <https://github.com/ssc-maire/CosRayModifiedISO> . If either `OULU_count_rate_in_seconds` or `W_parameter` are used, only one of them should be specified. Otherwise, `AniMAIRE` will determined their values using the `date_and_time` parameter supplied.\n\nIn addition to running from the DLR-ISO isotropic cosmic ray model, you can also run `AniMAIRE` from a combined power law rigidity spectrum and Gaussian pitch angle distribution. This can be done using the `run_from_power_law_gaussian_distribution` function:\n\n```python\ndef run_from_power_law_gaussian_distribution(J0, gamma, deltaGamma, sigma, \n reference_pitch_angle_latitude, reference_pitch_angle_longitude, \n Kp_index,date_and_time,\n **kwargs)\n```\n\nHere `J0`, `gamma`, `deltaGamma`, `sigma`, `reference_pitch_angle_latitude`, `reference_pitch_angle_longitude` are all defined as specified in the format of papers like [Mishev, A., Usoskin, I. Analysis of the Ground-Level Enhancements on 14 July 2000 and 13 December 2006 Using Neutron Monitor Data. Sol Phys 291, 1225\u20131239 (2016). https://doi.org/10.1007/s11207-016-0877-2](https://link.springer.com/article/10.1007/s11207-016-0877-2).\n\n## References\n\n- Davis, C. S. W. et al. (2024). *AniMAIRE-A New Openly Available Tool for Calculating Atmospheric Ionising Radiation Dose Rates and Single Event Effects During Anisotropic Conditions*. [https://doi.org/10.1029/2024SW003985](https://doi.org/10.1029/2024SW003985)\n- Larsen, N. et al.(2024). *A New Open-Source Geomagnetosphere Propagation Tool (OTSO) and Its Applications*. [https://doi.org/10.1029/2022JA031061](https://doi.org/10.1029/2022JA031061)\n- Mishev, A. & Usoskin, I. (2016). Analysis of the Ground-Level Enhancements on 14 July 2000 and 13 December 2006 Using Neutron Monitor Data. *Solar Physics, 291*, 1225\u20131239. [https://doi.org/10.1007/s11207-016-0877-2](https://doi.org/10.1007/s11207-016-0877-2)\n- Matthi\u00e4, D. et al. (2012). *A ready-to-use galactic cosmic ray model*, [https://doi.org/10.1016/j.asr.2012.09.022](https://doi.org/10.1016/j.asr.2012.09.022)\n",
"bugtrack_url": null,
"license": "CC By-NC-SA 4.0",
"summary": "Python library for running the anisotropic version of MAIRE+",
"version": "1.2.4",
"project_urls": {
"Homepage": "https://github.com/ssc-maire/AniMAIRE-public"
},
"split_keywords": [
"anisotropic",
"maire+",
"atmospheric",
"ionizing",
"radiation",
"dose",
"rates",
"cosmic",
"rays",
"ground",
"level",
"enhancements",
"gles",
"protons",
"alpha",
"particles",
"neutrons",
"effective",
"ambient",
"equivalent",
"aircraft",
"aviation",
"earth",
"solar",
"system",
"sun",
"space",
"magnetic",
"field"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4a7944848e828090b842214e67f570ca63813f9cc230bc85c1e6eaeda263a5b7",
"md5": "ccf7fec6be8cea5da3c79434eaf9c703",
"sha256": "eaf577e581fdb84b3db6d45fa5cc4ab90e475f2035690b3342855ba720bcbcd7"
},
"downloads": -1,
"filename": "AniMAIRE-1.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccf7fec6be8cea5da3c79434eaf9c703",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64643,
"upload_time": "2025-02-21T11:56:48",
"upload_time_iso_8601": "2025-02-21T11:56:48.046202Z",
"url": "https://files.pythonhosted.org/packages/4a/79/44848e828090b842214e67f570ca63813f9cc230bc85c1e6eaeda263a5b7/AniMAIRE-1.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "01d7bbe65dec626ed80acddd5bce8a652f3eef4bd24f00f6129975cd84afba9b",
"md5": "cde7eae64c4ed9b9c17803687a514305",
"sha256": "53dd6f38f0df4ffd1d92dfc03434e0b80b274bd6cbed8799872657921f884843"
},
"downloads": -1,
"filename": "animaire-1.2.4.tar.gz",
"has_sig": false,
"md5_digest": "cde7eae64c4ed9b9c17803687a514305",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 77734,
"upload_time": "2025-02-21T11:56:49",
"upload_time_iso_8601": "2025-02-21T11:56:49.269442Z",
"url": "https://files.pythonhosted.org/packages/01/d7/bbe65dec626ed80acddd5bce8a652f3eef4bd24f00f6129975cd84afba9b/animaire-1.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-21 11:56:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ssc-maire",
"github_project": "AniMAIRE-public",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.6"
]
]
},
{
"name": "wheel",
"specs": [
[
">=",
"0.43.0"
]
]
},
{
"name": "pandarallel",
"specs": [
[
">=",
"1.6.3"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.5"
]
]
},
{
"name": "ParticleRigidityCalculationTools",
"specs": [
[
">=",
"1.5.4"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.3"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"45.2.0"
]
]
},
{
"name": "spacepy",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.65.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.9.0"
]
]
},
{
"name": "numba",
"specs": [
[
">=",
"0.57.1"
]
]
},
{
"name": "metpy",
"specs": [
[
">=",
"1.5.1"
]
]
},
{
"name": "CosRayModifiedISO",
"specs": [
[
">=",
"1.2.9"
]
]
},
{
"name": "AsympDirsCalculator",
"specs": [
[
">=",
"1.0.8"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.13.2"
]
]
},
{
"name": "geopandas",
"specs": [
[
">=",
"0.11.1"
]
]
},
{
"name": "joblib",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "spaceweather",
"specs": [
[
">=",
"0.2.4"
]
]
},
{
"name": "atmosphericRadiationDoseAndFlux",
"specs": [
[
">=",
"1.0.3"
]
]
},
{
"name": "kpindex",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "ipywidgets",
"specs": [
[
">=",
"8.1.5"
]
]
},
{
"name": "dask",
"specs": [
[
">=",
"2022.0.0"
]
]
},
{
"name": "pyarrow",
"specs": [
[
">=",
"12.0.0"
]
]
}
],
"lcname": "animaire"
}
JSON
