IonizationStates

class plasmapy.atomic.IonizationStates(inputs: Union[Dict[str, numpy.ndarray], List[T], Tuple], *, T_e: Unit("K") = <Quantity nan K>, equilibrate: Optional[bool] = None, abundances: Optional[Dict[str, numbers.Real]] = None, log_abundances: Optional[Dict[str, numbers.Real]] = None, n: 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
  • inputs (list, tuple, or dict) – A list or tuple of elements or isotopes (if T_e is provided); a list of IonizationState instances; a dict with elements or isotopes as keys and a ndarray of ionic fractions as the values; or a dict with elements or isotopes as keys and Quantity instances with units of number density.

  • abundances (dict or str, optional, keyword-only) – The relative abundances of each element in the plasma.

  • log_abundances (dict, optional, keyword-only) – The base 10 logarithm of the relative abundances of each element in the plasma.

  • n (Quantity, optional, keyword-only) – The number density scaling factor. The number density of an element will be the product of its abundance and n.

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

  • kappa (float, optional, keyword-only) – The value of kappa for a kappa distribution function.

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

  • equilibrate (bool, optional, keyword-only) – Set the ionic fractions to the estimated collisional ionization equilibrium. Not implemented.

Raises

AtomicError – If IonizationStates cannot be instantiated.

Examples

>>> from astropy import units as u
>>> from plasmapy.atomic import IonizationStates
>>> states = IonizationStates(
...     {'H': [0.5, 0.5], 'He': [0.95, 0.05, 0]},
...     T_e = 1.2e4 * u.K,
...     n = 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

>>> 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 = IonizationStates(['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, log_abundances, and number_densities 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 IonizationStates instances, nan values are treated as equal. Equality tests are performed to within a tolerance of tol.

Collisional ionization equilibrium is based on atomic data that has relative errors of order 20%.

Attributes Summary

T_e

Return the electron temperature.

abundances

Return the elemental abundances.

base_particles

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

ionic_fractions

Return a dict containing the ionic fractions for each element and isotope.

kappa

Return the kappa parameter for a kappa distribution function for electrons.

log_abundances

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

n

Return the number density scaling factor.

n_e

Return the electron number density under the assumption of quasineutrality.

number_densities

Return a dict containing the number densities for element or isotope.

tol

Return the absolute tolerance for comparisons.

Methods Summary

equilibrate(T_e, particles, kappa)

Set the ionic fractions to collisional ionization equilibrium.

info(minimum_ionic_fraction)

Print quicklook information for an IonizationStates instance.

normalize()

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

Attributes Documentation

T_e

Return the electron temperature.

abundances

Return the elemental abundances.

base_particles

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

ionic_fractions

Return 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

Return the kappa 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

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

n

Return the number density scaling factor.

n_e

Return the electron number density under the assumption of quasineutrality.

number_densities

Return a dict containing the number densities for element or isotope.

tol

Return the absolute tolerance for comparisons.

Methods Documentation

equilibrate(T_e: Unit("K") = <Quantity nan K>, particles: str = 'all', kappa: numbers.Real = inf)

Set the ionic fractions to collisional ionization equilibrium. Not implemented.

The electron temperature used to calculate the new equilibrium ionic fractions will be the argument T_e to this method if given, and otherwise the attribute T_e if no electon temperature is provided to this method.

Parameters
  • T_e (Quantity, optional) – The electron temperature.

  • particles (list, tuple, or str, optional) – The elements and isotopes to be equilibrated. If particles is 'all' (default), then all elements and isotopes will be equilibrated.

  • kappa (Real) – The value of kappa for a kappa distribution for electrons.

info(minimum_ionic_fraction: numbers.Real = 0.01) → None

Print quicklook information for an IonizationStates 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

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

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