IonMixture

class PlasmaCalcs.mhd.multifluid.mhd_fluids.IonMixture(species, i=None, *, q=UNSET, name=UNSET, m_mean_mode='simple', m_tol=UNSET)

Bases: MhdFluid

Fluid corresponding to multiple ions grouped together, e.g. Mg+Al+Si_II

CAUTION: some code assumes (without checking) that IonMixture objects are immutable.

Changing an IonMixture after creating it could lead to unexpected behavior.

IonMixtures usually have a name. Every IonMixture has a charge (probably charge=1).

Name and charge can be inferred from the species in the mixture.

species: iterable of Specie or dict objects

the list of Species in this mixture. length must be at least 1.

internally stored as SpecieList(species)

dicts –> convert to SpecieList via SpecieList.from_dicts(species).

i: None or int

the index of this mixture (within an IonMixtureList or MhdFluidList)

None –> cannot convert self to int.

q: UNSET or number

charge, in elementary charge units (e.g. +1 for H_II).

all species must have the same charge else raise NotImplementedError.

UNSET –> infer q from species.

number –> assert q > 0, and q == spec.q for spec in species.

name: UNSET, None, or str

name of this mixture. None –> unnamed.

UNSET –> infer from species. E.g. Mg_II, Al_II, Si_II –> Mg+Al+Si_II

m_mean_mode: str in {‘simple’, ‘density’}

how to calculate the mass of this mixture.

‘simple’ –> m = mean(spec.m for spec in species). This is a constant.

‘density’ –> m = density weighted mean of spec.m for spec in species.

this might vary across maindims and snaps…

m_tol: UNSET, None, or number

crash if any |m_s - mean(m)| is more than m_tol * mean(m).

(using simple mean for this test, regardless of m_mean_mode)

(Prevents accidentally creating a mixture of ions with very different masses.)

UNSET –> use self.DEFAULT_M_TOL (default=0.1)

None –> allow any masses.

Methods

__eq__(v)	return self==v.
__init_subclass__(*[, _serial_typename])	register cls as a subclass of XarrayIoSerializable.
array_equals(other)	return whether self == other (which is assumed to be a numpy array or xarray.DataArray).
copy(**kw_init)	return a copy of self.
deserialize(serial)	creates an XarrayIoSerializable object from a serialized representation.
equal_except_i(v)	returns whether self == v (another DimensionValue), ignoring i.
from_dict(d)	return cls from dict d.
get_element([default])	return self.element if it exists and is not None, else crash with FluidKeyError.
get_elements([default])	return list of elements in self, i.e. spec.get_element() for spec in self.
infer_name()	infer name based on species' names.
ion([q])	return ionized Specie of self.get_element()
is_charged()	tells whether self is a charged fluid.
is_electron()	tells whether self is an electron.
is_ion()	tells whether self is an ion.
is_neutral()	tells whether self is a neutral fluid.
is_nonelectron()	tells whether self is not an electron, i.e. self.q >= 0.
lookup_dict()	return dict for looking up self within a DimensionValueList, given int, str, or self.
neutral(**kw_specie)	return neutral Specie of self.get_element().
register_type(cls_to_register[, ...])	register cls_to_register as a serializable subclass of XarrayIoSerializable.
saha_list(*[, istart])	return SpecieList of neutral & once-ionized ions of self.get_element().
serialize()	return dict of info about self, including 'typename' key.
to_dict(*[, species_to_dict])	return dictionary of info about self.
with_i(i)	return copy of self with i=i, or self if self.i==i already.
_assert_array_equals(other)	raise DimensionValueError unless self.array_equals(other).
_assert_single(vals, *[, meaning])	assert len(vals)==1.
_check_m_tol()	crash if any |m_s - mean(m)| is more than m_tol * mean(m).
_repr_contents()	contents used by self.__repr__
_repr_simple()	return simple repr for self: Classname(s, i).

Attributes

DEFAULT_M_TOL_DENSITY
DEFAULT_M_TOL_SIMPLE
SERIAL_TYPES
get	return self.species.get(key)
get_I	alias to neutral
get_II	alias to ion
m_mean	return mean mass of species in this mixture.
m_mean_mode	str telling how to calculate the mass of this mixture.
name	alias to s
ndim
size

__eq__(v)

return self==v. Equal if:

- v is an instance of type(self), and

all kw from both self._kw_eq and v._kw_eq have the same values.

(any kw missing attrs will be treated as UNSET.)

For DimensionValue, just compares self.s==v.s and self.i==v.i.

Subclasses may add more kwargs to compare by altering _kw_def.

- or, self.s == v or self.i == v, and v is not another DimensionValue

- or, v is a DimensionSingleValueSpecifier and v.checker(self) gives True.

Not equal if v is a DimensionValue but not an instance of type(self),

e.g. class Fluid(DimensionValue):…; class Snap(DimensionValue):…;

Fluid(‘H’, 0) != Snap(‘H’, 0).

classmethod __init_subclass__(*, _serial_typename=None, **kw)

register cls as a subclass of XarrayIoSerializable.

_serial_typename: None or str

name to use for this type, for serialization purposes.

None –> use cls.__name__.

This method also sets cls._serial_typename = _serial_typename.

_assert_array_equals(other)

raise DimensionValueError unless self.array_equals(other).

classmethod _assert_single(vals, *, meaning='value')

assert len(vals)==1. Raise DimensionKeyError if len==0; DimensionValueError if len>=2.

meaning can be provided to clarify what vals should represent, in case of crash;

error message will be ‘expected exactly 1 {meaning}, but got {len(vals)}’.

This check tends to make more sense coming from a DimensionValueList,

but it is convenient to attach here too in case of using isel from an array.

_check_m_tol()

crash if any |m_s - mean(m)| is more than m_tol * mean(m).

return max(|m_s - mean(m)| / mean(m)).

_dimension_key_error

alias of FluidKeyError

_dimension_value_error

alias of FluidValueError

_repr_contents()

contents used by self.__repr__

_repr_simple()

return simple repr for self: Classname(s, i).

if s is None, use Classname(i) instead.

if i is None, use Classname(s, i=None) instead.

Called when using PlasmaCalcs.tools.repr_simple.

array_equals(other)

return whether self == other (which is assumed to be a numpy array or xarray.DataArray).

return False if other.size != 1. Else, compare to other.item().

(Extremely convenient if comparing to xarray DataArray or numpy array,

with potentially unknown size / dimensionality.

Also, convenient if “self” might be DimensionValueList instead,

because DimensionValueList also provides an array_equals method.)

copy(**kw_init)

return a copy of self. Can provide new kwargs here to override old values in result.

E.g. self.copy(i=7) makes a copy of self but with i=7 instead of self.i.

static deserialize(serial)

creates an XarrayIoSerializable object from a serialized representation.

serial: dict or str

str –> convert to dict via ast.literal_eval.

dict must contain ‘typename’ key.

The output here will be an instance of XarrayIoSerializable.SERIAL_TYPES[typename]

element_cls

alias of Element

equal_except_i(v)

returns whether self == v (another DimensionValue), ignoring i.

equal if v is an instance of type(self) and

all kw from both self._kw_eq and v._kw_eq have the same values.

(any kw missing attrs will be treated as UNSET.)

For DimensionValue: self.s==v.s and self.i==v.i. Subclasses may add more.

classmethod from_dict(d)

return cls from dict d.

If ‘d’ contains ‘typename’, result is like cls.deserialize(d) instead,

however, first require that result is an instance of cls (or subclass of cls).

E.g. Fluid.from_dict(dict(typename=’EppicDist’, …)) returns EppicDist,

but Snap.from_dict(dict(typename=’EppicDist’, …)) crashes with InputError.

Subclasses wishing to alter deserialize behavior will probably override this method instead.

property get

return self.species.get(key)

property get_I

alias to neutral

property get_II

alias to ion

get_element(default=NO_VALUE)

return self.element if it exists and is not None, else crash with FluidKeyError.

default: NO_VALUE or any value.

If provided, when element missing or None, return default instead of crash.

get_elements(default=NO_VALUE)

return list of elements in self, i.e. spec.get_element() for spec in self.

infer_name()

infer name based on species’ names.

if all species’ names have the same suffix (starting at underscore),

‘+’.join(names without suffix) + suffix.

else, ‘+’.join(names).

ion(q=1, **kw_specie)

return ionized Specie of self.get_element()

q: charge in elementary charge units. (default: +1)

is_charged()

tells whether self is a charged fluid. i.e. self.q != 0.

if self.q is None, returns None instead of bool.

is_electron()

tells whether self is an electron. i.e. self.q < 0.

if self.q is None, returns None instead of bool.

is_ion()

tells whether self is an ion. i.e. self.q > 0.

if self.q is None, returns None instead of bool.

is_neutral()

tells whether self is a neutral fluid. i.e. self.q == 0.

if self.q is None, returns None instead of bool.

is_nonelectron()

tells whether self is not an electron, i.e. self.q >= 0.

if self.q is None, returns None instead of bool.

lookup_dict()

return dict for looking up self within a DimensionValueList, given int, str, or self.

(used by DimensionValueList.lookup_dict)

in addition to being able to lookup self,

also allows lookup of any species within self, by name or object (but not index).

E.g. if H_II=Specie(‘H_II’, i=3) in self,

result will include {‘H_II’: H_II, H_II: H_II}, but will not include {3: H_II}

property m_mean

return mean mass of species in this mixture.

(Always using a simple mean: sum(s.m for s in species)/len(species))

property m_mean_mode

str telling how to calculate the mass of this mixture.

‘simple’ –> m = mean(spec.m for spec in species). This is a constant.

‘density’ –> m = density weighted mean of spec.m for spec in species.

this might vary across maindims and snaps…

property name

alias to s

neutral(**kw_specie)

return neutral Specie of self.get_element().

static register_type(cls_to_register, _serial_typename=None)

register cls_to_register as a serializable subclass of XarrayIoSerializable.

_serial_typename: str or None

name to use for serialization. if None, use cls_to_register.__name__.

saha_list(*, istart=0, **kw_specie)

return SpecieList of neutral & once-ionized ions of self.get_element().

istart: start index for the SpecieList. Index affects conversion to int.

serialize()

return dict of info about self, including ‘typename’ key.

specie_cls

alias of Specie

specie_list_cls

alias of SpecieList

to_dict(*, species_to_dict=True)

return dictionary of info about self. Attribute values for keys in self._kw_def.

species_to_dict: bool, default True

whether to also convert result[‘species’].to_dict() too.

with_i(i)

return copy of self with i=i, or self if self.i==i already.