# ParticleRigidityCalculationTools
A set of Python functions for processing and converting data in units of particle kinetic energy to units of particle rigidity (typically expressed in GV; gigavolts) and vice versa. This is frequently done in the field of solar system radiation physics.
# Installation
To install from pypi, run
```
sudo pip3 install ParticleRigidityCalculationTools
```
Alternatively, you can install directly from the Github repository.
To do this you can first clone the repository, and then from the cloned respository, run
```
sudo python setup.py install
```
# Usage
For all the functions contained in this module, kinetic energy is always expressed in **MeV** (megaelectronvolts), and rigidity is always expressed in terms of **GV** (gigavolts) unless otherwise stated.
## General Conversion Functions
To convert particle kinetic energy to rigidity, use the `convertParticleEnergyToRigidity` function.
Particle kinetic energies can be supplied as a float, int, list, [NumPy array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) or [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html). Particle mass in atomic units should also be supplied, as well as the particle charge in atomic units, as particle rigidity is dependent on these quantities.
For instance, to calculate particle rigidities for several kinetic energies at once you can first define a list of particle kinetic energies:
```
import ParticleRigidityCalculationTools as PRCT
particleKineticEnergyInMeV = [250.0, 578.5, 1056.8, 5123.9]
```
and then running
```
PRCT.convertParticleEnergyToRigidity(particleKineticEnergyInMeV, particleMassAU = 1.0, particleChargeAU = 1.0)
```
will give the corresponding rigidities for a **proton** with kinetic energies of 250.0 MeV, 578.5 MeV, 1056.8 MeV and 5123.9 MeV respectively:
```
0 0.729134
1 1.191740
2 1.760670
3 5.989121
```
note that the output to this function, as with all rigidity calculation functions in this module is a [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html).
To perform the opposite calculation, calculating kinetic energies from a list of rigidities, you can use the `convertParticleRigidityToEnergy` function, which uses exactly the same input format but using input rigidities instead of energies. Using the output from the previous function:
```
outputtedRigiditiesSeries = PRCT.convertParticleEnergyToRigidity(particleKineticEnergyInMeV, particleMassAU = 1.0, particleChargeAU = 1.0)
```
we can get back the original set of proton kinetic energies with
```
PRCT.convertParticleRigidityToEnergy(outputtedRigiditiesSeries,particleMassAU=1.0,particleChargeAU=1.0)
```
which returns
```
0 250.0
1 578.5
2 1056.8
3 5123.9
```
as a [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html).
When not using protons, you can either directly input the particle mass from tabulated values or use the `getAtomicMass` function to get tabulated average mass values for a particle with a particular atomic number. For instance, for an alpha particle/helium ion:
```
alphaParticleAtomicNumber = 2
PRCT.getAtomicMass(alphaParticleAtomicNumber)
```
returns
```
4.0
```
The particle charge for all functions in this module is identical to the particle atomic number.
## Spectrum Conversion Functions
A user might not necessarily want to just convert individual numbers between units of rigidity and energy, they might also want to convert a kinetic energy distribution or rigidity distribution. This might usually be expressed in the form of $\frac{dN}{dE}$ or $\frac{dN}{dR}$, where E and R are particle kinetic energy and rigidity respectively, and where both quantities are expressed in terms of kinetic energy and rigidity respectively. As there is a one-to-one relationship between kinetic energy and rigidity, it is possible to analytically convert between these two quantities using $\frac{dN}{dR} = \frac{dN}{dE} \times \frac{dE}{dR}$, where $\frac{dR}{dE}$ can be calculated using the definition of the [magnetic rigidity of a particle](https://www.nmdb.eu/public_outreach/de/07_md/).
Tools are available in this module to perform all of this process automatically. The function `convertParticleEnergySpecToRigiditySpec` can be used to convert kinetic energy distributions into rigidity distributions, for example:
```
energyValuesInMeV = [1000,2000,3000,4000,5000]
energyDistributionValues = [1,0.5,0.2,0.1,0.01]
PRCT.convertParticleEnergySpecToRigiditySpec(energyValuesInMeV,energyDistributionValues,particleMassAU = 1.0,particleChargeAU = 1.0)
```
returns
```
Rigidity Rigidity distribution values
0 1.696038 875.025647
1 2.784437 473.822152
2 3.824870 194.241037
3 4.848317 98.178407
4 5.863678 9.874384
```
as a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).
The function `convertParticleRigiditySpecToEnergySpec` can be used to perform the opposite operation, converting particle rigidity to kinetic energy. For example,
```
rigiditySpec = PRCT.convertParticleEnergySpecToRigiditySpec(energyValuesInMeV,energyDistributionValues,particleMassAU = 1,particleChargeAU = 1)
PRCT.convertParticleRigiditySpecToEnergySpec(rigiditySpec["Rigidity"],rigiditySpec["Rigidity distribution values"],particleMassAU = 1,particleChargeAU = 1)
```
returns
```
Energy Energy distribution values
0 1000.0 1.00
1 2000.0 0.50
2 3000.0 0.20
3 4000.0 0.10
4 5000.0 0.01
```
the original kinetic energies and distribution values that were used for the energy distribution.
Raw data
{
"_id": null,
"home_page": "https://github.com/ssc-maire/ParticleRigidityCalculationTools",
"name": "ParticleRigidityCalculationTools",
"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/bf/41/5e296140f6fff2900c4ea3a979f6878cba5cc7a2547fdbac8eec1c1572d4/particlerigiditycalculationtools-1.5.16.tar.gz",
"platform": null,
"description": "# ParticleRigidityCalculationTools\n\nA set of Python functions for processing and converting data in units of particle kinetic energy to units of particle rigidity (typically expressed in GV; gigavolts) and vice versa. This is frequently done in the field of solar system radiation physics.\n\n# Installation\n\nTo install from pypi, run\n\n```\nsudo pip3 install ParticleRigidityCalculationTools\n```\nAlternatively, you can install directly from the Github repository.\n\nTo do this you can first clone the repository, and then from the cloned respository, run\n\n```\nsudo python setup.py install\n```\n\n# Usage\n\nFor all the functions contained in this module, kinetic energy is always expressed in **MeV** (megaelectronvolts), and rigidity is always expressed in terms of **GV** (gigavolts) unless otherwise stated.\n\n## General Conversion Functions\n\nTo convert particle kinetic energy to rigidity, use the `convertParticleEnergyToRigidity` function. \n\nParticle kinetic energies can be supplied as a float, int, list, [NumPy array](https://numpy.org/doc/stable/reference/generated/numpy.array.html) or [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html). Particle mass in atomic units should also be supplied, as well as the particle charge in atomic units, as particle rigidity is dependent on these quantities.\n\nFor instance, to calculate particle rigidities for several kinetic energies at once you can first define a list of particle kinetic energies:\n```\nimport ParticleRigidityCalculationTools as PRCT\n\nparticleKineticEnergyInMeV = [250.0, 578.5, 1056.8, 5123.9]\n```\n\nand then running\n```\nPRCT.convertParticleEnergyToRigidity(particleKineticEnergyInMeV, particleMassAU = 1.0, particleChargeAU = 1.0)\n```\n\nwill give the corresponding rigidities for a **proton** with kinetic energies of 250.0 MeV, 578.5 MeV, 1056.8 MeV and 5123.9 MeV respectively:\n```\n0 0.729134\n1 1.191740\n2 1.760670\n3 5.989121\n```\nnote that the output to this function, as with all rigidity calculation functions in this module is a [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html). \n\nTo perform the opposite calculation, calculating kinetic energies from a list of rigidities, you can use the `convertParticleRigidityToEnergy` function, which uses exactly the same input format but using input rigidities instead of energies. Using the output from the previous function:\n\n```\noutputtedRigiditiesSeries = PRCT.convertParticleEnergyToRigidity(particleKineticEnergyInMeV, particleMassAU = 1.0, particleChargeAU = 1.0)\n```\nwe can get back the original set of proton kinetic energies with\n```\nPRCT.convertParticleRigidityToEnergy(outputtedRigiditiesSeries,particleMassAU=1.0,particleChargeAU=1.0)\n```\nwhich returns\n```\n0 250.0\n1 578.5\n2 1056.8\n3 5123.9\n```\nas a [Pandas Series](https://pandas.pydata.org/docs/reference/api/pandas.Series.html).\n\nWhen not using protons, you can either directly input the particle mass from tabulated values or use the `getAtomicMass` function to get tabulated average mass values for a particle with a particular atomic number. For instance, for an alpha particle/helium ion:\n\n```\nalphaParticleAtomicNumber = 2\n\nPRCT.getAtomicMass(alphaParticleAtomicNumber)\n```\n\nreturns\n```\n4.0\n```\n\nThe particle charge for all functions in this module is identical to the particle atomic number.\n\n## Spectrum Conversion Functions\n\nA user might not necessarily want to just convert individual numbers between units of rigidity and energy, they might also want to convert a kinetic energy distribution or rigidity distribution. This might usually be expressed in the form of $\\frac{dN}{dE}$ or $\\frac{dN}{dR}$, where E and R are particle kinetic energy and rigidity respectively, and where both quantities are expressed in terms of kinetic energy and rigidity respectively. As there is a one-to-one relationship between kinetic energy and rigidity, it is possible to analytically convert between these two quantities using $\\frac{dN}{dR} = \\frac{dN}{dE} \\times \\frac{dE}{dR}$, where $\\frac{dR}{dE}$ can be calculated using the definition of the [magnetic rigidity of a particle](https://www.nmdb.eu/public_outreach/de/07_md/).\n\nTools are available in this module to perform all of this process automatically. The function `convertParticleEnergySpecToRigiditySpec` can be used to convert kinetic energy distributions into rigidity distributions, for example:\n\n```\nenergyValuesInMeV = [1000,2000,3000,4000,5000]\nenergyDistributionValues = [1,0.5,0.2,0.1,0.01]\n\nPRCT.convertParticleEnergySpecToRigiditySpec(energyValuesInMeV,energyDistributionValues,particleMassAU = 1.0,particleChargeAU = 1.0)\n```\n\nreturns\n```\n Rigidity Rigidity distribution values\n0 1.696038 875.025647\n1 2.784437 473.822152\n2 3.824870 194.241037\n3 4.848317 98.178407\n4 5.863678 9.874384\n```\nas a [Pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html).\n\nThe function `convertParticleRigiditySpecToEnergySpec` can be used to perform the opposite operation, converting particle rigidity to kinetic energy. For example, \n\n```\nrigiditySpec = PRCT.convertParticleEnergySpecToRigiditySpec(energyValuesInMeV,energyDistributionValues,particleMassAU = 1,particleChargeAU = 1)\n\nPRCT.convertParticleRigiditySpecToEnergySpec(rigiditySpec[\"Rigidity\"],rigiditySpec[\"Rigidity distribution values\"],particleMassAU = 1,particleChargeAU = 1)\n```\n\nreturns\n```\n Energy Energy distribution values\n0 1000.0 1.00\n1 2000.0 0.50\n2 3000.0 0.20\n3 4000.0 0.10\n4 5000.0 0.01\n```\nthe original kinetic energies and distribution values that were used for the energy distribution.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library containing tools for dealing with conversions between particle energy and rigidity",
"version": "1.5.16",
"project_urls": {
"Homepage": "https://github.com/ssc-maire/ParticleRigidityCalculationTools"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e72e13963afd37b61838fff7deddc038b2df8fa5a1fbc30db5ccd359a600946d",
"md5": "7b4c3e7e3fa006bc9f805f7391f1aeb4",
"sha256": "e3d15de579f639bbfeb7b0a8f950663dbfd3aae9f5215ba0c179230fa6862d95"
},
"downloads": -1,
"filename": "ParticleRigidityCalculationTools-1.5.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b4c3e7e3fa006bc9f805f7391f1aeb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10511,
"upload_time": "2024-09-02T13:01:55",
"upload_time_iso_8601": "2024-09-02T13:01:55.072667Z",
"url": "https://files.pythonhosted.org/packages/e7/2e/13963afd37b61838fff7deddc038b2df8fa5a1fbc30db5ccd359a600946d/ParticleRigidityCalculationTools-1.5.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bf415e296140f6fff2900c4ea3a979f6878cba5cc7a2547fdbac8eec1c1572d4",
"md5": "8910a030d25f34d4fa6c5ded5869fd3f",
"sha256": "796163fb4da5ef3e9cf85d0a1ecfc215ac042a7ed568742aef5b8b71acdc1282"
},
"downloads": -1,
"filename": "particlerigiditycalculationtools-1.5.16.tar.gz",
"has_sig": false,
"md5_digest": "8910a030d25f34d4fa6c5ded5869fd3f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10223,
"upload_time": "2024-09-02T13:01:56",
"upload_time_iso_8601": "2024-09-02T13:01:56.222118Z",
"url": "https://files.pythonhosted.org/packages/bf/41/5e296140f6fff2900c4ea3a979f6878cba5cc7a2547fdbac8eec1c1572d4/particlerigiditycalculationtools-1.5.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 13:01:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ssc-maire",
"github_project": "ParticleRigidityCalculationTools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "particlerigiditycalculationtools"
}
JSON
