Documentation
Below is documentation for the various features in this module!
Supported Conversions
Metric Conversions
Below are the supported metric prefixes handled in this package:
'y': 1e-24
'z': 1e-21
'a': 1e-18
'f': 1e-15
'p': 1e-12
'n': 1e-9
'µ': 1e-6
'mc': 1e-6 # for those who cannot use the µ symbol
'm': 1e-3
'c': 1e-2
'd': 1e-1
'da': 1e1
'h': 1e2
'k': 1e3
'M': 1e6
'G': 1e9
'T': 1e12
'P': 1e15
'E': 1e18
'Z': 1e21
'Y': 1e24
And here are the supported units for converting metric:
's', 'm', 'g', 'K', 'mol', 'J', 'W', 'N', 'Pa', 'L'
Conversion Factors
Below is a list of supported units for conversions for each conversion type. It contains the unit, followed by its conversion factor to the chosen reference unit for the conversion group (conversion factor is simply what you multiply a measurement in that unit by to get the number of reference units).
Length Conversions
The reference unit used for this is meters.
'ft': 0.3048 # feet
'yd': 0.9144 # yards
'in': 0.0254 # inches
'mi': 1609 # miles
'ly': 946e13 # light years
'au': 1496e8 # astronomical units
'pc': 31e15 # parsecs
'm': 1 # meters
Weight / Mass Conversions
The reference unit used for this is grams.
'g': 1 # grams
'lb': 454 # pounds
'oz': 454 / 16 # ounces
'st': 6356 # stones
'amu': 1.661e-24 # atomic mass units
Time Conversions
The reference unit used for this is seconds.
's': 1 # seconds
'min': 60 # minutes
'hr': 3600 # hours
'dy': 3600 * 24 # days
'wk': 3600 * 24 * 7 # weeks
'yr': 3600 * 24 * 365.25 # year
Volume Conversions
The reference unit used for this is liters.
'L': 1 # liters
'c.': 0.2366, # cups
'pt.': 0.2366 * 2 # pints
'qt.': 0.2366 * 4 # quarts
'gal.': 0.2366 * 16 # gallons
'fl. oz': 0.2366 / 8 # fluid ounces
'tbsp': 0.2366 / 16 # tablespoons
'tsp': 0.2366 / 48 # teaspoons
Temperature Conversions
The reference unit used for this is Kelvin. Note: these are absolute temperature conversions (not in reference to the boiling point of water like traditional Celsius and Fahrenheit)
'deg. C': 1 # degrees Celsius
'deg. F': 5 / 9 # degrees Fahrenheit
'K': 1 # Kelvin
Pressure Conversions
The reference unit used for this is the atm.
'atm': 1 # atmospheres
'torr': 0.0013157 # torr
'mm Hg': 0.0013157 # millimeters mercury
'bar': 0.986923 # bars
'Pa': 0.0000098 # pascals
'psi': 0.068046 # pounds per cubed inch
Quantity
This is the class that will manage most of your conversions. To import this, you can run either of the following:
from unisci import Quantity
from unisci.types import Quantity
You can create a Quantity using a constructor in the following format:
Quantity(<value>, <dict>)
Where <value> is the numerical value of the Quantity and <dict> is a dictionary of units and their powers. For example, here is the initialization of a Quantity holding the value 1.0 m/s².
>>> length = Quantity(1, {'m': 1, 's': -2})
>>> print(length)
1.000*10⁰ m/s²
Below are methods associated with this class. quan represents an arbitrary Quantity object.
Quantity.set_precision()
Quantity.set_precision(number: int) -> None
Sets the precision (number of decimal places) of printing output. The default value is 3, which is why the above example prints 1.000 rather than 1.0. The below example sets the precision to 2 decimal places.
Quantity.set_precision(number=2)
Quantity.set_auto_format()
Quantity.set_auto_format(do: bool) -> None
Determines if the auto-conversions should be done. For example, when multiplying Quantity’s with units m and in, if auto_format is enabled, the product will be in the units of the first number. It also enables auto-condensation of complicated units, which will be elaborated upon further regarding the x.simplified() method.
>>> length_m = Quantity(1, {'m': 1})
>>> length_in = Quantity(40, {'in': 1})
>>> print(length_m * length_in)
1.016*10⁰ m²
>>> Quantity.set_auto_format(False)
>>> print(length_m * length_in)
4.000*10¹ m-in
quan.value
quan.value -> float
Returns the numerical value of the Quantity.
>>> x = Quantity(12, {'m': 1})
>>> print(x.value)
12.0
quan.units
quan.units -> dict[str, int]
Returns a dictionary of units and powers of the Quantity’s overall composition. Internally, the dictionary is stored as quan.unit_type, but calling quan.units is better because it returns a copy of the dictionary.
>>> x = Quantity(12, {'m': 1})
>>> print(x.units)
{'m': 1}
quan.converted()
quan.converted(target_units: list[str]) -> Quantity
Returns a Quantity converted to all the units it can in the provided list of target units.
>>> velocity = Quantity(1, {'in': 1, 'min': -1})
>>> print(velocity)
1.000*10⁰ in/min
>>> velocity = velocity.converted(['cm', 's'])
>>> print(velocity)
4.233*10⁻² cm/s
Supported units for conversion can be found in the Supported Conversions section.
quan.converted_metric()
quan.converted_metric(target: str, original: str) -> Quantity
Returns a new Quantity with metric conversions being done. This is useful for complex units that aren’t supported in normal conversions, such as Newtons or Joules.
>>> energy = Quantity(1000, {'J': 1})
>>> print(energy)
1.000*10³ J
>>> energy = energy.converted_metric(original='J', target='kJ')
>>> print(energy)
1.000*10⁰ kJ
Specific Conversions
The following methods are available for specific conversions, although generally using quan.converted() is better:
quan.converted_length()
quan.converted_mass()
quan.converted_time()
quan.converted_volume()
quan.converted_temperature()
quan.converted_pressure()
All of the following follow the same format:
quan.converted_function(target: str, original: str) -> Quantity
They take in a target unit and an optional original unit. If no original unit is entered, all compatible conversions will be done to the target unit. These are useful for when you want to convert only one kind of unit to the other, as shown here:
>>> weird_unit = Quantity(1, {'m': 1, 'ft': -1})
>>> print(weird_unit)
1.000*10⁰ m/ft
>>> weird_unit = weird_unit.converted_length(original='ft', target='in')
>>> print(weird_unit)
8.333*10⁻² m/in
quan.simplified()
quan.simplified() -> Quantity
Returns a Quantity with units automatically condensed into complex units. If Quantity.auto_format is set to True, this will happen automatically upon conversions or multiplications with other units.
>>> Quantity.set_auto_format(False)
>>> force = Quantity(1, {'m': 1, 'kg': 1, 's': -2})
>>> print(force)
1.000*10⁰ m-kg/s²
>>> print(force.simplified())
1.000*10⁰ N
quan.force_simplified()
quan.force_simplified(target: str, exp: int = 1) -> Quantity
Forcibly converts a unit to the given target. Does this by multiplying by the inverse of the ‘base units’.
>>> acceleration = Quantity(1, {'m': 1, 's': -2})
>>> print(acceleration)
1.000*10⁰ m/s²
>>> print(acceleration.force_simplified(target='N', exp=1))
1.000*10⁰ N/kg
quan.to_base_units()
quan.to_base_units() -> Quantity
Simplifies a Quantity’s complicated units to their most ‘basic’ units.
>>> energy = Quantity(1, {'J': 1})
>>> print(energy)
1.000*10⁰ J
>>> print(energy.to_base_units())
1.000*10⁰ kg-m²/s²
Standardizing Functions
Here are the functions that are currently included in this package.
quan.standardized_physics() -> Quantity
quan.standardized_chemistry() -> Quantity
Standardizes a Quantity to the standard units in that discipline. Here are the converions made:
PHYSICS_UNITS = ['m', 's', 'kg', 'L', 'K']
CHEMISTRY_UNITS = ['m', 's', 'g', 'L', 'K', 'atm']
Here is an example:
>>> velocity = Quantity(1, {'ly': 1, 'yr': -1})
>>> print(velocity)
1.000*10⁰ ly/yr
>>> print(velocity.standardized_physics())
2.998*10⁸ m/s
Supported Operations
Supported operations using the Quantity class involve:
Multiplication: With a number or a Quantity
Division: With a mumber or a Quantity
Addition: With a number (when Quantity is unitless) or a Quantity
Exponents: With an integer power
Equality: With another Quantity
Here is an example of them in action:
>>> f1 = Quantity(1, {'N': 1})
>>> m2 = Quantity(12, {'lb': 1})
>>> a2 = Quantity(3, {'mi': 1, 'hr': -2})
>>> print(f"{f1}, {m2}, {a2}")
1.000*10⁰ N, 1.200*10¹ lb, 3.000*10⁰ mi/hr²
>>> f2 = m2 * a2 # multiplication
>>> print(f2)
3.600*10¹ lb-mi/hr²
>>> f3 = f1 + f2
>>> print(f3) # addition
1.002*10⁰ N
>>> m3 = Quantity(6.00, {'st': 1})
>>> a3 = f3 / m3 # division
>>> print(a3)
2.627*10⁻² m/s²
>>> c = Quantity(1, {'kN': 1})
>>> d = Quantity(1000, {'kg': 1, 'm': 1, 's': -2})
>>> c == d # equality
True
Element
This class represents chemical elements. It uses data from @Bowserinator to represent chemical elements. You can import it using either of the following:
from unisci import Element
from unisci.types import Element
You initialize an element using EITHER its name, symbol, or atomic number.
hydrogen = Element(name="hydrogen")
hydrogen = Element(symbol='H')
hydrogen = Element(atomic_number=1)
Only one of the the three arguments can be entered, otherwise, an error is raised.
Here are some things you can do with this class. Note: element represents an arbitrary element.
element.name
Returns the name of the element as a string, capitalized. Note: the name for the element aluminum returns alumunium.
>>> al = Element(symbol='Al')
>>> al.name
'Aluminium'
element.number
Returns the element’s atomic number.
>>> hg = Element(name="mercury")
>>> hg.number
80
element.symbol
Returns the element’s symbol. This is also called with the element’s __str__ method.
>>> iron = Element(name="iron")
>>> iron.symbol
'Fe'
>>> print(iron)
Fe
element.desc
Returns the element’s description as a String.
>>> u = Element(atomic_number=92)
>>> print(u.desc)
Uranium is a chemical element with symbol U and atomic number 92. It is a silvery-white metal in the actinide series of the periodic table. A uranium atom has 92 protons and 92 electrons, of which 6 are valence electrons.
element.discoverer
Returns the name of the person who discovered the element.
>>> u = Element(atomic_number=92)
>>> u.discoverer
'Martin Heinrich Klaproth'
element.atomic_mass
Returns the atomic mass of the element in grams per mole.
>>> he = Element(name="helium")
>>> he.atomic_mass
Quantity(4.0026022, {'g': 1, 'mol': -1})
element.state
Returns the state of the element at room temperature.
>>> n = Element(name="nitrogen")
>>> n.state
'Gas'
element.density
Returns the density of the element at room temperature as a Quantity in g/L if the element is a gas and in g/mL for Liquids or Solids.
>>> tungsten = Element(symbol="W")
>>> tungsten.density
Quantity(19.25, {'g': 1, 'mL': -1})
element.boiling_point
Returns the boiling point of the element in Kelvin, as a Quantity.
>>> fe = Element(name="iron")
>>> fe.boiling_point
Quantity(3134.0, {'K': 1})
element.melting_point
Returns the melting point of the element in Kelvin, as a Quantity.
>>> fe = Element(name="iron")
>>> fe.melting_point
Quantity(1811.0, {'K': 1})
element.period
Returns the period of the element.
>>> k = Element(symbol="K")
>>> k.period
4
element.group
Returns the group of the element.
>>> k = Element(symbol="K")
>>> k.group
1
element.electron_config_str
Returns the element’s electron configuration as a string.
>>> mg = Element(symbol="Mg")
>>> mg.electron_config_str
'1s2 2s2 2p6 3s2'
element.electron_config
Returns a dictionary of electron orbitals and electron counts within those orbitals.
>>> mg = Element(symbol="Mg")
>>> mg.electron_config
{'1s': 2, '2s': 2, '2p': 6, '3s': 2}
element.noble_gas_config_str
Returns a string containing the element’s noble gas configuration with the gas.
>>> mercury = Element(symbol="Hg")
>>> mercury.noble_gas_config_str
'[Xe] 4f14 5d10 6s2'
element.noble_gas_config
Returns a dictionary, containing the gas, and a nested dictionary of electron orbitals and their counts.
>>> mercury = Element(symbol="Hg")
>>> mercury.noble_gas_config
{'gas': Element(symbol='Xe'), 'configuration': {'4f': 14, '5d': 10, '6s': 2}}
element.electron_affinity
Returns the electron affinity of the element.
>>> oxygen = Element(atomic_number=8)
>>> oxygen.electron_affinity
140.976
element.electronegativity
Returns the Pauling electronegativity of the element.
>>> oxygen = Element(atomic_number=8)
>>> oxygen.electronegativity
3.44
element.get_ionization_energy(level)
Returns the level-th ionization energy of the element as a Quantity in kJ/mol.
>>> oxygen.get_ionization_energy(level=1)
Quantity(1313.9, {'kJ': 1, 'mol': -1})
Temperature
The temperature class is intended to store temperatures that are relative temperatures, rather than absolute. A relative temperature, in the case of Fahrenheit and Celsius, is one that is relative to the temperature of water. The commonplace ˚C or ˚F are relative, as 0 ˚C is based on the freezing point of water, etc.
For absolute temperatures, (for uses like changes in temperature), or Kelvin temperatures, use the Quantity class.