# IonizationStateCollection

class plasmapy.particles.ionization_state_collection.IonizationStateCollection(inputs: ~typing.Union[~typing.Dict[str, ~numpy.ndarray], ~typing.List, ~typing.Tuple], *, T_e: Unit("K") = <Quantity nan K>, abundances: ~typing.Optional[~typing.Dict[str, ~numbers.Real]] = None, log_abundances: ~typing.Optional[~typing.Dict[str, ~numbers.Real]] = None, n0: Unit("1 / m3") = <Quantity nan 1 / m3>, tol: ~numbers.Real = 1e-15, kappa: ~numbers.Real = inf)

Bases: object

Describe the ionization state distributions of multiple elements or isotopes.

Parameters
Raises

ParticleError – If IonizationStateCollection cannot be instantiated.

Examples

>>> from astropy import units as u
>>> from plasmapy.particles import IonizationStateCollection
>>> states = IonizationStateCollection(
...     {'H': [0.5, 0.5], 'He': [0.95, 0.05, 0]},
...     T_e = 1.2e4 * u.K,
...     n0 = 1e15 * u.m ** -3,
...     abundances = {'H': 1, 'He': 0.08},
... )
>>> states.ionic_fractions
{'H': array([0.5, 0.5]), 'He': array([0.95, 0.05, 0.  ])}


The number densities are given by the ionic fractions multiplied by the abundance and the number density scaling factor n0.

>>> states.number_densities['H']
<Quantity [5.e+14, 5.e+14] 1 / m3>
>>> states['He'] = [0.4, 0.59, 0.01]


To change the ionic fractions for a single element, use item assignment.

>>> states = IonizationStateCollection(['H', 'He'])
>>> states['H'] = [0.1, 0.9]


Item assignment will also work if you supply number densities.

>>> states['He'] = [0.4, 0.6, 0.0] * u.m ** -3
>>> states.ionic_fractions['He']
array([0.4, 0.6, 0. ])
>>> states.number_densities['He']
<Quantity [0.4, 0.6, 0. ] 1 / m3>


Notes

No more than one of abundances and log_abundances may be specified.

If the value provided during item assignment is a Quantity with units of number density that retains the total element density, then the ionic fractions will be set proportionately.

When making comparisons between IonizationStateCollection instances, nan values are treated as equal. Equality tests are performed to within a tolerance of tol.

Attributes Summary

 T_e The electron temperature. abundances The elemental abundances. base_particles A list of the elements and isotopes whose ionization states are being kept track of. ionic_fractions A dict containing the ionic fractions for each element and isotope. kappa The κ parameter for a kappa distribution function for electrons. log_abundances A dict with atomic or isotope symbols as keys and the base 10 logarithms of the relative abundances as the corresponding values. n0 The number density scaling factor. n_e The electron number density under the assumption of quasineutrality. number_densities A dict containing the number densities for the elements and/or isotopes composing the collection. tol The absolute tolerance for comparisons.

Methods Summary

 average_ion(*[, include_neutrals, ...]) Return a CustomParticle representing the mean particle included across all ionization states. Normalize the ionic fractions so that the sum for each element equals one. summarize([minimum_ionic_fraction]) Print quicklook information.

Attributes Documentation

T_e

The electron temperature.

abundances

The elemental abundances.

base_particles

A list of the elements and isotopes whose ionization states are being kept track of.

ionic_fractions

A dict containing the ionic fractions for each element and isotope.

The keys of this dict are the symbols for each element or isotope. The values will be ndarray objects containing the ionic fractions for each ionization level corresponding to each element or 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 equals inf, then the distribution function reduces to a Maxwellian.

log_abundances

A dict with atomic or isotope symbols as keys and the base 10 logarithms of the relative abundances as the corresponding values.

n0

The number density scaling factor.

n_e

The electron number density under the assumption of quasineutrality.

number_densities

A dict containing the number densities for the elements and/or isotopes composing the collection.

tol

The absolute tolerance for comparisons.

Methods Documentation

average_ion(*, include_neutrals: bool = True, use_rms_charge: bool = False, use_rms_mass: bool = False)

Return a CustomParticle representing the mean particle included across all ionization states.

By default, this method will use the weighted mean to calculate the properties of the CustomParticle, where the weights for each ionic level is given by its ionic fraction multiplied by the abundance of the base element or isotope. 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
Raises

ParticleError – If the abundance of any of the elements or isotopes is not defined and the IonizationStateCollection instance includes more than one element or isotope.

Return type

CustomParticle

Examples

>>> states = IonizationStateCollection(
...     {"H": [0.1, 0.9], "He": [0, 0.1, 0.9]},
...     abundances={"H": 1, "He": 0.1}
... )
>>> states.average_ion()
CustomParticle(mass=2.12498...e-27 kg, charge=1.5876...e-19 C)
>>> states.average_ion(include_neutrals=False, use_rms_charge=True, use_rms_mass=True)
CustomParticle(mass=2.633...e-27 kg, charge=1.805...e-19 C)

normalize() None

Normalize the ionic fractions so that the sum for each element equals one.

summarize(minimum_ionic_fraction: Real = 0.01)

Print quicklook information.

Parameters

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

Examples

>>> states = IonizationStateCollection(
...     {'H': [0.1, 0.9], 'He': [0.95, 0.05, 0.0]},
...     T_e = 12000 * u.K,
...     n0 = 3e9 * u.cm ** -3,
...     abundances = {'H': 1.0, 'He': 0.1},
...     kappa = 3.4,
... )
>>> states.summarize()
IonizationStateCollection instance for: H, He
----------------------------------------------------------------
H  0+: 0.100    n_i = 3.00e+14 m**-3    T_i = 1.20e+04 K
H  1+: 0.900    n_i = 2.70e+15 m**-3    T_i = 1.20e+04 K
----------------------------------------------------------------
He  0+: 0.950    n_i = 2.85e+14 m**-3    T_i = 1.20e+04 K
He  1+: 0.050    n_i = 1.50e+13 m**-3    T_i = 1.20e+04 K
----------------------------------------------------------------
n_e = 2.71e+15 m**-3
T_e = 1.20e+04 K
kappa = 3.40
----------------------------------------------------------------