# CosRayModifiedISO
A simple library for running the ISO galactic cosmic ray spectrum model as modified by DLR.
All the details and equations about this model can be found in Matthiä et al.,
"A ready-to-use galactic cosmic ray model", Advances in Space Research 51.3 (2013): 329-338, https://doi.org/10.1016/j.asr.2012.09.022 . This model only requires
a single parameter, *W*, which describes the modulation of the Sun at a given date and time, to calculate the flux of cosmic rays hitting Earth.
If you use this software for scientific research, please reference the above paper, and this software appropriately according to the appropriate journal publication rules.
# Installation
You can either install directly from PyPi using
```
pip install CosRayModifiedISO
```
Or clone CosRayModifiedISO from https://github.com/ssc-maire/CosRayModifiedISO, and then from the cloned directory, run
```
sudo python setup.py install
```
# Usage
to import this module, use
```
from CosRayModifiedISO import CosRayModifiedISO
```
unless otherwise stated, all of the quantities specified in this library use the following units:
* Energies are always in units of **MeV**
* Rigidities are always in units of **GV**
* Differential energy fluxes are always in units of **cts / cm<sup>2</sup> / s / sr / (MeV/n)**
* Differential rigidity fluxes are always in units of **cts / cm<sup>2</sup> / s / sr / (GV/n)**
It should be noted that in the field of space radiation, "energy" is frequently generally used specifically as a shorthand for "kinetic energy" rather than
the total energy of a particle (rest mass energy + kinetic energy), and all references to "energy" in this library should be assumed to be kinetic energy
unless otherwise specified.
All users should be always be careful to remember which differential flux type they are using for their application, as differential
energy flux and differential rigidity flux are different quantities which have a non-linear conversion between them. In general, differential
energy flux should always be used when working with energies, and differential rigidity flux should be used when working with particle rigidities.
If you're trying to create something like a particle 'kinetic energy spectrum' for instance, you should use particle kinetic energy on the x-axis, and the differential
energy flux on the y-axis (here using energy as a shorthand for kinetic energy).
Unit description:
| Symbol | name |
| ----------- | ----------- |
| cm | centimeter |
| s | seconds |
| sr | steradian |
| MeV | Megaelectronvolts |
| GV | Gigavolts |
| n | nucleons |
## Single differential flux values and ranges of differential flux values
to get a single differential flux value for a particle value of solar modulation, and for a particular particle with a given atomic number and kinetic energy
(or range of kinetic energies), the appropriate method for `CosRayModifiedISO` is
```
CosRayModifiedISO.getEnergyFluxesFromEnergies(solarModulationWparameter, atomicNumber, energyListInMeV)
```
For example, the script
```
from CosRayModifiedISO import CosRayModifiedISO
solarModulationWparameter = 19.25 # the solar modulation at a specific point in the solar cycle
atomicNumber = 1 # the atomic number of the particle in question - in this case a proton/hydrogen ion, which has an atomic number of 1
energyListInMeV = 945.2 # kinetic energy of particle in MeV
print(CosRayModifiedISO.getEnergyFluxesFromEnergies(solarModulationWparameter, atomicNumber, energyListInMeV))
```
gives
```
[0.00012419]
```
as output.
The argument `energyListInMeV` can be supplied as either a single float or as a list of floats to give either a single differential flux as output,
or a range of differential fluxes corresponding to each supplied kinetic energy.
If you instead want to acquire differential rigidity fluxes rather than differential energy fluxes, you can use
```
CosRayModifiedISO.getRigidityFluxesFromRigidities(solarModulationWparameter, atomicNumber, rigidityListInGV)
```
which has exactly the same syntax and usage as the `getEnergyFluxesFromEnergies` method, but where rigidities in GV must be supplied instead
of kinetic energies in MeV.
## Outputting full particle spectra from a date and time, from neutron monitor data, or from the solar modulation.
Instead of directly needing to input the solar modulation and required kinetic energies or rigidities for each calculation, methods are available to return
differential fluxes automatically based on neutron monitor data and a default set of kinetic energies designed to cover a range corresponding to particles
that are relevant specifically for radiation dose rate calculations in Earth's atmosphere.
The method
```
CosRayModifiedISO.getSpectrumUsingTimestamp(timestamp, atomicNumber)
```
method can be used to output the differential fluxes for a given date and time, for example,
```
from CosRayModifiedISO import CosRayModifiedISO
import datetime as dt
datetimeToUse = dt.datetime(
year = 2001,
month = 10,
day = 27,
hour = 0,
minute = 10,
second = 35
)
print(CosRayModifiedISO.getSpectrumUsingTimestamp(datetimeToUse,atomicNumber=1))
```
returns the output
```
Energy (MeV/n) d_Flux / d_E (cm-2 s-1 sr-1 (MeV/n)-1) Rigidity (GV/n) d_Flux / d_R (cm-2 s-1 sr-1 (GV/n)-1)
0 11.294627 2.290835e-07 0.146022 3.522790e-05
1 14.219093 3.785376e-07 0.163966 6.516322e-05
2 17.900778 6.157642e-07 0.184152 1.185919e-04
3 22.535744 9.848618e-07 0.206875 2.120539e-04
4 28.370820 1.546788e-06 0.232474 3.719962e-04
...
```
`getSpectrumUsingTimestamp` returns output in the form of a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).
This method uses historic values from the [OULU neutron monitor](https://cosmicrays.oulu.fi/) to determine values of solar modulation for input into
the model, using the method described in [Matthiä et al., (2013)](https://doi.org/10.1016/j.asr.2012.09.022). Currently only dates between 1964/04/01 00:00
and 2021/01/31 00:00 can be used.
Count rates from the OULU neutron monitor (or representative values) can be supplied directly into the model using the
```
CosRayModifiedISO.getSpectrumUsingOULUcountRate(OULUcountRatePerSecond, atomicNumber)
```
method, where `OULUcountRatePerSecond` is a single float representing the count rate per second of the OULU neutron monitor at a given instance of time.
The solar modulation parameter can also be supplied directly using
```
CosRayModifiedISO.getSpectrumUsingSolarModulation(solarModulationWparameter, atomicNumber)
```
This function can be identically supplied with the monthly averaged sunspot number instead of the solar modulation parameter, which the solar modulation parameter
is essentially a proxy for. Alternatively the identical function
```
CosRayModifiedISO.getSpectrumUsingSSN(sunspotNumber, atomicNumber)
```
can be used instead for code understandability.
Each of these three methods output Pandas DataFrames in the same format as outputted by `getSpectrumUsingTimestamp`. The value of the solar modulation parameter
as a function of OULU neutron monitor monitor count rate can also be outputted by running
```
CosRayModifiedISO.getWparameterFromOULUcountRate(OULUcountRateInSeconds)
```
# Quantity Conversion Functions
In addition to the above spectrum calculation methods, there are also several methods for performing conversion between different quantities for input and output.
The methods
```
CosRayModifiedISO.convertParticleRigidityToEnergy(particleRigidityInGV,
particleMassAU,
particleChargeAU)
```
and
```
CosRayModifiedISO.convertParticleRigidityToEnergy(particleRigidityInGV,
particleMassAU,
particleChargeAU)
```
can be used to convert particle rigidities to kinetic energies and vice versa, respectively. Currently particle rigidities and energy *must* be supplied
as [Pandas Series objects](https://pandas.pydata.org/docs/reference/api/pandas.Series.html). Particle masses and charges here must be inputted as single numbers
and in atomic units.
The methods
```
CosRayModifiedISO.convertParticleRigiditySpecToEnergySpec(particleRigidityInGV,
fluxInRigidityGVform,
particleMassAU,
particleChargeAU)
```
and
```
CosRayModifiedISO.convertParticleEnergySpecToRigiditySpec(particleKineticEnergyInMeV,
fluxInEnergyMeVform,
particleMassAU,
particleChargeAU)
```
can be used to convert differential rigidity flux to differential energy flux and vice versa, respectively. Both the particle rigidity values and their
respective differential flux values must be inputted as [Pandas Series objects](https://pandas.pydata.org/docs/reference/api/pandas.Series.html).
The particle mass for all of these methods can be acquired directly from atomic number using
```
CosRayModifiedISO.getAtomicMass(atomicNumber)
```
# Acknowledgments
Thank you to Daniel Matthiä and others at DLR for allowing us to test their model initially using their own scripts.
This package contains and for certain functions uses data from the OULU neutron monitor, as acquired from https://www.nmdb.eu/ , where data can also be found at https://cosmicrays.oulu.fi/ . We therefore acknowledge the NMDB database www.nmdb.eu, founded under the European Union's FP7 programme (contract no. 213007) for providing data.
Raw data
{
"_id": null,
"home_page": "https://github.com/ssc-maire/CosRayModifiedISO",
"name": "CosRayModifiedISO",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Space Environment and Protection Group, University of Surrey",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d8/cc/fd199fd550e37c50649aef1214af0dadd2d7347ba9257f2674f272d34a5b/cosraymodifiediso-1.2.8.tar.gz",
"platform": null,
"description": "# CosRayModifiedISO\n\nA simple library for running the ISO galactic cosmic ray spectrum model as modified by DLR. \n\nAll the details and equations about this model can be found in Matthi\u00e4 et al., \n\"A ready-to-use galactic cosmic ray model\", Advances in Space Research 51.3 (2013): 329-338, https://doi.org/10.1016/j.asr.2012.09.022 . This model only requires\na single parameter, *W*, which describes the modulation of the Sun at a given date and time, to calculate the flux of cosmic rays hitting Earth.\n\nIf you use this software for scientific research, please reference the above paper, and this software appropriately according to the appropriate journal publication rules.\n \n# Installation\n\nYou can either install directly from PyPi using\n\n```\npip install CosRayModifiedISO\n```\n\nOr clone CosRayModifiedISO from https://github.com/ssc-maire/CosRayModifiedISO, and then from the cloned directory, run\n\n```\nsudo python setup.py install\n```\n\n# Usage\n\nto import this module, use\n\n```\nfrom CosRayModifiedISO import CosRayModifiedISO\n```\n\nunless otherwise stated, all of the quantities specified in this library use the following units:\n* Energies are always in units of **MeV**\n* Rigidities are always in units of **GV**\n* Differential energy fluxes are always in units of **cts / cm<sup>2</sup> / s / sr / (MeV/n)**\n* Differential rigidity fluxes are always in units of **cts / cm<sup>2</sup> / s / sr / (GV/n)**\n\nIt should be noted that in the field of space radiation, \"energy\" is frequently generally used specifically as a shorthand for \"kinetic energy\" rather than \nthe total energy of a particle (rest mass energy + kinetic energy), and all references to \"energy\" in this library should be assumed to be kinetic energy\nunless otherwise specified.\n\nAll users should be always be careful to remember which differential flux type they are using for their application, as differential \nenergy flux and differential rigidity flux are different quantities which have a non-linear conversion between them. In general, differential\nenergy flux should always be used when working with energies, and differential rigidity flux should be used when working with particle rigidities.\nIf you're trying to create something like a particle 'kinetic energy spectrum' for instance, you should use particle kinetic energy on the x-axis, and the differential\nenergy flux on the y-axis (here using energy as a shorthand for kinetic energy).\n\nUnit description:\n\n| Symbol | name |\n| ----------- | ----------- |\n| cm | centimeter |\n| s | seconds |\n| sr | steradian |\n| MeV | Megaelectronvolts |\n| GV | Gigavolts |\n| n | nucleons |\n\n## Single differential flux values and ranges of differential flux values\n\nto get a single differential flux value for a particle value of solar modulation, and for a particular particle with a given atomic number and kinetic energy \n(or range of kinetic energies), the appropriate method for `CosRayModifiedISO` is\n```\nCosRayModifiedISO.getEnergyFluxesFromEnergies(solarModulationWparameter, atomicNumber, energyListInMeV)\n```\n\nFor example, the script\n```\nfrom CosRayModifiedISO import CosRayModifiedISO\n\nsolarModulationWparameter = 19.25 # the solar modulation at a specific point in the solar cycle\natomicNumber = 1 # the atomic number of the particle in question - in this case a proton/hydrogen ion, which has an atomic number of 1\nenergyListInMeV = 945.2 # kinetic energy of particle in MeV\n\nprint(CosRayModifiedISO.getEnergyFluxesFromEnergies(solarModulationWparameter, atomicNumber, energyListInMeV))\n```\ngives\n```\n[0.00012419]\n```\nas output.\n\nThe argument `energyListInMeV` can be supplied as either a single float or as a list of floats to give either a single differential flux as output, \nor a range of differential fluxes corresponding to each supplied kinetic energy.\n\nIf you instead want to acquire differential rigidity fluxes rather than differential energy fluxes, you can use\n```\nCosRayModifiedISO.getRigidityFluxesFromRigidities(solarModulationWparameter, atomicNumber, rigidityListInGV)\n```\nwhich has exactly the same syntax and usage as the `getEnergyFluxesFromEnergies` method, but where rigidities in GV must be supplied instead \nof kinetic energies in MeV.\n\n## Outputting full particle spectra from a date and time, from neutron monitor data, or from the solar modulation.\n\nInstead of directly needing to input the solar modulation and required kinetic energies or rigidities for each calculation, methods are available to return \ndifferential fluxes automatically based on neutron monitor data and a default set of kinetic energies designed to cover a range corresponding to particles \nthat are relevant specifically for radiation dose rate calculations in Earth's atmosphere.\n\nThe method\n```\nCosRayModifiedISO.getSpectrumUsingTimestamp(timestamp, atomicNumber)\n```\nmethod can be used to output the differential fluxes for a given date and time, for example,\n\n```\nfrom CosRayModifiedISO import CosRayModifiedISO\nimport datetime as dt\n\ndatetimeToUse = dt.datetime(\n year = 2001,\n month = 10,\n day = 27,\n hour = 0,\n minute = 10,\n second = 35\n )\n \nprint(CosRayModifiedISO.getSpectrumUsingTimestamp(datetimeToUse,atomicNumber=1))\n```\nreturns the output\n```\n Energy (MeV/n) d_Flux / d_E (cm-2 s-1 sr-1 (MeV/n)-1) Rigidity (GV/n) d_Flux / d_R (cm-2 s-1 sr-1 (GV/n)-1)\n0 11.294627 2.290835e-07 0.146022 3.522790e-05\n1 14.219093 3.785376e-07 0.163966 6.516322e-05\n2 17.900778 6.157642e-07 0.184152 1.185919e-04\n3 22.535744 9.848618e-07 0.206875 2.120539e-04\n4 28.370820 1.546788e-06 0.232474 3.719962e-04\n...\n```\n`getSpectrumUsingTimestamp` returns output in the form of a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).\n\nThis method uses historic values from the [OULU neutron monitor](https://cosmicrays.oulu.fi/) to determine values of solar modulation for input into \nthe model, using the method described in [Matthi\u00e4 et al., (2013)](https://doi.org/10.1016/j.asr.2012.09.022). Currently only dates between 1964/04/01 00:00 \nand 2021/01/31 00:00 can be used.\n\nCount rates from the OULU neutron monitor (or representative values) can be supplied directly into the model using the\n```\nCosRayModifiedISO.getSpectrumUsingOULUcountRate(OULUcountRatePerSecond, atomicNumber)\n```\nmethod, where `OULUcountRatePerSecond` is a single float representing the count rate per second of the OULU neutron monitor at a given instance of time. \nThe solar modulation parameter can also be supplied directly using\n```\nCosRayModifiedISO.getSpectrumUsingSolarModulation(solarModulationWparameter, atomicNumber)\n```\nThis function can be identically supplied with the monthly averaged sunspot number instead of the solar modulation parameter, which the solar modulation parameter\nis essentially a proxy for. Alternatively the identical function \n\n```\nCosRayModifiedISO.getSpectrumUsingSSN(sunspotNumber, atomicNumber)\n``` \ncan be used instead for code understandability.\n\nEach of these three methods output Pandas DataFrames in the same format as outputted by `getSpectrumUsingTimestamp`. The value of the solar modulation parameter\nas a function of OULU neutron monitor monitor count rate can also be outputted by running\n\n```\nCosRayModifiedISO.getWparameterFromOULUcountRate(OULUcountRateInSeconds)\n```\n\n# Quantity Conversion Functions\n\nIn addition to the above spectrum calculation methods, there are also several methods for performing conversion between different quantities for input and output.\n\nThe methods\n```\nCosRayModifiedISO.convertParticleRigidityToEnergy(particleRigidityInGV, \n particleMassAU, \n particleChargeAU)\n```\nand\n```\nCosRayModifiedISO.convertParticleRigidityToEnergy(particleRigidityInGV, \n particleMassAU, \n particleChargeAU)\n```\ncan be used to convert particle rigidities to kinetic energies and vice versa, respectively. Currently particle rigidities and energy *must* be supplied \nas [Pandas Series objects](https://pandas.pydata.org/docs/reference/api/pandas.Series.html). Particle masses and charges here must be inputted as single numbers\nand in atomic units.\n\nThe methods\n```\nCosRayModifiedISO.convertParticleRigiditySpecToEnergySpec(particleRigidityInGV, \n fluxInRigidityGVform, \n particleMassAU, \n particleChargeAU)\n```\nand\n```\nCosRayModifiedISO.convertParticleEnergySpecToRigiditySpec(particleKineticEnergyInMeV, \n fluxInEnergyMeVform, \n particleMassAU, \n particleChargeAU)\n```\ncan be used to convert differential rigidity flux to differential energy flux and vice versa, respectively. Both the particle rigidity values and their \nrespective differential flux values must be inputted as [Pandas Series objects](https://pandas.pydata.org/docs/reference/api/pandas.Series.html).\n\nThe particle mass for all of these methods can be acquired directly from atomic number using\n```\nCosRayModifiedISO.getAtomicMass(atomicNumber)\n```\n\n# Acknowledgments\n\nThank you to Daniel Matthi\u00e4 and others at DLR for allowing us to test their model initially using their own scripts. \n\nThis package contains and for certain functions uses data from the OULU neutron monitor, as acquired from https://www.nmdb.eu/ , where data can also be found at https://cosmicrays.oulu.fi/ . We therefore acknowledge the NMDB database www.nmdb.eu, founded under the European Union's FP7 programme (contract no. 213007) for providing data. \n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for acquiring galactic cosmic ray spectra at Earth from the ISO model as modified by DLR. All the details and equations about this model can be found in Matthiae et al., A ready-to-use galactic cosmic ray model, Advances in Space Research 51.3 (2013): 329-338, https://doi.org/10.1016/j.asr.2012.09.022 .",
"version": "1.2.8",
"project_urls": {
"Homepage": "https://github.com/ssc-maire/CosRayModifiedISO"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be3072e86c6417cf1632da36ba5e7c11108a069a57a303ae09157c89b1426208",
"md5": "cbee5941f3ebf2bfc445aac785c595d2",
"sha256": "f2217271f397d3f18334b218f071dfd85109d040c13cf46e371e8204fe128a8e"
},
"downloads": -1,
"filename": "CosRayModifiedISO-1.2.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbee5941f3ebf2bfc445aac785c595d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 36201737,
"upload_time": "2024-09-02T15:22:28",
"upload_time_iso_8601": "2024-09-02T15:22:28.685738Z",
"url": "https://files.pythonhosted.org/packages/be/30/72e86c6417cf1632da36ba5e7c11108a069a57a303ae09157c89b1426208/CosRayModifiedISO-1.2.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d8ccfd199fd550e37c50649aef1214af0dadd2d7347ba9257f2674f272d34a5b",
"md5": "7328ba5cebc3e8f902b5e3e4fab27934",
"sha256": "f9dea385dbede2656d8227d301ec2f099bf94a0aaf23160d77085290cf484487"
},
"downloads": -1,
"filename": "cosraymodifiediso-1.2.8.tar.gz",
"has_sig": false,
"md5_digest": "7328ba5cebc3e8f902b5e3e4fab27934",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 35495175,
"upload_time": "2024-09-02T15:22:32",
"upload_time_iso_8601": "2024-09-02T15:22:32.417332Z",
"url": "https://files.pythonhosted.org/packages/d8/cc/fd199fd550e37c50649aef1214af0dadd2d7347ba9257f2674f272d34a5b/cosraymodifiediso-1.2.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 15:22:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ssc-maire",
"github_project": "CosRayModifiedISO",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "cosraymodifiediso"
}
JSON
