# 65. `plugins.units` — A Python wrapper for unit conversion of physical quantities.

This module uses the standard UNIX program ‘units’ (available from http://www.gnu.org/software/units/units.html) to do the actual conversions. Obviously, it will only work on systems that have this program available.

If you really insist on running another OS lacking the units command, have a look at http://home.tiscali.be/be052320/Unum.html and make an implementation based on unum. If you GPL it and send it to me, I might include it in this distribution.

class `plugins.units.``UnitsSystem`(system='international')

  A class for handling and converting units of physical quantities.

  The units class provides two built-in consistent units systems: International() and Engineering(). International() returns the standard International Standard units. Engineering() returns a consistent engineering system,which is very practical for use in mechanical engineering. It uses ‘mm’ for length and ‘MPa’ for pressure and stress. To keep it consistent however, the density is rather unpractical: ‘t/mm^3’. If you want to use t/m^3, you can make a custom units system. Beware with non-consistent unit systems though! The better practice is to allow any unit to be specified at input (and eventually requested for output), and to convert everyting internally to a consistent system. Apart from the units for usual physical quantities, Units stores two special purpose values in its units dictionary: ‘model’ : defines the length unit used in the geometrical model ‘problem’ : defines the unit system to be used in the problem. Defaults are: model=’m’, problem=’international’.

  `Add`(un)

    Add the units from dictionary un to the units system

  `Predefined`(system)

    Returns the predefined units for the specified system

  `International`()

    Returns the international units system.

  `Engineering`()

    Returns a consistent engineering units system.

  `Read`(filename)

    Read units from file with specified name.

    The units file is an ascii file where each line contains a couple of words separated by a colon and a blank. The first word is the type of quantity, the second is the unit to be used for this quantity. Lines starting with ‘#’ are ignored. A ‘problem: system’ line sets all units to the corresponding value of the specified units system.

  `Get`(ent)

    Get units list for the specified entitities.

    If ent is a single entity, returns the corresponding unit if an entry ent exists in the current system or else returns ent unchanged. If ent is a list of entities, returns a list of corresponding units. Example: with the default units system:

        Un = UnitsSystem()
        Un.Get(['length','mass','float'])

    returns: `['m', 'kg', 'float']`

## 65.1. Functions defined in module plugins.units

`plugins.units.``convertUnits`(From, To)

  Converts between conformable units.

  This function converts the units ‘From’ to units ‘To’. The units should be conformable. The ‘From’ argument can (and usually does) include a value. The return value is a string with the converted value without units. Thus: convertUnits(‘3.45 kg’,’g’) will return ‘3450’. This function is merely a wrapper around the GNU ‘units’ command, which should be installed for this function to work.

  Examples

      >>> convertUnits('25.4cm', 'in')
      '10'
      >>> convertUnits('31e6mg', 'kg')
      '31'
      >>> convertUnits('1 lightyear', 'km')
      '9.4607305e+12'
      >>> convertUnits('21000 kN/cm**2', 'MPa')
      '210000'