MhdUnitsManager

class PlasmaCalcs.mhd.mhd_units.MhdUnitsManager(units='si', *, M=1, l=1, t=1, q=1, K=1, sic_quantities=None)

Bases: UnitsManager

units manager with the from_mhd method,

which determines all units based on u_l, u_t, u_r, and mu0_raw.

Note: cgs units for electromagnetic quantities are not supported here,

because cgs electromagnetic equations differ from SI equations,

e.g. cgs includes extra factors of 4*pi or c in various places.

How to infer electromagnetic units from t, l, r, and mu0?

Internally, this method determines:

u_M = u_r * u_l**3 # mass

u_N = u_M * u_l * u_t**-2 # energy (Newtons in SI)

Amperes units:

(mu0 [si]) = u_N * u_A**-2 * (mu0 [raw])
–> u_A = sqrt(u_N * (mu0 [raw]) / (mu0 [si]))
where mu0 [si] == DEFAULTS.PHYSICAL.CONSTANTS_SI[‘mu0’], approx. 4 * pi * 1e-7.

Which yields, for charge units:

u_q = u_A * u_t

At which point, we have u_l, u_t, u_M, and u_q,

which is sufficient to infer all other units (aside from K for temperature)

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

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(‘speed0.5 m-1’) == self(‘speed’)**0.5 * self(‘m’)**-1

self.known_systems tells all the systems known by self, e.g.:

‘si’, ‘cgs’, ‘raw’.

call self.si_bases(…) to convert to SI base units representation, e.g.:

self.si_bases(‘force’) == ‘kg m s-2’

Implementation notes:

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_physical_constants_raw() 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().

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 any key of self.systems. 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 any key of self.systems. 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_mhd`([units, mu0_raw, K])	create a MhdUnitsManager from u_l, u_t and u_r, the SI conversion factors.
`from_mhd_cgs`([units, mu0_raw, K])	create a BifrostUnitsManager from ucgs_l, ucgs_t and ucgs_r, the CGS conversion factors.
`get_sic_factor`(ustr)	Get conversion factor from raw units to SI units.
`get_system`(key)	return self.systems[key], but raise clear error message if crash.
`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).
`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_contents`()	returns list of contents to include in repr(self).
`_repr_show_factors`()	returns dict of name and conversion factor to si, to include in repr(self).
`_systems_default`()	returns default value for self.systems.

Attributes

`BASES`
`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`
`known_systems`	list of all systems known by self, including 'si' and 'raw'
`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
`si_bases`	alias to string_to_si_bases
`systems`	dict of {name: UnitsManager} for other systems known by this instance.
`t`	Time_si = t * Time_raw

static 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.

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.

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 any key of self.systems.: 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 any key of self.systems.: 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_contents(): returns list of contents to include in repr(self).

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

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

Also include mu0_raw if it is not 1.

_systems_default(): returns default value for self.systems.

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_mhd(units='si', *, u_l, u_t, u_r, mu0_raw=1, K=1): create a MhdUnitsManager from u_l, u_t and u_r, the SI conversion factors.

CAUTION: these are the SI conversion factors. NOT cgs.

(some MHD simulations, like Bifrost, use similar names for the CGS factors.)

units: ‘si’ or ‘raw’

by default, outputs of the resulting UnitsManager convert to this unit system.

Can easily change later by setting result.units to a different value.

u_l: number

length [si] = u_l * length [raw]

u_t: number

time [si] = u_l * time [raw]

u_r: number

mass density [si] = u_r * mass density [raw]

mu0_raw: number, default 1

value of mu0 in ‘raw’ units system. Used to infer Amperes units via:

u_M = u_r * u_l**3 # mass

u_N = u_M * u_l * u_t**-2 # energy (Newtons in SI)

mu0_si = u_N * u_A**-2 * mu0_raw

u_A = sqrt(u_N * mu0_raw / mu0_si)

where mu0_si == DEFAULTS.PHYSICAL.CONSTANTS_SI[‘mu0’], approx. 4 * pi * 1e-7.

K: number, default 1

temperature [si] = K * temperature [raw]

classmethod from_mhd_cgs(units='si', *, ucgs_l, ucgs_t, ucgs_r, mu0_raw=1, K=1)

create a BifrostUnitsManager from ucgs_l, ucgs_t and ucgs_r, the CGS conversion factors.

units: ‘si’ or ‘raw’

by default, outputs of the resulting UnitsManager convert to this unit system.

Can easily change later by setting result.units to a different value.

ucgs_l: number

length [cgs] = ucgs_l * length [raw]

ucgs_t: number

time [cgs] = ucgs_t * time [raw]

ucgs_r: number

mass density [cgs] = ucgs_r * mass density [raw]

mu0_raw: number, default 1

value of mu0 in ‘raw’ units system. Used to infer Amperes units via:

u_M = u_r * u_l**3          # mass
u_N = u_M * u_l * u_t**-2   # energy (Newtons in SI)
mu0_si = u_N * u_A**-2 * mu0_raw
u_A = sqrt(u_N * mu0_raw / mu0_si)

where mu0_si == DEFAULTS.PHYSICAL.CONSTANTS_SI[‘mu0’], approx. 4 * pi * 1e-7.

K: number, default 1

temperature [cgs] = K * temperature [raw]

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.

get_system(key): return self.systems[key], but raise clear error message if crash.

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 known_systems: list of all systems known by self, including ‘si’ and ‘raw’

Equivalent: [‘si’] + list(self.systems) + ‘raw’

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.

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

property si_bases: alias to string_to_si_bases

string_to_si_bases(string_of_units): convert string of any units to string of SI base units.

property systems: dict of {name: UnitsManager} for other systems known by this instance.

For example, might put {‘R_E’: UnitsManager(l=R_earth_si)},

then self.u(‘l’, ‘R_E’, ‘si’) converts lengths to earth radii.

(R_earth_si must be provided, you might provide 6.3781e6 for example).

By default, this is just {‘cgs’: self.CGS_UNITS_DEFAULT()},

but subclasses and instances might add more.

property t: Time_si = t * Time_raw