1Defining Quantities 2=================== 3 4A quantity in Pint is the product of a unit and a magnitude. 5 6Pint supports several different ways of defining physical quantities, including 7a powerful string parsing system. These methods are largely interchangeable, 8though you may **need** to use the constructor form under certain circumstances 9(see :doc:`nonmult` for an example of where the constructor form is required). 10 11By multiplication 12----------------- 13 14If you've read the :ref:`Tutorial`, you're already familiar with defining a 15quantity by multiplying a ``Unit()`` and a scalar: 16 17.. doctest:: 18 19 >>> from pint import UnitRegistry 20 >>> ureg = UnitRegistry() 21 >>> ureg.meter 22 <Unit('meter')> 23 >>> 30.0 * ureg.meter 24 <Quantity(30.0, 'meter')> 25 26This works to build up complex units as well: 27 28.. doctest:: 29 30 >>> 9.8 * ureg.meter / ureg.second**2 31 <Quantity(9.8, 'meter / second ** 2')> 32 33 34Using the constructor 35--------------------- 36 37In some cases it is useful to define :class:`Quantity() <pint.quantity.Quantity>` 38objects using it's class constructor. Using the constructor allows you to 39specify the units and magnitude separately. 40 41We typically abbreviate that constructor as `Q_` to make it's usage less verbose: 42 43.. doctest:: 44 45 >>> Q_ = ureg.Quantity 46 >>> Q_(1.78, ureg.meter) 47 <Quantity(1.78, 'meter')> 48 49As you can see below, the multiplication and constructor methods should produce 50the same results: 51 52.. doctest:: 53 54 >>> Q_(30.0, ureg.meter) == 30.0 * ureg.meter 55 True 56 >>> Q_(9.8, ureg.meter / ureg.second**2) 57 <Quantity(9.8, 'meter / second ** 2')> 58 59Quantity can be created with itself, if units is specified ``pint`` will try to convert it to the desired units. 60If not, pint will just copy the quantity. 61 62.. doctest:: 63 64 >>> length = Q_(30.0, ureg.meter) 65 >>> Q_(length, 'cm') 66 <Quantity(3000.0, 'centimeter')> 67 >>> Q_(length) 68 <Quantity(30.0, 'meter')> 69 70Using string parsing 71-------------------- 72 73Pint includes a powerful parser for detecting magnitudes and units (with or 74without prefixes) in strings. Calling the ``UnitRegistry()`` directly 75invokes the parsing function: 76 77.. doctest:: 78 79 >>> 30.0 * ureg('meter') 80 <Quantity(30.0, 'meter')> 81 >>> ureg('30.0 meters') 82 <Quantity(30.0, 'meter')> 83 >>> ureg('3000cm').to('meters') 84 <Quantity(30.0, 'meter')> 85 86The parsing function is also available to the ``Quantity()`` constructor and 87the various ``.to()`` methods: 88 89.. doctest:: 90 91 >>> Q_('30.0 meters') 92 <Quantity(30.0, 'meter')> 93 >>> Q_(30.0, 'meter') 94 <Quantity(30.0, 'meter')> 95 >>> Q_('3000.0cm').to('meter') 96 <Quantity(30.0, 'meter')> 97 98Or as a standalone method on the ``UnitRegistry``: 99 100.. doctest:: 101 102 >>> 2.54 * ureg.parse_expression('centimeter') 103 <Quantity(2.54, 'centimeter')> 104 105It is fairly good at detecting compound units: 106 107.. doctest:: 108 109 >>> g = ureg('9.8 meters/second**2') 110 >>> g 111 <Quantity(9.8, 'meter / second ** 2')> 112 >>> g.to('furlongs/fortnight**2') 113 <Quantity(7.12770743e+10, 'furlong / fortnight ** 2')> 114 115And behaves well when given dimensionless quantities, which are parsed into 116their appropriate objects: 117 118.. doctest:: 119 120 >>> ureg('2.54') 121 2.54 122 >>> type(ureg('2.54')) 123 <class 'float'> 124 >>> Q_('2.54') 125 <Quantity(2.54, 'dimensionless')> 126 >>> type(Q_('2.54')) 127 <class 'pint.quantity.build_quantity_class.<locals>.Quantity'> 128 129.. note:: Pint's rule for parsing strings with a mixture of numbers and 130 units is that **units are treated with the same precedence as numbers**. 131 132For example, the units of 133 134.. doctest:: 135 136 >>> Q_('3 l / 100 km') 137 <Quantity(0.03, 'kilometer * liter')> 138 139may be unexpected at first but, are a consequence of applying this rule. Use 140brackets to get the expected result: 141 142.. doctest:: 143 144 >>> Q_('3 l / (100 km)') 145 <Quantity(0.03, 'liter / kilometer')> 146 147.. note:: Since version 0.7, Pint **does not** use eval_ under the hood. 148 This change removes the `serious security problems`_ that the system is 149 exposed to when parsing information from untrusted sources. 150 151.. _eval: http://docs.python.org/3/library/functions.html#eval 152.. _`serious security problems`: http://nedbatchelder.com/blog/201206/eval_really_is_dangerous.html 153