UnitsManagerPIC

class PlasmaCalcs.units.units_manager_pic.UnitsManagerPIC(units='si', *, M=1, l=1, t=1, q=1, K=1, sic_quantities=None)

Bases: UnitsManager

units manager with the from_pic method, and some other helpful PIC things.

Manages units, including conversion factors and physical constants in different unit systems.

— UnitsManagerPIC.help() will print a helpful message: —

BASES tells all the SI base unit symbols.

KNOWN tells all the known conversions between symbols (just strings, not numerical values).

PHYSICAL_CONSTANTS_SI tells all the known physical constants, as tuples of (SI value, units string)).

physical_constants_raw (or pcr) tells all the known physical constants, in ‘raw’ units;

first do self.populate_pcr() to calculate them all.

self.sic tells all the known values for unit conversions, from raw to SI.

e.g., Mass [raw] * self.sic[‘M’] == Mass [si].

new conversion factors are cached here the first time they are calculated,

to avoid recalculating the values multiple times.

to remove all cached values, self.clear_sic().

call the object to get conversion factor. E.g.:

density_si = density_raw * self(‘r’, ‘si’, ‘raw’)

density_raw = density_si * self(‘r’, ‘raw’, ‘si’)

or call the object to get physical constant. E.g.:

c_si = self(‘c’, ‘si’) # speed of light in ‘si’ units

c_raw = self(‘c’, ‘raw’) # speed of light in ‘raw’ units.

Conversion factors can be combined and raised to powers, e.g.:

self(‘u0.5 m-1’) == self(‘u’)**0.5 * self(‘m’)**-1

Methods

__call__(ustr[, units, convert_from, alt])	return quantity or conversion factor in the specified unit system. ustr: str physical constant or quantity (e.g. "c" for speed of light or "M" for mass units) units: UNSET, None, 'si', 'raw', or 'cgs' unit system to convert to. UNSET --> units = self.alts.get(alt, self.units). (Equivalent to None if alt is None) None --> use self.units. convert_from: 'si', 'raw', or 'cgs' unit system to convert from. Ignored if ustr is a quantity (e.g. "c") instead of conversion factor (e.g. "mass") alt: object (probably None or str) if units is UNSET, use units = self.alts.get(alt, self.units) otherwise, alt must be None. :return: a converted physical constant or a conversion factor.
CGS_UNITS_DEFAULT()	UnitsManager for cgs units.
calc_sic_factor(ustr)	Calculate conversion factor from raw units to SI units.
clear_sic()	clear self.sic.
from_pic([units, u_l, u_t, u_n, ne, ne_si, ...])	create a UnitsManagerPIC from pic parameters.
get_sic_factor(ustr)	Get conversion factor from raw units to SI units.
help()	prints a helpful message about using cls.
init_sic()	initialize self.sic from self.bases.
is_trivial()	returns whether self has only trivial conversion factors in it (all factors 1 or not provided).
pic_ambiguous_unit([u_l, u_t, u_n, ne, ne_si])	Returns dict of u_l and u_t.
populate_physical_constants_raw([quantities])	Calculate all the physical constants in raw units. :param quantities: None or iterable of strings calculate only these physical constants. if None, use self.PHYSICAL_CONSTANTS_SI.keys() :return: self.physical_constants_raw, after creating and filling it.
populate_sic([quantities, reset])	Calculate lots of conversion factors. :param quantities: None or iterable of strings calculate these conversion factors and put them in self.sic. e.g. "p", "momentum", "M u", "kg m s-1". if None, use self.SIC_QUANTITIES. :reset: bool, default False. if True, clear self.sic before calculating. :return: self.sic, after adding all the requested conversion factors.
string_to_si_bases(string_of_units)	convert string of any units to string of SI base units.
_base_unit_property(longname)	create property for base unit -- link to self.bases[ustr].
_init_from_bases()	initialize all other parts of self, using self.bases (and self._init_sic_quantities).
_repr_show_factors()	returns dict of name and conversion factor to si, to include in repr(self).

Attributes

BASES
CGS_UNITS	UnitsManager for cgs units.
K	Temperature_si = K * Temperature_raw
KNOWN
M	Mass_si = M * Mass_raw
PHYSICAL_CONSTANTS_SI
SIC_QUANTITIES
alts	dict of {key: units} for alternative objects' unit systems.
display_precision
l	Length_si = l * Length_raw
pcr	alias to physical_constants_raw
physical_constants_raw	dict of all the physical constants in raw units.
q	Charge_si = q * Charge_raw
t	Time_si = t * Time_raw

property CGS_UNITS

UnitsManager for cgs units. Default is UnitsManager(M=1e-3, l=1e2, t=1, q=None, K=1).

q=None is the default because electromagnetic cgs units are ambiguous,

there are multiple options for how to convert to si and the equations differ.

Note that for CGS_UNITS, ‘raw’ means ‘cgs’.

Feel free to set self.CGS_UNITS = a new UnitsManager with a known q,

if you have decided on a specific cgs system to remove relevant ambiguities.

classmethod CGS_UNITS_DEFAULT()

UnitsManager for cgs units. Default is UnitsManager(M=1e-3, l=1e2, t=1, q=None, K=1).

q=None is the default because electromagnetic cgs units are ambiguous,

there are multiple options for how to convert to si and the equations differ.

Note that for the CGS_UNITS result,’raw’ means ‘cgs’.

property K

Temperature_si = K * Temperature_raw

property M

Mass_si = M * Mass_raw

__call__(ustr, units=UNSET, convert_from='raw', *, alt=None)

return quantity or conversion factor in the specified unit system. ustr: str

physical constant or quantity (e.g. “c” for speed of light or “M” for mass units)

units: UNSET, None, ‘si’, ‘raw’, or ‘cgs’

unit system to convert to. UNSET –> units = self.alts.get(alt, self.units). (Equivalent to None if alt is None) None –> use self.units.

convert_from: ‘si’, ‘raw’, or ‘cgs’

unit system to convert from. Ignored if ustr is a quantity (e.g. “c”) instead of conversion factor (e.g. “mass”)

alt: object (probably None or str)

if units is UNSET, use units = self.alts.get(alt, self.units) otherwise, alt must be None.

Returns:

a converted physical constant or a conversion factor

_base_unit_property(longname)

create property for base unit – link to self.bases[ustr]. re-initialize self if changed.

_init_from_bases()

initialize all other parts of self, using self.bases (and self._init_sic_quantities).

_repr_show_factors()

returns dict of name and conversion factor to si, to include in repr(self).

Here, include l, t, M, and q. Also include K if it is not 1.

property alts

dict of {key: units} for alternative objects’ unit systems.

e.g. CoordsUnitsHaver might set alts[‘coords’] = ‘si’ to indicate coords always in si.

calc_sic_factor(ustr)

Calculate conversion factor from raw units to SI units. Also save result in self.sic for future use. :param ustr: string of units (e.g. “m-3”) :return: conversion factor from raw units to SI units

clear_sic()

clear self.sic. delete self.sic, then do self.init_sic()

classmethod from_pic(units='si', *, u_l=None, u_t=None, u_n=None, ne=None, ne_si=None, qe=None, me=None, eps0=None, qe_si=None, me_si=None, eps0_si=None, M=None, q=None, u_eps=None, **kw_init)

create a UnitsManagerPIC from pic parameters. ‘raw’ units refers to the units from the PIC code.

REQUIRED PARAMETERS

There is an ambiguity in the units from a PIC code (e.g. from eppic). Indicate length or time units in one of the following ways:

u_l: length [si] = u_l * length [raw] u_t: time [si] = u_t * time [raw] u_n: number density [si] = u_n * number density [raw] ne and ne_si: number density n for electrons; ne = n [raw]; ne_si = n [si]

OPTIONAL PARAMETERS

param qe:

None or value absolute value of electron charge [raw units]. if None, use cls._PIC_DEFAULTS[‘qe’]. Default: SI value of qe.

param me:

None or value electron mass [raw units]. if None, use cls._PIC_DEFAULTS[‘me’]. Default: SI value of me.

param eps0:

None or value permittivity of free space [raw units]. if None, use cls._PIC_DEFAULTS[‘eps0’]. Default: SI value of epsilon0

param qe_si, me_si, eps0_si:

None or value optionally, specify a non-traditional SI value for electron charge, electron mass, and/or epsilon0.

param M, q, u_eps:

None or value if provided, set u_M = M, u_q = q, or u_eps=u_eps, and ignore info about me, qe, or eps0.

get_sic_factor(ustr)

Get conversion factor from raw units to SI units. If not already calculated, calculate it first. :param ustr: string of units (e.g. “m-3”) :return: conversion factor from raw units to SI units

if None, raise UnitsUnknownError instead.

classmethod help()

prints a helpful message about using cls.

init_sic()

initialize self.sic from self.bases.

is_trivial()

returns whether self has only trivial conversion factors in it (all factors 1 or not provided).

property l

Length_si = l * Length_raw

property pcr

alias to physical_constants_raw

property physical_constants_raw

dict of all the physical constants in raw units.

static pic_ambiguous_unit(u_l=None, u_t=None, u_n=None, ne=None, ne_si=None)

Returns dict of u_l and u_t.

Requires that u_l or u_t can be determined, but not both.

raise InputConflictError if too many inputs; InputMissingError if not enough inputs.

Indicate length or time units in one of the following ways:

u_l: length [si] = u_l * length [raw] u_t: time [si] = u_t * time [raw] u_n: number density [si] = u_n * number density [raw]

ne and ne_si: number density n for electrons; ne = n [raw]; ne_si = n [si]

DEFAULTS.pic_ambiguous_unit can be set to a dict of default values instead;

if DEFAULTS.pic_ambiguous_unit exists, use it when all inputs to this function are None.

E.g. DEFAULTS.pic_ambiguous_unit = dict(u_t=1) –> pic seconds are SI seconds, by default.

Ignored when any input is not None (or when providing ne or ne_si but not both).

populate_physical_constants_raw(quantities=None)

Calculate all the physical constants in raw units. :param quantities: None or iterable of strings

calculate only these physical constants. if None, use self.PHYSICAL_CONSTANTS_SI.keys()

Returns:

self.physical_constants_raw, after creating and filling it.

populate_sic(quantities=None, *, reset=False)

Calculate lots of conversion factors. :param quantities: None or iterable of strings

calculate these conversion factors and put them in self.sic. e.g. “p”, “momentum”, “M u”, “kg m s-1”. if None, use self.SIC_QUANTITIES.

Reset:

bool, default False. if True, clear self.sic before calculating.

Returns:

self.sic, after adding all the requested conversion factors.

property q

Charge_si = q * Charge_raw

string_to_si_bases(string_of_units)

convert string of any units to string of SI base units.

property t

Time_si = t * Time_raw