6. The Simulation Unit

The following section describes the unit management provide by Gridsim.

Module author: Gillian Basso<gillian.basso@hevs.ch>

Code author: Gillian Basso<gillian.basso@hevs.ch>

This module provides a unit management based on pint (https://pypi.python.org/pypi/Pint/).

6.1. How to use gridsim.units

The unit in Gridsim are used for ‘user interface’ functions such as gridsim.simulation.Simulator.run(), but for improves performance Gridsim converts all units in SI base unit and uses them as number (int, float, complex). Therefore some function parameters are float instead of unit especially when extending Gridsim core (see The Simulation Core).

It provides an object call units which is a wrapper to all useful features of pint, thus it should used as follow:

>>> from gridsim.unit import units
>>> area = 1.2*units.meter * 2.5*units.meter
>>> print area
3.0 meter ** 2
>>> print units.value(area)
3.0
>>> print units.dimension(area)
[length] ** 2
>>> print units.unit(area)
meter ** 2

As it is possible to create a measurement by crossing a number value by the unit:

>>> size1 = 1.2*units.meter

it is also possible to create a measurement in an oriented-object way:

>>> size2 = units(1.2, units.meter)

and:

>>> size1 == size2
True

Warning

The second method to create a measurement MUST be used to define non standard temperature and SHALL be converted in standard unit before sending to the simulator unless a pint.unit.OffsetUnitCalculusError will be raised:

celsius = units(20, units.degC)                                   # define temperature in degree celsius
room = sim.thermal.add(ThermalProcess.room('room',
                           50*units.meter*units.meter,            # define square metre
                           2.5*units.metre,                       # define metre
                           units.convert(celsius, units.kelvin))) # convert celsius to kelvin for the simulation

Also, there is a delta counterpart to specify temperature differences. Absolute units have no delta counterpart. For example, the change in celsius is equal to the change in kelvin, but not in fahrenheit (as the scaling factor is different):

>>> hysteresis = 2.4*units.delta_degC
>>> print(hysteresis.to(units.kelvin))
2.4 kelvin
>>> print(hysteresis.to(units.delta_degF))
4.32 delta_degF
gridsim.unit.to_si(unit)

Returns the SI base unit of the given unit:

>>> mass = 1000*units.gram
>>> print units.to_si(mass)
1.0 kilogram
>>> print units.to_si(units.kilometre)
1000.0 meter
Parameters:
gridsim.unit.units(value, unit)

Creates a measurement of value times unit Equivalent to:

value*unit
Parameters:
units.value(measurement)

Returns the value of the measurement without any conversion:

>>> size = 1.2*units.meter
>>> print units.value(size)
1.2
>>> size = 34*units.kilometer
>>> print units.value(size)
34
Returns:the value of the measurement
Return type:float
units.unit(measurement)

Returns the unit of the measurement:

>>> size = 1*units.meter
>>> print units.unit(size)
meter
>>> size = 1*units.kilometer
>>> print units.unit(size)
kilometer
Returns:the unit of the measurement
Return type:str
units.dimension(measurement)

Returns the unit of the measurement:

>>> size = 1*units.meter
>>> print units.dimension(size)
[length]
>>> size = 1*units.kilometer
>>> print units.dimension(size)
[length]
Returns:the unit of the measurement
Return type:str
units.convert(measurement, unit)

Converts the measurement to the unit if possible else raises pint.unit.DimensionalityError exception:

>>> print units.convert(1*units.metre, units.centimetre)
100.0 centimeter
>>> print units.convert(1*units.metre, units.litre)
[...]
pint.unit.DimensionalityError: Cannot convert from 'meter' ([length]) to 'liter' ([length] ** 3)
Returns:the converted measurement
Return type:unit

6.2. Information of existing units

Here is a summary of all units that could be used to create a measurement. This content is based on data of file default_en.txt of pint package.

6.2.1. References

The data in square brackets [] are the dimension returned by units.dimension().

  • meter = [length] = m = metre
  • second = [time] = s = sec
  • ampere = [current] = A = amp
  • candela = [luminosity] = cd = candle
  • kilogram = [mass] = kg
  • mole = [substance] = mol
  • kelvin = [temperature]; offset: 0 = K = degK
  • radian = [] = rad
  • bit = []
  • count = []

6.2.2. Prefixes

6.2.2.1. Decimal prefixes

  • yocto- = 1e-24 = y-
  • zepto- = 1e-21 = z-
  • atto- =  1e-18 = a-
  • femto- = 1e-15 = f-
  • pico- =  1e-12 = p-
  • nano- =  1e-9  = n-
  • micro- = 1e-6  = u-
  • milli- = 1e-3  = m-
  • centi- = 1e-2  = c-
  • deci- =  1e-1  = d-
  • deca- =  1e+1  = da-
  • hecto- = 1e2   = h-
  • kilo- =  1e3   = k-
  • mega- =  1e6   = M-
  • giga- =  1e9   = G-
  • tera- =  1e12  = T-
  • peta- =  1e15  = P-
  • exa- =   1e18  = E-
  • zetta- = 1e21  = Z-
  • yotta- = 1e24  = Y-

Example:

>>> print units.convert(1*units.yottagram, units.gram)
1e+24 gram
>>> print units.convert(1*units.Yg, units.g)
1e+24 gram

6.2.2.2. Binary_prefixes

  • kibi- = 2**10 = Ki-
  • mebi- = 2**20 = Mi-
  • gibi- = 2**30 = Gi-
  • tebi- = 2**40 = Ti-
  • pebi- = 2**50 = Pi-
  • exbi- = 2**60 = Ei-
  • zebi- = 2**70 = Zi-
  • yobi- = 2**80 = Yi-

Example:

>>> print units.convert(1*units.kibibit, units.bit)
1024.0 bit
>>> print units.convert(1*units.Kibit, units.bit)
1024.0 bit

6.2.3. Other units

6.2.3.1. Gridsim units

Gridsim defines its own units to simplify coding as these special units is used often times.

  • heat_capacity = joule/(kilogram*kelvin)
  • mass_density = kilogram/(metre*metre*metre)
  • thermal_conductivity = watt/(kelvin*metre)

6.2.3.2. Acceleration

  • [acceleration] = [length] / [time] ** 2

6.2.3.3. Angle

  • turn = 2 * pi * radian = revolution = cycle = circle
  • degree = pi / 180 * radian = deg = arcdeg = arcdegree = angular_degree
  • arcminute = arcdeg / 60 = arcmin = arc_minute = angular_minute
  • arcsecond = arcmin / 60 =  arcsec = arc_second = angular_second
  • steradian = radian ** 2 = sr

6.2.3.4. Area

  • [area] = [length] ** 2
  • are = 100 * m**2
  • barn = 1e-28 * m ** 2 = b
  • cmil = 5.067075e-10 * m ** 2 = circular_mils
  • darcy = 9.869233e-13 * m ** 2
  • acre = 4046.8564224 * m ** 2 = international_acre
  • US_survey_acre = 160 * rod ** 2

6.2.3.5. Electromagnetism

  • esu = 1 * erg**0.5 * centimeter**0.5 = statcoulombs = statC = franklin = Fr
  • esu_per_second = 1 * esu / second = statampere
  • ampere_turn = 1 * A
  • gilbert = 10 / (4 * pi ) * ampere_turn
  • coulomb = ampere * second = C
  • volt = joule / coulomb = V
  • farad = coulomb / volt = F
  • ohm = volt / ampere
  • siemens = ampere / volt = S = mho
  • weber = volt * second = Wb
  • tesla = weber / meter ** 2 = T
  • henry = weber / ampere = H
  • elementary_charge = 1.602176487e-19 * coulomb = e
  • chemical_faraday = 9.64957e4 * coulomb
  • physical_faraday = 9.65219e4 * coulomb
  • faraday =  96485.3399 * coulomb = C12_faraday
  • gamma = 1e-9 * tesla
  • gauss = 1e-4 * tesla
  • maxwell = 1e-8 * weber = mx
  • oersted = 1000 / (4 * pi) * A / m = Oe
  • statfarad = 1.112650e-12 * farad = statF = stF
  • stathenry = 8.987554e11 * henry = statH = stH
  • statmho = 1.112650e-12 * siemens = statS = stS
  • statohm = 8.987554e11 * ohm
  • statvolt = 2.997925e2 * volt = statV = stV
  • unit_pole = 1.256637e-7 * weber

6.2.3.6. Energy

  • [energy] = [force] * [length]
  • joule = newton * meter = J
  • erg = dyne * centimeter
  • btu = 1.05505585262e3 * joule = Btu = BTU = british_thermal_unit
  • eV = 1.60217653e-19 * J = electron_volt
  • thm = 100000 * BTU = therm = EC_therm
  • cal = 4.184 * joule = calorie = thermochemical_calorie
  • international_steam_table_calorie = 4.1868 * joule
  • ton_TNT = 4.184e9 * joule = tTNT
  • US_therm = 1.054804e8 * joule
  • watt_hour = watt * hour = Wh = watthour
  • E_h = 4.35974394e-18 * joule = hartree = hartree_energy

6.2.3.7. Force

  • [force] = [mass] * [acceleration]
  • newton = kilogram * meter / second ** 2 = N
  • dyne = gram * centimeter / second ** 2 = dyn
  • force_kilogram = g_0 * kilogram = kgf = kilogram_force = pond
  • force_gram = g_0 * gram = gf = gram_force
  • force_ounce = g_0 * ounce = ozf = ounce_force
  • force_pound = g_0 * lb = lbf = pound_force
  • force_ton = 2000 * force_pound = ton_force
  • poundal = lb * feet / second ** 2 = pdl
  • kip = 1000*lbf

6.2.3.8. Frequency

  • [frequency] = 1 / [time]
  • hertz = 1 / second = Hz = rps
  • revolutions_per_minute = revolution / minute = rpm
  • counts_per_second = count / second = cps

6.2.3.9. Information

  • byte = 8 * bit = Bo = octet
  • baud = bit / second = Bd = bps

6.2.3.10. Length

  • angstrom = 1e-10 * meter
  • inch = 2.54 * centimeter = in = international_inch = inches = international_inches
  • foot = 12 * inch = ft = international_foot = feet = international_feet
  • mile = 5280 * foot = mi = international_mile
  • yard = 3 * feet = yd = international_yard
  • mil = inch / 1000 = thou
  • parsec = 3.08568025e16 * meter = pc
  • light_year = speed_of_light * julian_year = ly = lightyear
  • astronomical_unit = 149597870691 * meter = au
  • nautical_mile = 1.852e3 * meter = nmi
  • printers_point = 127 * millimeter / 360 = point
  • printers_pica = 12 * printers_point = pica
  • US_survey_foot = 1200 * meter / 3937
  • US_survey_yard =  3 * US_survey_foot
  • US_survey_mile = 5280 * US_survey_foot = US_statute_mile
  • rod = 16.5 * US_survey_foot = pole = perch
  • furlong = 660 * US_survey_foot
  • fathom = 6 * US_survey_foot
  • chain = 66 * US_survey_foot
  • barleycorn = inch / 3
  • arpentlin = 191.835 * feet
  • kayser = 1 / centimeter = wavenumber

6.2.3.11. Mass

  • dram = oz / 16 = dr = avoirdupois_dram
  • ounce = 28.349523125 * gram = oz = avoirdupois_ounce
  • pound = 0.45359237 * kilogram = lb = avoirdupois_pound
  • stone = 14 * lb = st
  • carat = 200 * milligram
  • grain = 64.79891 * milligram = gr
  • long_hundredweight = 112 * lb
  • short_hundredweight = 100 * lb
  • metric_ton = 1000 * kilogram = t = tonne
  • pennyweight = 24 * gram = dwt
  • slug = 14.59390 * kilogram
  • troy_ounce = 480 * gram = toz = apounce = apothecary_ounce
  • troy_pound = 12 * toz = tlb = appound = apothecary_pound
  • drachm = 60 * gram = apdram = apothecary_dram
  • atomic_mass_unit = 1.660538782e-27 * kilogram =  u = amu = dalton = Da
  • scruple = 20 * gram
  • bag = 94 * lb
  • ton = 2000 * lb = short_ton

6.2.3.12. Textile

  • denier =  gram / (9000 * meter)
  • tex = gram/ (1000 * meter)
  • dtex = decitex

6.2.3.13. Power

  • [power] = [energy] / [time]
  • watt = joule / second = W = volt_ampere = VA
  • horsepower = 33000 * ft * lbf / min = hp = UK_horsepower = British_horsepower
  • boiler_horsepower = 33475 * btu / hour
  • metric_horsepower =  75 * force_kilogram * meter / second
  • electric_horsepower = 746 * watt
  • hydraulic_horsepower = 550 * feet * lbf / second
  • refrigeration_ton = 12000 * btu / hour = ton_of_refrigeration

6.2.3.14. Pressure

  • [pressure] = [force] / [area]
  • Hg = gravity * 13.59510 * gram / centimeter ** 3 = mercury = conventional_mercury
  • mercury_60F = gravity * 13.5568 * gram / centimeter ** 3
  • H2O = gravity * 1000 * kilogram / meter ** 3 = h2o = water = conventional_water
  • water_4C = gravity * 999.972 * kilogram / meter ** 3 = water_39F
  • water_60F = gravity * 999.001 * kilogram / m ** 3
  • pascal = newton / meter ** 2 = Pa
  • bar = 100000 * pascal
  • atmosphere = 101325 * pascal = atm = standard_atmosphere
  • technical_atmosphere = kilogram * gravity / centimeter ** 2 = at
  • torr = atm / 760
  • psi = pound * gravity / inch ** 2 = pound_force_per_square_inch
  • ksi = kip / inch ** 2 = kip_per_square_inch
  • barye = 0.1 * newton / meter ** 2 = barie = barad = barrie = baryd = Ba
  • mmHg = millimeter * Hg = mm_Hg = millimeter_Hg = millimeter_Hg_0C
  • cmHg = centimeter * Hg = cm_Hg = centimeter_Hg
  • inHg = inch * Hg = in_Hg = inch_Hg = inch_Hg_32F
  • inch_Hg_60F = inch * mercury_60F
  • inch_H2O_39F = inch * water_39F
  • inch_H2O_60F = inch * water_60F
  • footH2O = ft * water
  • cmH2O = centimeter * water
  • foot_H2O = ft * water = ftH2O
  • standard_liter_per_minute = 1.68875 * Pa * m ** 3 / s = slpm = slm

6.2.3.15. Radiation

  • Bq = Hz = becquerel
  • curie = 3.7e10 * Bq = Ci
  • rutherford = 1e6*Bq = rd = Rd
  • Gy = joule / kilogram = gray = Sv = sievert
  • rem = 1e-2 * sievert
  • rads = 1e-2 * gray
  • roentgen = 2.58e-4 * coulomb / kilogram

6.2.3.16. Temperature

  • degC = kelvin; offset: 273.15 = celsius
  • degR = 5 / 9 * kelvin; offset: 0 = rankine
  • degF = 5 / 9 * kelvin; offset: 255.372222 = fahrenheit

Warning

As temperature can have an offset, it could be necessary to units.convert() degree to kelvin to avoid errors.

6.2.3.17. Delta temperature

There is a delta counterpart to specify temperature differences. Absolute units have no delta counterpart. For example, the change in celsius is equal to the change in kelvin, but not in fahrenheit (as the scaling factor is different).

  • delta_degC
  • delta_degF
  • kelvin
  • rankine

6.2.3.18. Time

  • minute = 60 * second = min
  • hour = 60 * minute = hr
  • day = 24 * hour
  • week = 7 * day
  • fortnight = 2 * week
  • year = 31556925.9747 * second
  • month = year/12
  • shake = 1e-8 * second
  • sidereal_day = day / 1.00273790935079524
  • sidereal_hour = sidereal_day/24
  • sidereal_minute=sidereal_hour/60
  • sidereal_second =sidereal_minute/60
  • sidereal_year = 366.25636042 * sidereal_day
  • sidereal_month = 27.321661 * sidereal_day
  • tropical_month = 27.321661 * day
  • synodic_month = 29.530589 * day = lunar_month
  • common_year = 365 * day
  • leap_year = 366 * day
  • julian_year = 365.25 * day
  • gregorian_year = 365.2425 * day
  • millenium = 1000 * year = millenia = milenia = milenium
  • eon = 1e9 * year
  • work_year = 2056 * hour
  • work_month = work_year/12

6.2.3.19. Velocity

  • [speed] = [length] / [time]
  • knot = nautical_mile / hour = kt = knot_international = international_knot = nautical_miles_per_hour
  • mph = mile / hour = MPH
  • kph = kilometer / hour = KPH

6.2.3.20. Viscosity

  • [viscosity] = [pressure] * [time]
  • poise = 1e-1 * Pa * second = P
  • stokes = 1e-4 * meter ** 2 / second = St
  • rhe = 10 / (Pa * s)

6.2.3.21. Volume

  • [volume] = [length] ** 3
  • liter = 1e-3 * m ** 3 = l = L = litre
  • cc = centimeter ** 3 = cubic_centimeter
  • stere = meter ** 3
  • gross_register_ton = 100 * foot ** 3 = register_ton = GRT
  • acre_foot = acre * foot = acre_feet
  • board_foot = foot ** 2 * inch = FBM
  • bushel = 2150.42 * inch ** 3 = bu = US_bushel
  • dry_gallon = bushel / 8 = US_dry_gallon
  • dry_quart = dry_gallon / 4 = US_dry_quart
  • dry_pint = dry_quart / 2 = US_dry_pint
  • gallon = 231 * inch ** 3 = liquid_gallon = US_liquid_gallon
  • quart = gallon / 4 = liquid_quart = US_liquid_quart
  • pint = quart / 2 = pt = liquid_pint = US_liquid_pint
  • cup = pint / 2 = liquid_cup = US_liquid_cup
  • gill = cup / 2 = liquid_gill = US_liquid_gill
  • fluid_ounce = gill / 4 = floz = US_fluid_ounce = US_liquid_ounce
  • imperial_bushel = 36.36872 * liter = UK_bushel
  • imperial_gallon = imperial_bushel / 8 = UK_gallon
  • imperial_quart = imperial_gallon / 4 = UK_quart
  • imperial_pint = imperial_quart / 2 = UK_pint
  • imperial_cup = imperial_pint / 2 = UK_cup
  • imperial_gill = imperial_cup / 2 = UK_gill
  • imperial_floz = imperial_gill / 5 = UK_fluid_ounce = imperial_fluid_ounce
  • barrel = 42 * gallon = bbl
  • tablespoon = floz / 2 = tbsp = Tbsp = Tblsp = tblsp = tbs = Tbl
  • teaspoon = tablespoon / 3 = tsp
  • peck = bushel / 4 = pk
  • fluid_dram = floz / 8 = fldr = fluidram
  • firkin = barrel / 4