mahautils.multics.MahaMulticsUnitConverter¶

class mahautils.multics.MahaMulticsUnitConverter¶

Bases: UnitConverter

A unit converter using the SI system of units, pre-filled with common units

This class is identical in function to a UnitConveter, with the exception that it has been initialized with a number of commonly-used units. All units in a UnitConveterSI are defined in terms of the SI system (https://www.nist.gov/pml/owm/metric-si/si-units), with the following sequence of seven base units (used in the Unit.base_unit_exps attribute of all units in the unit converter):

Mass: kilogram [\(kg\)]
Length: meter [\(m\)]
Time: second [\(s\)]
Temperature: Kelvin [\(K\)]
Amount of substance: mole [\(mol\)]
Electric current: ampere [\(A\)]
Luminous intensity: candela [\(cd\)]

For a list of units available by default, please refer to the Unit Converter Default Units page.

Methods

__init__()

Creates a new unit converter using the SI system of units and populated with commonly-used units.

Inherited Attributes

unit_system

The system of units used by all units in the unit converter

Inherited Methods

`add_alias`(key, aliases[, overwrite])	Add one or more aliases for a unit
`add_unit`(key, unit[, tags, name, ...])	Adds a unit to the unit converter
`clear`()
`convert`(quantity, from_unit, to_unit)	Converts a quantity from one unit in the `UnitConverter` to another
`copy`()
`fromkeys`([value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`get_aliases`(unit)	Retrieves a list of aliases for a particular unit in the unit converter
`is_convertible`(unit1, unit2, *args)	Checks whether units can be converted between each other
`is_defined_unit`(unit)	Checks whether a simple or complex unit is composed exclusively of units which have been defined in the unit converter
`is_simplified_unit`(unit)	Evaluates whether a unit is a fully-simplified unit
`items`()
`keys`()
`list_tags`()	Returns a list of all tags currently used in the `UnitConverter` instance
`pop`(k[,d])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`search`(search_term[, search_fields, ...])	Searches the `UnitConverter` contents for a given term
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`str_to_unit`(unit)	Converts a string to a `Unit` object using units defined in the `UnitConverter`
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()

__init__()¶

Creates a new unit converter using the SI system of units and populated with commonly-used units.

Creates an new UnitConverterSI instance. This unit converter uses the SI system (specifically, the system of units referenced by UnitSystemSI) and is pre-filled with a set of commonly-used units.

add_alias(key: str, aliases: str | List[str] | Tuple[str, ...], overwrite: bool = False) → None¶

Add one or more aliases for a unit

Adds alternate identifiers (keys) that may be used to identify a unit in simple or compound unit strings. This method is useful for adding units which have multiple equivalent representations, such as “micron” and “μm,” to the unit converter efficiently.

Parameters:

key (str) – The unit identifier of a unit already in the unit converter for which to add an alias
aliases (str or list or tuple) – Alternate identifiers to add to unit converter
overwrite (bool, optional) – Whether to overwrite units if they already exist in the unit converter (default is False)

Warning

Aliased units are added to the UnitConverter by reference. Thus, if one of the aliased units is modified, all the other aliased units will also be updated.

Adds a unit to the unit converter

Adds a unit and possibly unit metadata (tags, description) to the unit converter, so that the unit can be used to perform later unit conversions.

Parameters:

key (str) – A short string, such as 'kg', uniquely identifying the unit
unit (Unit) – A Unit object (or subclass) specifying the unit
tags (TypedList or list or tuple or str, optional) – One or more strings containing brief, one-word descriptors to use to group similar units, such as “length” or “speed” (default is None, meaning that no tags are associated with the unit)
name (str, optional) – A name for the unit (default is None)
description (str, optional) – A written description of the unit (default is None)
aliases (str or list or tuple, optional) – Alternate identifiers to add to unit converter (default is None). Refer to the add_alias() method documentation for more detail about unit aliases
overwrite (bool, optional) – Whether to overwrite units if they already exist in the unit converter (default is False)

clear() → None. Remove all items from D.¶

convert(quantity: ndarray | list | tuple | float, from_unit: str, to_unit: str) → ndarray¶

Converts a quantity from one unit in the UnitConverter to another

Converts a value or array from one unit to another, where the units can be either units in the unit converter, or compound units composed of units in the unit converter.

Parameters:

quantity (np.ndarray or list or tuple or float) – Value(s) to convert from from_unit to to_unit
from_unit (str) – String specifying the simple or compound unit of quantity
to_unit (str) – String specifying the simple or compound unit to which quantity is to be converted

Returns:

NumPy array with the same shape as quantity containing the value(s) in quantity converted from from_unit to to_unit

Return type:

np.ndarray

copy() → a shallow copy of D¶

fromkeys(value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

get_aliases(unit: str) → List[str]¶

Retrieves a list of aliases for a particular unit in the unit converter

This method identifies all keys in the unit converter that are aliases of a particular unit.

Parameters:: unit (str) – The identifier of the unit for which to search for aliases
Returns:: A list of strings containing all identifiers in the unit converter which are aliases of unit
Return type:: list

is_convertible(unit1: str, unit2: str, *args: str) → bool¶

Checks whether units can be converted between each other

Checks whether two or more units are compatible and can be directly converted between each other. Inputs can be strings of simple or compound units. The corresponding units (or component units of compound units) must exist in the UnitConverter before calling this method.

Parameters:

unit1 (str) – Key/identifier of the first unit to check
unit2 (str) – Key/identifier of the second unit to check
*args (str, optional) – Keys/identifiers of any other units to check

Returns:

Whether all units can be converted directly between each other

Return type:

bool

is_defined_unit(unit: str) → bool¶

Checks whether a simple or complex unit is composed exclusively of units which have been defined in the unit converter

This method verifies that a simple unit or all component units of a compound unit have been defined in the unit converter; if not, unit conversions involving such a unit cannot be performed.

Parameters:: unit (str) – The simple or compound unit to analyze
Returns:: Whether all component unit(s) in unit are defined in the unit converter
Return type:: bool

is_simplified_unit(unit: str) → bool¶

Evaluates whether a unit is a fully-simplified unit

Returns whether a unit is NOT a compound unit. Fully-simplified units can be added to the UnitConverter, but compound units cannot. Note that units that are not of type str or which are enclosed in brackets (such as '(m)') are not considered fully-simplified.

Parameters:: unit (str) – The unit to check
Returns:: Whether unit is fully-simplified and can be added to the UnitConverter
Return type:: bool

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

list_tags() → List[str]¶

Returns a list of all tags currently used in the UnitConverter instance

Returns:: List (in alphabetical order) of all tags used by any unit in the unit converter
Return type:: list

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

Searches the UnitConverter contents for a given term

Once a unit converter has a large number of units, it can be challenging to remember all included units. This method provides a simple way to search the contents of a UnitConverter, either interactively (on the command line) or programmatically (in a script).

Parameters:

search_term (str) – The term to search for. Any units in which search_term is found in the fields specified by search_fields will be returned. Set search_term to '*' or '**' to match any string
search_fields (list or tuple or str, optional) – The fields of each entry in the UnitConverter to search. Valid options are any of ('key', 'name', 'tags', 'description') (default is to search all valid fields)
filter_by_tags (list or tuple or str, optional) – Only units with tags specified by filter_by_tags will be included in the search results. Set to None disable filtering by tags (default is None)
hide_aliases (bool, optional) – Whether to hide unit aliases when outputting search results (default is False). Refer to the add_alias() method documentation for more detail about unit aliases
print_results (bool, optional) – Whether to print search results to the terminal (default is True)
return_results (bool, optional) – Whether to return a list containing search results (default is False)

Returns:

Returns a list of strings containing the UnitConverter keys for any units matching the specified search criteria if return_results is True. Otherwise, no outputs are returned

Return type:

list or None

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

str_to_unit(unit: str) → Unit¶

Converts a string to a Unit object using units defined in the UnitConverter

Parses a string containing a simple or compound unit, converting it to a Unit object. All simple units and all component units in compound units must be defined in the unit converter prior to calling this method.

Parameters:: unit (str) – String containing the simple or compound unit to parse
Returns:: A Unit object representation of the unit specified by unit
Return type:: Unit

property unit_system: UnitSystem¶: The system of units used by all units in the unit converter

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values¶