# atmosphericRadiationDoseAndFlux
A calculation toolkit for determining radiation dose rates in the atmosphere due to an incoming spectrum of particles from space.
# Installation
After cloning this directory to your computer, install this package from the cloned directory using the command
```
sudo pip3 install .
```
or alternatively,
```
sudo python3 setup.py install
```
# Usage
## Calculating dose rates from an input spectrum as a function
Radiation dose rates that aircraft experience are dependent on the incoming radiation spectrum from space for each incoming particle type,
altitude above ground level and the 'vertical cut-off rigidity' (which is a function of latitude and longitude).
You can directly calculate radiation dose rates from an incoming rigidity spectrum using the `calculate_from_rigidity_spec` function.
`calculate_from_rigidity_spec` takes in an input rigidity specrum as a Python function, as well as an altitude or a list of altitudes,
and outputs the dose rates aircraft will experience at that altitude. You can optionally also include a vertical cut-off rigidity (the
default vertical cut-off rigidity is set to 0.0 GV).
The usage of `calculate_from_rigidity_spec` is:
```
calculate_from_rigidity_spec(rigiditySpectrum:Function,
altitudesInkm:float|list,
particleName="proton",
inputRigidityBins=None,
verticalCutOffRigidity=0.0)
```
where the input parameters are:
| parameter | description |
| --------- | ----------- |
| rigiditySpectrum | *callable function*: must be specified in units of **particles/cm2/sr/GV/s**, and as a function of rigidity in GV. rigiditySpectrum can be specified as any callable single argument function, representing an incoming particle spectrum with any distribution. You may wish to use Python's [lambda function](https://www.w3schools.com/python/python_lambda.asp) to do this.
| altitudesInkm | *float* or *list*: if specified as a list, calculations will be performed in a loop over each of the specified altitudes and returned in the output Pandas DataFrame.
| particleName | *str*: must be either "proton" or "alpha". Currently using the setting "alpha" actually calculates dose rates associated with all particles species with atomic numbers 2 and greater rather than just for alpha particles. Default = "proton".
| inputRigidityBins | *list*: an optional input parameter, do not use unless experienced with using this library. Setting this parameter to a value overrides this module's internal application of the `rigiditySpectrum` parameter to an internal default set of energy bins for the purpose of calculating dose rates and fluxes. |
| verticalCutOffRigidity | *float*: units of gigavolts (GV). Default = 0.0.
For example, after importing the module using
```
from atmosphericRadiationDoseAndFlux import doseAndFluxCalculator as DAFcalc
```
and defining an input rigidity spectrum as a function;
```
testA = 2.77578789
testmu = 2.82874076
testRigiditySpectrum = lambda x:testA*(x**(-testmu))
```
running
```
DAFcalc.calculate_from_rigidity_spec(testRigiditySpectrum,
particleName="proton",altitudesInkm=18.5928, verticalCutOffRigidity=0.0)
```
will return
```
altitude (km) edose adose dosee tn1 tn2 \
0 18.5928 62.219856 41.774429 34.169926 12.323553 7.639987
tn3 SEU SEL
0 5.108492 7.639987e-13 7.639987e-08
```
as a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html). Here `testRigiditySpectrum` is a power law distribution in rigidity, with a spectral index of `testmu` and a value at x = 1 of `testA`.
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 |
Dose rates can also be generated from an energy spectrum using `calculate_from_energy_spec`, which has the same syntax as `calculate_from_rigidity_spec`,
but where the incoming spectrum (now in units of *particles/cm2/sr/MeV/s*) must be specified in terms of energy in MeV instead of rigidity and the optional `inputRigidityBins` parameter is instead `inputEnergyBins` in MeV.
## Calculating dose rates from an input spectrum as an array
While it is recommended that the user uses functions as the method of inputting spectra, you can also use the `calculate_from_rigidity_spec_array` and `calculate_from_energy_spec_array` functions to calculate dose rates directly from an array of spectral flux values and energy bins.
The general syntax for inputs to these are:
```
calculate_from_rigidity_spec_array(
inputRigidityBins:list,
inputFluxesGV:list,
altitudesInkm:list,
particleName="proton",
verticalCutOffRigidity = 0.0)
```
where `inputRigidityBins` is the full list of rigidity bin edge locations in GV that the input fluxes specified by `inputFluxesGV` are specified for. As `inputRigidityBins` represent the bin edge locations for `inputFluxesGV`, the length of `inputRigidityBins` must therefore be exactly 1 greater than the length of `inputFluxesGV`.
`calculate_from_energy_spec_array` has a nearly identical syntax to `calculate_from_rigidity_spec_array`, where the only difference is that the first argument of `calculate_from_energy_spec_array` must be specified in MeV instead of GV, and the second argument is the energy spectrum in particles/cm2/sr/MeV/s instead of the rigidity spectrum in particles/cm2/sr/GV/s.
Raw data
{
"_id": null,
"home_page": "https://github.com/ssc-maire/DoseAndFluxCalculator",
"name": "atmosphericRadiationDoseAndFlux",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "atmosphere radiation space weather cosmic rays spectrum alpha particles yield response dose rates ambient effective GLE sun solar aviation neutron monitor",
"author": "Space Environment and Protection Group, University of Surrey",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/74/9f/b44a7ce4d88b9f86394c7271b762f7ecf75e481b907cd846af2bb8745637/atmosphericradiationdoseandflux-1.0.10.tar.gz",
"platform": null,
"description": "# atmosphericRadiationDoseAndFlux\n\nA calculation toolkit for determining radiation dose rates in the atmosphere due to an incoming spectrum of particles from space.\n\n# Installation\n\nAfter cloning this directory to your computer, install this package from the cloned directory using the command\n\n```\nsudo pip3 install .\n```\nor alternatively,\n```\nsudo python3 setup.py install\n```\n\n# Usage\n\n## Calculating dose rates from an input spectrum as a function\n\nRadiation dose rates that aircraft experience are dependent on the incoming radiation spectrum from space for each incoming particle type, \naltitude above ground level and the 'vertical cut-off rigidity' (which is a function of latitude and longitude). \n\nYou can directly calculate radiation dose rates from an incoming rigidity spectrum using the `calculate_from_rigidity_spec` function. \n`calculate_from_rigidity_spec` takes in an input rigidity specrum as a Python function, as well as an altitude or a list of altitudes, \nand outputs the dose rates aircraft will experience at that altitude. You can optionally also include a vertical cut-off rigidity (the \ndefault vertical cut-off rigidity is set to 0.0 GV).\n\nThe usage of `calculate_from_rigidity_spec` is:\n\n```\ncalculate_from_rigidity_spec(rigiditySpectrum:Function, \n altitudesInkm:float|list, \n particleName=\"proton\", \n inputRigidityBins=None,\n verticalCutOffRigidity=0.0)\n```\nwhere the input parameters are:\n\n| parameter | description |\n| --------- | ----------- |\n| rigiditySpectrum | *callable function*: must be specified in units of **particles/cm2/sr/GV/s**, and as a function of rigidity in GV. rigiditySpectrum can be specified as any callable single argument function, representing an incoming particle spectrum with any distribution. You may wish to use Python's [lambda function](https://www.w3schools.com/python/python_lambda.asp) to do this.\n| altitudesInkm | *float* or *list*: if specified as a list, calculations will be performed in a loop over each of the specified altitudes and returned in the output Pandas DataFrame.\n| particleName | *str*: must be either \"proton\" or \"alpha\". Currently using the setting \"alpha\" actually calculates dose rates associated with all particles species with atomic numbers 2 and greater rather than just for alpha particles. Default = \"proton\".\n| inputRigidityBins | *list*: an optional input parameter, do not use unless experienced with using this library. Setting this parameter to a value overrides this module's internal application of the `rigiditySpectrum` parameter to an internal default set of energy bins for the purpose of calculating dose rates and fluxes. |\n| verticalCutOffRigidity | *float*: units of gigavolts (GV). Default = 0.0. \n\nFor example, after importing the module using\n```\nfrom atmosphericRadiationDoseAndFlux import doseAndFluxCalculator as DAFcalc\n```\nand defining an input rigidity spectrum as a function;\n```\ntestA = 2.77578789\ntestmu = 2.82874076\n\ntestRigiditySpectrum = lambda x:testA*(x**(-testmu))\n```\nrunning\n```\nDAFcalc.calculate_from_rigidity_spec(testRigiditySpectrum, \n particleName=\"proton\",altitudesInkm=18.5928, verticalCutOffRigidity=0.0)\n```\nwill return\n```\n altitude (km) edose adose dosee tn1 tn2 \\\n0 18.5928 62.219856 41.774429 34.169926 12.323553 7.639987 \n\n tn3 SEU SEL \n0 5.108492 7.639987e-13 7.639987e-08 \n```\nas a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html). Here `testRigiditySpectrum` is a power law distribution in rigidity, with a spectral index of `testmu` and a value at x = 1 of `testA`.\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\nDose rates can also be generated from an energy spectrum using `calculate_from_energy_spec`, which has the same syntax as `calculate_from_rigidity_spec`, \nbut where the incoming spectrum (now in units of *particles/cm2/sr/MeV/s*) must be specified in terms of energy in MeV instead of rigidity and the optional `inputRigidityBins` parameter is instead `inputEnergyBins` in MeV.\n\n## Calculating dose rates from an input spectrum as an array\n\nWhile it is recommended that the user uses functions as the method of inputting spectra, you can also use the `calculate_from_rigidity_spec_array` and `calculate_from_energy_spec_array` functions to calculate dose rates directly from an array of spectral flux values and energy bins.\n\nThe general syntax for inputs to these are:\n\n```\ncalculate_from_rigidity_spec_array(\n inputRigidityBins:list,\n inputFluxesGV:list, \n altitudesInkm:list, \n particleName=\"proton\",\n verticalCutOffRigidity = 0.0)\n```\n \nwhere `inputRigidityBins` is the full list of rigidity bin edge locations in GV that the input fluxes specified by `inputFluxesGV` are specified for. As `inputRigidityBins` represent the bin edge locations for `inputFluxesGV`, the length of `inputRigidityBins` must therefore be exactly 1 greater than the length of `inputFluxesGV`.\n\n`calculate_from_energy_spec_array` has a nearly identical syntax to `calculate_from_rigidity_spec_array`, where the only difference is that the first argument of `calculate_from_energy_spec_array` must be specified in MeV instead of GV, and the second argument is the energy spectrum in particles/cm2/sr/MeV/s instead of the rigidity spectrum in particles/cm2/sr/GV/s.\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3.0",
"summary": "Python library for calculating doses and fluxes at a particular altitude given an input spectrum",
"version": "1.0.10",
"project_urls": {
"Homepage": "https://github.com/ssc-maire/DoseAndFluxCalculator"
},
"split_keywords": [
"atmosphere",
"radiation",
"space",
"weather",
"cosmic",
"rays",
"spectrum",
"alpha",
"particles",
"yield",
"response",
"dose",
"rates",
"ambient",
"effective",
"gle",
"sun",
"solar",
"aviation",
"neutron",
"monitor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f5c1b4177919fe9c162e237ab144e81b44ae77102b1fc08f86e7e4c72a3300e",
"md5": "f623aa318baabab49ebabe5434b08418",
"sha256": "dc4447ff1075b1c493ab495530b38f4f0924fe31ef0839c7edc870dc5957682d"
},
"downloads": -1,
"filename": "atmosphericRadiationDoseAndFlux-1.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f623aa318baabab49ebabe5434b08418",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 193374,
"upload_time": "2024-09-02T13:28:07",
"upload_time_iso_8601": "2024-09-02T13:28:07.088527Z",
"url": "https://files.pythonhosted.org/packages/8f/5c/1b4177919fe9c162e237ab144e81b44ae77102b1fc08f86e7e4c72a3300e/atmosphericRadiationDoseAndFlux-1.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "749fb44a7ce4d88b9f86394c7271b762f7ecf75e481b907cd846af2bb8745637",
"md5": "21196e4ea059952153b511a1675d3a14",
"sha256": "8b84fe1a2b2da95f545144a22d419cd17aef25a2bdca2c58243c06b60a03c6a0"
},
"downloads": -1,
"filename": "atmosphericradiationdoseandflux-1.0.10.tar.gz",
"has_sig": false,
"md5_digest": "21196e4ea059952153b511a1675d3a14",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 184943,
"upload_time": "2024-09-02T13:28:08",
"upload_time_iso_8601": "2024-09-02T13:28:08.456465Z",
"url": "https://files.pythonhosted.org/packages/74/9f/b44a7ce4d88b9f86394c7271b762f7ecf75e481b907cd846af2bb8745637/atmosphericradiationdoseandflux-1.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 13:28:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ssc-maire",
"github_project": "DoseAndFluxCalculator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "atmosphericradiationdoseandflux"
}
JSON
