IonizationState

class plasmapy.particles.ionization_state.IonizationState(particle: plasmapy.particles.particle_class.Particle, ionic_fractions=None, *, T_e: Unit("K") = <Quantity nan K>, T_i: Unit("K") = None, kappa: numbers.Real = inf, n_elem: Unit("1 / m3") = <Quantity nan 1 / m3>, tol: Union[float, int] = 1e-15)

Bases: object

Representation of the ionization state distribution of a single element or isotope.

Parameters
  • particle (ParticleLike) – A str or Particle instance representing an element, isotope, or ion; or an integer representing the atomic number of an element.

  • ionic_fractions (ndarray, list, tuple, or Quantity; optional) – The ionization fractions of an element, where the indices correspond to the charge number. This argument should contain the atomic number plus one items, and must sum to one within an absolute tolerance of tol if dimensionless. Alternatively, this argument may be a Quantity that represents the number densities of each neutral/ion. This argument cannot be specified when particle is an ion.

  • T_e (Quantity, keyword-only, optional) – The electron temperature or thermal energy per electron.

  • n_elem (Quantity, keyword-only, optional) – The number density of the element, including neutrals and all ions.

  • tol (float or integer, keyword-only, optional) – The absolute tolerance used by isclose and similar functions when testing normalizations and making comparisons. Defaults to 1e-15.

Raises
  • ParticleError – If the ionic fractions are not normalized or contain invalid values, or if number density information is provided through both ionic_fractions and n_elem.

  • InvalidParticleError – If the particle is invalid.

See also

IonicLevel, plasmapy.particles.IonizationStateCollection

Examples

>>> states = IonizationState('H', [0.6, 0.4], n_elem=1*u.cm**-3, T_e=11000*u.K)
>>> states.ionic_fractions[0]  # fraction of hydrogen that is neutral
0.6
>>> states.ionic_fractions[1]  # fraction of hydrogen that is ionized
0.4
>>> states.n_e  # electron number density
<Quantity 400000. 1 / m3>
>>> states.n_elem  # element number density
<Quantity 1000000. 1 / m3>

If the input particle is an ion, then the ionization state for the corresponding element or isotope will be set to 1.0 for that ion. For example, when the input particle is an alpha particle, the base particle will be He-4, and all He-4 particles will be set as doubly charged.

>>> states = IonizationState('alpha')
>>> states.base_particle
'He-4'
>>> states.ionic_fractions
array([0., 0., 1.])

Initialize an IonizationState instance.

Attributes Summary

T_e

The electron temperature.

T_i

The ion temperature.

Z_mean

Return the mean charge number.

Z_most_abundant

A list of the charge numbers with the highest ionic fractions.

Z_rms

The root mean square charge number.

atomic_number

The atomic number of the element.

base_particle

The symbol of the element or isotope.

charge_numbers

An array of the charge numbers.

element

The atomic symbol of the element.

integer_charges

Deprecated since version 0.7.0.

ionic_fractions

The ionic fractions, where the index corresponds to the charge number.

ionic_symbols

The ionic symbols for all charge states.

isotope

The isotope symbol for an isotope, or None if the particle is not an isotope.

kappa

The κ parameter for a kappa distribution function for electrons.

n_e

The electron number density assuming a single species plasma.

n_elem

The total number density of neutrals and all ions.

number_densities

The number densities for each state.

tol

The absolute tolerance for comparisons.

Methods Summary

average_ion(*[, include_neutrals, ...])

Return a CustomParticle instance representing the average particle in this ionization state.

normalize()

Normalize the ionization state distribution (if set) so that the sum of the ionic fractions becomes equal to one.

summarize([minimum_ionic_fraction])

Print quicklook information for an IonizationState instance.

to_list()

Return a ParticleList of the ionic levels.

Attributes Documentation

T_e

The electron temperature.

T_i

The ion temperature. If the ion temperature has not been provided, then this attribute will provide the electron temperature.

Z_mean

Return the mean charge number.

Z_most_abundant

A list of the charge numbers with the highest ionic fractions.

Examples

>>> He = IonizationState('He', [0.2, 0.5, 0.3])
>>> He.Z_most_abundant
[1]
>>> Li = IonizationState('Li', [0.4, 0.4, 0.2, 0.0])
>>> Li.Z_most_abundant
[0, 1]
Z_rms

The root mean square charge number.

atomic_number

The atomic number of the element.

base_particle

The symbol of the element or isotope.

charge_numbers

An array of the charge numbers.

element

The atomic symbol of the element.

integer_charges

Deprecated since version 0.7.0: The integer_charges attribute of IonizationState has been deprecated and will be removed in a future release. Use charge_numbers instead.

An array of the charge numbers.

ionic_fractions

The ionic fractions, where the index corresponds to the charge number.

Examples

>>> hydrogen_states = IonizationState('H', [0.9, 0.1])
>>> hydrogen_states.ionic_fractions
array([0.9, 0.1])
ionic_symbols

The ionic symbols for all charge states.

isotope

The isotope symbol for an isotope, or None if the particle is not an isotope.

kappa

The κ parameter for a kappa distribution function for electrons.

The value of kappa must be greater than 1.5 in order to have a valid distribution function. If kappa is inf, then the distribution function reduces to a Maxwellian.

n_e

The electron number density assuming a single species plasma.

n_elem

The total number density of neutrals and all ions.

number_densities

The number densities for each state.

tol

The absolute tolerance for comparisons.

This attribute is used as the atol parameter in numpy.isclose, numpy.allclose, astropy.units.isclose, and astropy.units.allclose when testing normalizations and making comparisons.

Methods Documentation

average_ion(*, include_neutrals: bool = True, use_rms_charge: bool = False, use_rms_mass: bool = False) plasmapy.particles.particle_class.CustomParticle

Return a CustomParticle instance representing the average particle in this ionization state.

By default, the weighted mean will be used as the average, with the ionic fractions as the weights. If use_rms_charge or use_rms_mass is True, then this method will return the root mean square of the charge or mass, respectively.

Parameters
  • include_neutrals (bool, optional, keyword-only) – If True, include neutrals when calculating the mean values of the different particles. If False, exclude neutrals. Defaults to True.

  • use_rms_charge (bool, optional, keyword-only) – If True, use the root mean square charge instead of the mean charge. Defaults to False.

  • use_rms_mass (bool, optional, keyword-only) – If True, use the root mean square mass instead of the mean mass. Defaults to False.

Returns

Return type

CustomParticle

Examples

>>> state = IonizationState("He", [0.1, 0.9, 0.0])
>>> state.average_ion()
CustomParticle(mass=6.645657...e-27 kg, charge=1.44...e-19 C)
>>> state.average_ion(include_neutrals=False)
CustomParticle(mass=6.6455660...e-27 kg, charge=1.602...e-19 C)
>>> state.average_ion(use_rms_charge=True, use_rms_mass=True)
CustomParticle(mass=6.645657...e-27 kg, charge=1.519958...e-19 C)
normalize() None

Normalize the ionization state distribution (if set) so that the sum of the ionic fractions becomes equal to one.

This method may be used, for example, to correct for rounding errors.

summarize(minimum_ionic_fraction: numbers.Real = 0.01) None

Print quicklook information for an IonizationState instance.

Parameters

minimum_ionic_fraction (Real) – If the ionic fraction for a particular ionization state is below this level, then information for it will not be printed. Defaults to 0.01.

Examples

>>> He_states = IonizationState(
...     'He',
...     [0.941, 0.058, 0.001],
...     T_e = 5.34 * u.K,
...     kappa = 4.05,
...     n_elem = 5.51e19 * u.m ** -3,
... )
>>> He_states.summarize()
IonizationState instance for He with Z_mean = 0.06
----------------------------------------------------------------
He  0+: 0.941    n_i = 5.18e+19 m**-3    T_i = 5.34e+00 K
He  1+: 0.058    n_i = 3.20e+18 m**-3    T_i = 5.34e+00 K
----------------------------------------------------------------
n_elem = 5.51e+19 m**-3
n_e = 3.31e+18 m**-3
T_e = 5.34e+00 K
kappa = 4.05
----------------------------------------------------------------
to_list() plasmapy.particles.particle_collections.ParticleList

Return a ParticleList of the ionic levels.