Update classes & docs for ionization states and fix docstring formatting in plasmapy.particles

changelog/796.breaking.rst

@@ -0,0 +1,10 @@
+In `plasmapy.particles`, the ``IonizationStates`` class was renamed to
+`~plasmapy.particles.IonizationStateCollection`.  The argument ``n`` in
+``IonizationStates`` was changed to ``n0`` in
+`~plasmapy.particles.IonizationStateCollection`.  The ``State`` namedtuple
+was changed to the `~plasmapy.particles.IonicFraction` class.  When the
+`~plasmapy.particles.IonizationState` class is now provided with an ion,
+the ionic fraction for that ion is set to 100% for the corresponding
+element or isotope.  ``AtomicError`` was renamed to
+`~plasmapy.particles.exceptions.ParticleError` and ``MissingAtomicDataError``
+was renamed to `~plasmapy.particles.exceptions.MissingParticleDataError`.

changelog/796.doc.rst

@@ -0,0 +1 @@
+Add narrative documentation on ionization state functionality.

docs/api_static/plasmapy.particles.ionization_state_collection.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+`plasmapy.particles.ionization_state_collection`
+================================================
+
+.. currentmodule:: plasmapy.particles.ionization_state_collection
+
+.. automodapi::  plasmapy.particles.ionization_state_collection
+   :include-all-objects:
+   :no-heading:

docs/particles/decorators.rst

@@ -18,7 +18,7 @@ class.  The arguments must be annotated with `~plasmapy.particles.Particle`
 so that the decorator knows to create the `~plasmapy.particles.Particle`
 instance.  The function can then access particle properties by using
 `~plasmapy.particles.Particle` attributes.  This decorator will raise an
-`~plasmapy.utils.InvalidParticleError` if the input does not correspond
+`~plasmapy.particles.exceptions.InvalidParticleError` if the input does not correspond
 to a valid particle.
 
 .. code-block:: python
@@ -57,10 +57,10 @@ decorator enables several ways to allow this.
 
 If an annotated keyword is named ``element``, ``isotope``, or ``ion``;
 then `~plasmapy.particles.particle_input` will raise an
-`~plasmapy.utils.InvalidElementError`,
-`~plasmapy.utils.InvalidIsotopeError`, or
-`~plasmapy.utils.InvalidIonError` if the particle is not associated with
-an element, isotope, or ion; respectively.
+`~plasmapy.particles.exceptions.InvalidElementError`,
+`~plasmapy.particles.exceptions.InvalidIsotopeError`, or
+`~plasmapy.particles.exceptions.InvalidIonError` if the particle is not
+associated with an element, isotope, or ion; respectively.
 
 .. code-block:: python
 

docs/particles/functional.rst

@@ -134,7 +134,7 @@ unstable), `~plasmapy.particles.half_life` returns infinity seconds.
 
 If the particle's half-life is not known to sufficient precision, then
 `~plasmapy.particles.half_life` returns a `str` with the estimated value
-while issuing a `~plasmapy.particles.exceptions.MissingAtomicDataWarning`.
+while issuing a `~plasmapy.particles.exceptions.MissingParticleDataWarning`.
 
 Additional Properties
 =====================

docs/particles/index.rst

@@ -23,6 +23,7 @@ Submodules
    particle_class
    functional
    nuclear
+   ionization_states
    decorators
 
 See Also

docs/particles/ionization_states.rst

@@ -0,0 +1,163 @@
+.. _ionization-state-data-structures:
+
+Ionization state data structures
+********************************
+
+The ionization state (or charge state) of a plasma refers to the
+fraction of an element that is at each ionization level.  For example,
+the ionization state of a pure helium plasma could be 5% He⁰⁺, 94% He¹⁺,
+and 1% He²⁺.
+
+The ionization state of a single element
+========================================
+
+We may use the `~plasmapy.particles.IonizationState` class
+to represent the ionization state of a single element, such as for this
+example.
+
+>>> from plasmapy.particles import IonizationState
+>>> ionization_state = IonizationState("He", [0.05, 0.94, 0.01])
+
+The ionization state for helium may be accessed using the
+``ionic_fractions`` attribute.  These ionic fractions correspond to the
+``integer_charges`` attribute.
+
+>>> ionization_state.ionic_fractions
+array([0.05, 0.94, 0.01])
+>>> ionization_state.integer_charges
+array([0, 1, 2])
+
+The ``Z_mean`` attribute returns the mean integer charge averaged
+over all particles in that element.
+
+>>> ionization_state.Z_mean
+0.96
+
+The ``Z_rms`` attribute returns the root mean square integer charge.
+
+>>> ionization_state.Z_rms
+0.9899...
+
+The ``Z_most_abundant`` attribute returns a `list` of the most abundant
+ion(s).  The `list` may contain more than one integer charge in case of
+a tie.
+
+>>> ionization_state.Z_most_abundant
+[1]
+
+The ``summarize`` method prints out the ionic fraction for the ions with
+an abundance of at least 1%.
+
+>>> ionization_state.summarize()
+IonizationState instance for He with Z_mean = 0.96
+----------------------------------------------------------------
+He  0+: 0.050
+He  1+: 0.940
+He  2+: 0.010
+----------------------------------------------------------------
+
+The number density of the element may be specified through the
+``n_elem`` keyword argument.
+
+>>> import astropy.units as u
+>>> ionization_state = IonizationState(
+...     "He", [0.05, 0.94, 0.01], n_elem = 1e19 * u.m ** -3,
+... )
+
+The ``n_e`` attribute provides the electron number density as a
+`~astropy.units.Quantity`.
+
+>>> ionization_state.n_e
+<Quantity 9.6e+18 1 / m3>
+
+The ``number_densities`` attribute provides the number density of each
+ion or neutral.
+
+>>> ionization_state.number_densities
+<Quantity [5.0e+17, 9.4e+18, 1.0e+17] 1 / m3>
+
+Ionization states for multiple elements
+=======================================
+
+The `~plasmapy.particles.IonizationStateCollection` class may be used to
+represent the ionization state for multiple elements. This can be used,
+for example, to describe the various impurities in a fusion plasma or
+the charge state distributions of different elements in the solar wind.
+
+>>> from plasmapy.particles import IonizationStateCollection
+
+The minimal input to `~plasmapy.particles.IonizationStateCollection` is a `list`
+of the elements or isotopes to represent.  Integers in the `list` will
+be treated as atomic numbers.
+
+>>> states = IonizationStateCollection(["H", 2])
+
+To set the ionic fractions for hydrogen, we may do item assignment.
+
+>>> states["H"] = [0.9, 0.1]
+
+We may use indexing to retrieve an `~plasmapy.particles.IonizationState`
+instance for an element.
+
+>>> states["H"]
+<IonizationState instance for H>
+
+The ionization states for all of the elements may be specified directly
+as arguments to the class.
+
+>>> states = IonizationStateCollection(
+...     {"H": [0.01, 0.99], "He": [0.04, 0.95, 0.01]},
+...     abundances={"H": 1, "He": 0.08},
+...     n0 = 5e19 * u.m ** -3,
+... )
+
+The ionic fractions will be stored as a `dict`.
+
+>>> states.ionic_fractions
+{'H': array([0.01, 0.99]), 'He': array([0.04, 0.95, 0.01])}
+
+The number density for each element is the product of the number
+density scaling factor ``n0`` with that element's abundance.
+The number density for each ion is the product of ``n0``, the
+corresponding element's abundance, and the ionic fraction.
+
+>>> states.n0
+<Quantity 5.e+19 1 / m3>
+>>> states.abundances
+{'H': 1.0, 'He': 0.08}
+>>> states.number_densities["H"]
+<Quantity [5.00e+17, 4.95e+19] 1 / m3>
+
+The
+corresponding element's abundance, and the ionic fraction.
+
+>>> states.n0
+<Quantity 5.e+19 1 / m3>
+>>> states.abundances
+{'H': 1.0, 'He': 0.08}
+>>> states.number_densities["H"]
+<Quantity [5.00e+17, 4.95e+19] 1 / m3>
+
+The
+corresponding element's abundance, and the ionic fraction.
+
+>>> states.n
+<Quantity 5.e+19 1 / m3>
+>>> states.abundances
+{'H': 1.0, 'He': 0.08}
+>>> states.number_densities["H"]
+<Quantity [5.00e+17, 4.95e+19] 1 / m3>
+
+The `~plasmapy.particles.IonizationStates.summarize` method may also be
+used to get a summary of the ionization states.
+
+>>> states.summarize()
+----------------------------------------------------------------
+H  1+: 0.990    n_i = 4.95e+19 m**-3
+----------------------------------------------------------------
+He  0+: 0.040    n_i = 1.60e+17 m**-3
+He  1+: 0.950    n_i = 3.80e+18 m**-3
+----------------------------------------------------------------
+n_e = 5.34e+19 m**-3
+T_e = 1.30e+04 K
+----------------------------------------------------------------

plasmapy/particles/__init__.py

@@ -21,14 +21,15 @@
     standard_atomic_weight,
 )
 from plasmapy.particles.decorators import particle_input
-from plasmapy.particles.ionization_state import IonizationState, State
-from plasmapy.particles.ionization_states import IonizationStates
+from plasmapy.particles.ionization_state import IonicFraction, IonizationState
+from plasmapy.particles.ionization_state_collection import IonizationStateCollection
 from plasmapy.particles.nuclear import nuclear_binding_energy, nuclear_reaction_energy
 from plasmapy.particles.particle_class import (
     AbstractParticle,
     CustomParticle,
     DimensionlessParticle,
     Particle,
+    particle_like,
 )
 from plasmapy.particles.serialization import (
     json_load_particle,