Addresses #35 Adds coupling parameter for #49 Heavily expands Coulomb logarithm for #154

Adding a bunch of transport functionality and re-arranging some functions within transport.py. Much of the additions are based off of Gericke, Murillo, and Schlanges (2002) for extending Coulomb logarithm to the dense plasma case where quantum effects become important. To that end, I am also adding a coupling parameter function, which is handy for determining which regime a plasma is in. The coupling parameter itself is quite involve and requires things like: ideal chemical potential, Fermi integral, polylogarithms.

I am also adding functions for collision frequency and mean free path (which I believe I wrote based off of F. F. Chen's book).

Charged particle radiography detectors are usually comprised of multiple layers of active medium, each of which detects different energies of particles based on their Bragg peak. This PR adds a couple objects that represent these detector stacks and calculates the energies deposited in each layer using stopping power data from NIST.

This is Step 1 of adding support for detector stacks. Step 2, in a future PR, will create a new synthetic_radiograph function that takes a film stack object and produces a synthetic radiograph in each layer.

~~This PR depends on #1486 and should be merged after that PR~~ Done

This PR adds a file plasmapy/diagnostics/thomson.py which contain a code for simulating Thomson scattering spectra for Maxwellian plasmas in both the collective and non-collective regimes.

An associated file of tests is also added: plasmapy/diagnostics/tests/test_thomson.py. This file contains two tests that run the program in two regimes (collective and non-collective) and make sure the results match their current output values.

Working on Issue #35 . I've put in some functionality and done some preliminary checks and tests. Definitely still a work in progress, needs tests and documentation and then is going to need some ruthless refactoring. Oh shoot, and the PEP8 checking-thing is going to have a fit.

Resolves #1699

This pull request moves plasmapy.formulary.collisons.fundamental_ion_collision_freq and plasmapy.formulary.collisons.fundamental_electron_collision_freq to CollisionFrequencies.

• [x] I have added a changelog entry for this pull request.
• [x] If adding new functionality, I have added tests and docstrings.
• [x] I have fixed any newly failing tests.

Related to Issue #759 Extension on to functionality introduced in PR #833

This introduces the from_json method for the Particle, CustomParticle, and DimensionlessParticle classes that converts from a JSON representation to the appropriate particle object.

• [x] I have added a changelog entry for this pull request (please see changelog/README.rst for instructions, and if you need help with picking the PR type, ask!)
• [x] If adding new functionality, I have added (passing) tests and docstrings. (Tests pop up at the bottom, in the checks box).
• [x] I have fixed any new failing tests (if you're unsure why they're failing, ask!).

Suggestions and advice is appreciated :)

Thank you!

The use of Thomson scattering as a diagnostic depends on the ability to extract plasma parameters (eg. density, temperature, flow velocity) from scattered light spectra. One of the design uses for the diagnostics.thomson.spectral_density function would be as part of a fit function to curve fit experimental data to extract these parameters. As such, I've received requests to develop a function for fitting TS data.

This function provides a lmfit.Model function (thomson.thomson_model) with which the user can apply any of the lmfit fitting algorithms and other features to Thomson scattering data. The example notebook exhibits in detail how this is done.

** EDIT **

This PR was starting to get big, so I've restricted its scope thus:

This PR

• Basic Thomson fitting lmfit model function.
• Changes to thomson.spectral_density necessary to make the fitting work.
• One example notebook that demonstrates fitting
• Minor easy speed improvements.

Future PRs

• Optimize thomson.spectral_density and sub-functions to make the fitting algorithm fast enough for research (#1085)
• Create a function that estimates the errors in a Thomson fit (or maybe more generally in an lmfit result?). PR to come

When dealing with plasma waves, it would be helpful to have a dispersion relation solver.

This was recommended by John Raymond. I believe Carl Sovinec wrote a code that this several years ago, though not in python.

This PR creates a new sets of objects within the 'plasmapy.plasma' package:

Child classes of 'grids.AbstractGrid' represent 3D grids of positions in various coordinate systems. Further subclasses can provide special types of grids - for example 'IrregularCartesianGrid' is a non-uniformly spaced Cartesian grid for testing post-processing scripts meant for irregularly gridded simulation outputs.

This PR originated as part of the proton radiography module (PR #895 ) and must be merged before that module can be finalized. In the meantime, that PR serves as an example of one usecase for these objects. The same grid objects could potentially also be useful input forms for simulations, etc.

• [x] Add methods for calculating volume-averaging values over the grid at a position (at least for CartesianGrid with uniform spacing...)

I realized the current volume weighted interpolator in grids.CartesianGrid was incorrect. This PR fixes that.

Here's an example of the old interpolator: the linear interpolation between data points is backwards!

And here it is with the corrected algorithm

I haven't yet found a good implementation of this algorithm to copy, so my code probably isn't the most efficient. The diagram below shows the idea in 2D

The particle position "p" is surrounded by a box of size dx * dy. The four surrounding grid points are similarly surrounded. The weight for the field from each grid point is then the area (volume in 3D) of the overlap between the particle box and the box for each grid point.

Proton radiography is an increasingly common diagnostic technique used to interrogate the electric and magnetic fields inside high energy density plasmas. The plasma of interest is positioned between a bright pulsed source of protons and a detector plane. Electric and magnetic fields in the plasma deflect the protons, producing patterns on the detector. Since this represents a non-linear and line-integrated measurement of the fields, the interpretation of these "proton radiographs" is a complicated business. The goal of this module is to provide tools for planning these experiments and analyzing their results.

Eventually, this new module should contain two type different types of functions:

1. Functions that construct synthetic proton radiographs given simulated or calculated fields, either for planning an experiment or analyzing the results of one.

2. Functions that use assumptions about symmetries etc. to "invert" experimental radiographs to recover the magnitudes of the fields that created them.

The SyntheticProtonRadiograph object contained in this initial PR belongs to the first category. The SyntheticProtonRadiograph object is initialized with a plasmapy.plasma.grid.AbstractGrid subclass containing electric and magnetic fields, as well as the locations of the proton source and detector. A particle tracing algorithm is then run to determine the trajectories of the protons, and the resulting positions in the detector plane are used to create a synthetic radiograph (2D histogram).

This function can currently support field data on either regular or non-uniform (although the former is much faster) to support complicated simulation meshes. Time steps are computed in an adaptive manner based on both the fields currently experienced by the particles and the grid resolution. Source and detector positions can be specified anywhere in Cartesian, cylindrical, or spherical coordinates systems to re-create geometric effects.

The example fields generated within the function for testing and demonstration are intentionally simple, but this technique can re-create complicated structures, such as this off-axis radiograph of a cylindrical, radial electric field:

This PR adds particle scattering and stopping in dense matter to the charged particle radiography Tracker class. This capability is important for charged particle radiography in dense plasmas where these effects significantly affect the radiograph.

Builds on #1799, so merge that first.

Note: should compare this implementation of scattering + stopping to the MPRAD code described here: https://aip.scitation.org/doi/full/10.1063/1.5123392

Replaces a previous PR (#1802) because I needed to completely refactor after #1799

This PR makes the following changes:

• Changed the signature of CustomParticle to CustomParticle(*quantities, ...), where quantities can include Quantity objects of physical type mass or charge, or (as its last item) the symbol. See #1873 for some motivation and follow-up discussion. This is a follow-up attempt to do more or less the same thing as #1364, which didn't get merged. Closes #1873.
• Fixed a new edge case in the particle factory function by assuming that a string passed as the first positional argument to it is meant for Particle and not as a symbol for CustomParticle.
• Made ParticleList.__init__ accept an iterable containing Quantity objects. Closes #1872.
• Made ParticleList methods accept Quantity objects of mass or electrical charge.

The changes to CustomParticle made the changes to ParticleList pretty straightforward to implement, so I addressed them here.

This PR should make it easier to address #1869 and #1871.

Feature description

I'd like it to be possible to put the mass and charge of a CustomParticle in either order as positional arguments. For example, I would like to be able to do:

>>> CustomParticle(1 * u.C)
>>> CustomParticle(1 * u.kg)
>>> CustomParticle(1 * u.kg, 1 * u.C)
>>> CustomParticle(1 * u.C, 1 * u.kg)

Motivation

While working on #1871 and #1872, I've been having to do a bunch of special handling for when the input to CustomParticle is a charge or a mass, including when writing tests. Code downstream of CustomParticle will be cleaner if we have this flexibility.

Implementation strategy

Right now the signature of CustomParticle.__init__ is:

def __init__(self, mass: u.kg = None, charge: (u.C, Real) = None, symbol=None):

I'd like to be able to do CustomParticle(1e-27 * u.kg) or CustomParticle(1e-18 * u.C), which would correspond to a signature like:

def __init__(self, *quantities, symbol=None):

This change would lead to breaking changes, so we might want to retain mass and charge as keyword arguments, even if we deprecate them. We could perhaps even make it so that if a string is provided in quantities, it would get interpreted as the symbol (though quantities might not be the best name in that case).

Additional context

This is inspired by #1364 and discussed further in #1872. This should be addressed after #1866 is merged since they're both working on the same section of code.

Feature description

Right now if we try to create a ParticleList using a Quantity array, we get an InvalidParticleError:

>>> import astropy.units as u
>>> ParticleList([5, 6] * u.kg)
plasmapy.particles.exceptions.InvalidParticleError: The object 5.0 kg supplied to ParticleList is not a particle-like object.

What I'd like to happen is for a CustomParticle to be created based on each element of the Quantity array, i.e.:

>>> ParticleList([5, 6] * u.kg)
ParticleList(['CustomParticle(mass=5.0 kg, charge=nan C)', 'CustomParticle(mass=6.0 kg, charge=nan C)'])

Motivation

As part of the refactoring of particle_input in #1057, we're making it so that a Quantity of physical type mass or electrical charge will be used to construct a CustomParticle instance. I discovered in #1871 that ParticleList works for Quantity non-arrays but not for Quantity arrays. The code downstream of ParticleList will be cleaner and have fewer special cases to handle if ParticleList can handle Quantity iterables of these physical types.

Implementation strategy

We'll need to make these changes to not only ParticleList.__init__, but also the append, extend, and insert methods.

There's some repeated code in these methods, so it might be worth creating a private function that does the particleification or particlizing.

Additional context

Implementing this would probably be cleaner by allowing mass and charge as positional arguments in either order in CustomParticle, kind of like what I attempted in #1364, but maybe having a signature like CustomParticle(*quantities, mass: Optional[u.kg] = None, charge=Optional[u.C] = None, symbol: Optional[str]=None).

Description

• Applied particle_input to relativistic_energy and RelativisticBody
• Updated docstrings
• Changed the parameters provided to relativistic_energy:
  • Changed m to particle
  • Changed v to V This would be a breaking change; however, when provided as positional arguments, the change would be transparent. In particular, particle_input would create a CustomParticle from a Quantity for mass.

Motivation and context

The goals here are

• To further implement particle_input in plasmapy.formulary for more compatibility with ParticleList and CustomParticle objects.
• To improve consistency with function signatures. For example, we mostly use V instead of v to describe velocity, and it helps to be consistent.

I'm wondering if it would be worth having a deprecation warning for this and still accept the old parameters as keywords, but relativistic_energy might not be widely used enough to warrant the extra complexity this would entail.

Related issues

This is approximately 4% of #341!

Feature description

A decorator that attaches references (as BibTex entries?) to objects in PlasmaPy. A helper function would then exist that, given a list of functions, would assemble a list of references (recursively) for that object.

For example, if the user's code relies on X, but X relies on Y and Z, then the reference manager should return the references associated with all three, perhaps saved as output to a text file that can be directly copied in to Bibtex.

The helper function could also (maybe by setting a keyword?) include citations for other packages used within the PlasmaPy functionality (e.g. scipy, numpy, etc.)

Inspired by: https://github.com/duecredit/duecredit

Motivation

• Provides a natural place to record relevant references in the code, and consequently adding and updating these references would be covered by the existing code review process.
• Encourage citation of software!

Implementation strategy

See feature description

Additional context

No response