<commit_before>.. _tutorial:


Tutorial
========

Converting Quantities
---------------------

Pint has the concept of Unit Registry, an object within which units are defined and handled. You start by creating your registry::

   >>> from pint import UnitRegistry
   >>> ureg = UnitRegistry()

.. testsetup:: *

   from pint import UnitRegistry
   ureg = UnitRegistry()
   Q_ = ureg.Quantity

If no parameter is given to the constructor, the unit registry is populated with the default list of units and prefixes.
You can now simply use the registry in the following way:

.. doctest::

   >>> distance = 24.0 * ureg.meter
   >>> print(distance)
   24.0 meter
   >>> time = 8.0 * ureg.second
   >>> print(time)
   8.0 second
   >>> print(repr(time))
   <Quantity(8.0, 'second')>

In this code `distance` and `time` are physical quantities objects (`Quantity`). Physical quantities can be queried for the magnitude, units, and dimensionality:

.. doctest::

   >>> print(distance.magnitude)
   24.0
   >>> print(distance.units)
   meter
   >>> print(distance.dimensionality)
   [length]

and can handle mathematical operations between:

.. doctest::

   >>> speed = distance / time
   >>> print(speed)
   3.0 meter / second

As unit registry knows about the relationship between different units, you can convert quantities to the unit of choice:

.. doctest::

   >>> speed.to(ureg.inch / ureg.minute )
   <Quantity(7086.614173228345, 'inch / minute')>

This method returns a new object leaving the original intact as can be seen by:

.. doctest::

   >>> print(speed)
   3.0 meter / second

If you want to convert in-place (i.e. without creating another object), you can use the `ito` method:

.. doctest::

   >>> speed.ito(ureg.inch / ureg.minute )
   <Quantity(7086.614173228345, 'inch / minute')>
   >>> print(speed)
   7086.614173228345 inch / minute

If you ask Pint to perform an invalid conversion:

.. doctest::

   >>> speed.to(ureg.joule)
   Traceback (most recent call last):
   ...
   pint.pint.DimensionalityError: Cannot convert from 'inch / minute' (length / time) to 'joule' (length ** 2 * mass / time ** 2)


There are also methods 'to_base_units' and 'ito_base_units' which automatically convert to the reference units with the correct dimensionality:

.. doctest::

   >>> height = 5.0 * ureg.foot + 9.0 * ureg.inch
   >>> print(height)
   5.75 foot
   >>> print(height.to_base_units())
   1.7526 meter
   >>> print(height)
   5.75 foot
   >>> height.ito_base_units()
   <Quantity(1.7526, 'meter')>
   >>> print(height)
   1.7526 meter


In some cases it is useful to define physical quantities objects using the class constructor:

.. doctest::

   >>> Q_ = ureg.Quantity
   >>> Q_(1.78, ureg.meter) == 1.78 * ureg.meter
   True

(I tend to abbreviate Quantity as `Q_`) The in-built parse allows to recognize prefixed and pluralized units even though they are not in the definition list:

.. doctest::

   >>> distance = 42 * ureg.kilometers
   >>> print(distance)
   42 kilometer
   >>> print(distance.to(ureg.meter))
   42000.0 meter

If you try to use a unit which is not in the registry:

.. doctest::

   >>> speed = 23 * ureg.snail_speed
   Traceback (most recent call last):
   ...
   pint.pint.UndefinedUnitError: 'snail_speed' is not defined in the unit registry

You can add your own units to the registry or build your own list. More info on that :ref:`defining`


String parsing
--------------

Pint can also handle units and units provided as strings:

.. doctest::

   >>> 2.54 * ureg.parse_expression('centimeter')
   <Quantity(2.54, 'centimeter')>

or using the registry as a callable for a short form:

.. doctest::

   >>> 2.54 * ureg('centimeter')
   <Quantity(2.54, 'centimeter')>

or using the `Quantity` constructor:

.. doctest::

   >>> Q_(2.54, 'centimeter')
   <Quantity(2.54, 'centimeter')>

Numbers are also parsed, so you can use an expression:

.. doctest::

   >>> ureg('2.54 * centimeter')
   <Quantity(2.54, 'centimeter')>

or:

.. doctest::

   >>> Q_('2.54 * centimeter')
   <Quantity(2.54, 'centimeter')>

This enables you to build a simple unit converter in 3 lines:

.. doctest::

   >>> user_input = '2.54 * centimeter to inch'
   >>> src, dst = user_input.split(' to ')
   >>> Q_(src).to(dst)
   <Quantity(1.0, 'inch')>

Take a look at `qconvert.py` within the examples folder for a full script.

.. warning:: Pint currently uses eval_ under the hood.
   Do not use this approach from untrusted sources as it is dangerous_.


String formatting
-----------------

Pint's physical quantities can be easily printed:

.. doctest::

   >>> accel = 1.3 * ureg['meter/second**2']
   >>> # The standard string formatting code
   >>> print('The str is {!s}'.format(accel))<commit_msg>Removed incorrect text from the tutorial<commit_after>.. _tutorial:


Tutorial
========

Converting Quantities
---------------------

Pint has the concept of Unit Registry, an object within which units are defined and handled. You start by creating your registry::

   >>> from pint import UnitRegistry
   >>> ureg = UnitRegistry()

.. testsetup:: *

   from pint import UnitRegistry
   ureg = UnitRegistry()
   Q_ = ureg.Quantity

If no parameter is given to the constructor, the unit registry is populated with the default list of units and prefixes.
You can now simply use the registry in the following way:

.. doctest::

   >>> distance = 24.0 * ureg.meter
   >>> print(distance)
   24.0 meter
   >>> time = 8.0 * ureg.second
   >>> print(time)
   8.0 second
   >>> print(repr(time))
   <Quantity(8.0, 'second')>

In this code `distance` and `time` are physical quantities objects (`Quantity`). Physical quantities can be queried for the magnitude, units, and dimensionality:

.. doctest::

   >>> print(distance.magnitude)
   24.0
   >>> print(distance.units)
   meter
   >>> print(distance.dimensionality)
   [length]

and can handle mathematical operations between:

.. doctest::

   >>> speed = distance / time
   >>> print(speed)
   3.0 meter / second

As unit registry knows about the relationship between different units, you can convert quantities to the unit of choice:

.. doctest::

   >>> speed.to(ureg.inch / ureg.minute )
   <Quantity(7086.614173228345, 'inch / minute')>

This method returns a new object leaving the original intact as can be seen by:

.. doctest::

   >>> print(speed)
   3.0 meter / second

If you want to convert in-place (i.e. without creating another object), you can use the `ito` method:

.. doctest::

   >>> speed.ito(ureg.inch / ureg.minute )
   <Quantity(7086.614173228345, 'inch / minute')>
   >>> print(speed)
   7086.614173228345 inch / minute

If you ask Pint to perform an invalid conversion:

.. doctest::

   >>> speed.to(ureg.joule)
   Traceback (most recent call last):
   ...
   pint.pint.DimensionalityError: Cannot convert from 'inch / minute' (length / time) to 'joule' (length ** 2 * mass / time ** 2)


There are also methods 'to_base_units' and 'ito_base_units' which automatically convert to the reference units with the correct dimensionality:

.. doctest::

   >>> height = 5.0 * ureg.foot + 9.0 * ureg.inch
   >>> print(height)
   5.75 foot
   >>> print(height.to_base_units())
   1.7526 meter
   >>> print(height)
   5.75 foot
   >>> height.ito_base_units()
   <Quantity(1.7526, 'meter')>
   >>> print(height)
   1.7526 meter


In some cases it is useful to define physical quantities objects using the class constructor:

.. doctest::

   >>> Q_ = ureg.Quantity
   >>> Q_(1.78, ureg.meter) == 1.78 * ureg.meter
   True

(I tend to abbreviate Quantity as `Q_`) The in-built parse allows to recognize prefixed and pluralized units even though they are not in the definition list:

.. doctest::

   >>> distance = 42 * ureg.kilometers
   >>> print(distance)
   42 kilometer
   >>> print(distance.to(ureg.meter))
   42000.0 meter

If you try to use a unit which is not in the registry:

.. doctest::

   >>> speed = 23 * ureg.snail_speed
   Traceback (most recent call last):
   ...
   pint.pint.UndefinedUnitError: 'snail_speed' is not defined in the unit registry

You can add your own units to the registry or build your own list. More info on that :ref:`defining`


String parsing
--------------

Pint can also handle units and units provided as strings:

.. doctest::

   >>> 2.54 * ureg.parse_expression('centimeter')
   <Quantity(2.54, 'centimeter')>

or using the registry as a callable for a short form:

.. doctest::

   >>> 2.54 * ureg('centimeter')
   <Quantity(2.54, 'centimeter')>

or using the `Quantity` constructor:

.. doctest::

   >>> Q_(2.54, 'centimeter')
   <Quantity(2.54, 'centimeter')>

Numbers are also parsed, so you can use an expression:

.. doctest::

   >>> ureg('2.54 * centimeter')
   <Quantity(2.54, 'centimeter')>

or:

.. doctest::

   >>> Q_('2.54 * centimeter')
   <Quantity(2.54, 'centimeter')>

This enables you to build a simple unit converter in 3 lines:

.. doctest::

   >>> user_input = '2.54 * centimeter to inch'
   >>> src, dst = user_input.split(' to ')
   >>> Q_(src).to(dst)
   <Quantity(1.0, 'inch')>


.. warning:: Pint currently uses eval_ under the hood.
   Do not use this approach from untrusted sources as it is dangerous_.


String formatting
-----------------

Pint's physical quantities can be easily printed:

.. doctest::

   >>> accel = 1.3 * ureg['meter/second**2']
   >>> # The standard string formatting code
   >>> print('The str is {!s}'.format(accel))
{'fraction_non_alphanumeric': 0.13603565365025466, 'fraction_numerical': 0.032045840407470286, 'mean_word_length': 3.2019616584930897, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 263, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '608881', 'n_tokens_mistral': 3207, 'n_tokens_neox': 2907, 'n_words': 1049}