barril 2.2.1
Python package to manage units for physical quantities
License: MIT license
Requires Python: >=3.9
Keywords: barril

======
Barril
======


.. image:: https://img.shields.io/pypi/v/barril.svg
    :target: https://pypi.python.org/pypi/barril

.. image:: https://img.shields.io/pypi/pyversions/barril.svg
    :target: https://pypi.org/project/barril

.. image:: https://github.com/ESSS/barril/workflows/test/badge.svg
    :target: https://github.com/ESSS/barril/actions

.. image:: https://codecov.io/gh/ESSS/barril/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/ESSS/barril

.. image:: https://img.shields.io/readthedocs/barril.svg
    :target: https://barril.readthedocs.io/en/latest/

.. image:: https://sonarcloud.io/api/project_badges/measure?project=ESSS_barril&metric=alert_status
    :target: https://sonarcloud.io/project/overview?id=ESSS_barril


What is Barril?
===============

Python package to manage units for physical quantities.

Quick example:

.. code-block:: python

    from barril.units import Scalar

    s1 = Scalar(10, "m")
    s2 = Scalar(500, "cm")
    assert s1 + s2 == Scalar(15, "m")


Features
--------

* Pre-defined unit database containing several physical quantities for the Oil & Gas industry.
* Data types with an associated unit: ``Scalar``, ``Array``, ``Quantity``, ``FixedArray``.
* Automatic conversion during arithmetic operations.

Development
-----------

For complete description of what type of contributions are possible,
see the full `CONTRIBUTING <CONTRIBUTING.rst>`_ guide.

Here is a quick summary of the steps necessary to setup your environment to contribute to ``barril``.

#. Create a virtual environment and activate it::

    $ python -m virtualenv .env
    $ .env\Scripts\activate  # windows
    $ source .env/bin/activate  # linux


   .. note::

       If you use ``conda``, you can install ``virtualenv`` in the root environment::

           $ conda install -n root virtualenv

       Don't worry as this is safe to do.

#. Update ``pip``::

    $ python -m pip install -U pip

#. Install development dependencies::

    $ pip install -e .[testing]

#. Install pre-commit::

    $ pre-commit install

#. Run tests::

    $ pytest --pyargs barril

#. Generate docs locally::

    $ tox -e docs

   The documentation files will be generated in ``docs/_build``.

Release
-------

A reminder for the maintainers on how to make a new release.

Note that the VERSION should folow the semantic versioning as X.Y.Z
Ex.: v1.0.5

1. Create a ``release-VERSION`` branch from ``upstream/master``.
2. Update ``CHANGELOG.rst``.
3. Push a branch with the changes.
4. Once all builds pass, push a ``VERSION`` tag to ``upstream``.
5. Merge the PR.

Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _`GitHub page` :                   https://github.com/ESSS/barril
.. _Cookiecutter:                     https://github.com/audreyr/cookiecutter
.. _pytest:                           https://github.com/pytest-dev/pytest
.. _tox:                              https://github.com/tox-dev/tox


2.2.1
-------------------

*2026-01-16*

* Fixed ``UnboundLocalError`` bug when performing multiplication in an empty array.

2.2.0
-----

*2025-12-23*

* Add category ``slip coefficient``  (default unit: ``m3/Pa.s``).
* Add category ``fluid mobility``  (default unit: ``s/m2``).
* Add category and quantity type ``time per per area``  (``s/m2``).

2.1.0
-----

*2025-09-17*

* Added new unit: "Kelvin per atm" (``K/atm``).
* Added support for Python 3.13.
* Dropped support for Python 3.8 (EOL).

2.0.1 (2024-02-15)
------------------

* Added support for Python 3.11 and 3.12.
* Dropped support for EOL Python 3.6 and 3.7.
* Add categorie and quantity type ``henry solubility coefficient``  (``mol/m3.Pa``)
* Add categorie and quantity type ``crystallization kinetic rate`` (``mol/m2.s.Pa``)

1.19.0 (2023-08-10)
-------------------

* Define the category and quantity type ``density derivative in respect to enthalpy``(default unit: ``kg2/m3.J``).

1.18.0 (2023-06-01)
-------------------

* Define categories ``forchheimer linear productivity index`` and ``forchheimer linear productivity index``.
* Define quantity types ``forchheimer linear productivity index`` and ``forchheimer quadratic productivity index``.
* Add units to categories ``forchheimer linear productivity index`` and ``forchheimer quadratic productivity index``.

1.17.0 (2023-05-02)
-------------------

* Standardize the usage of ``lbmol``
* Add more valid units for ``mole per mass`` category

1.16.0 (2023-04-26)
-------------------

* Add more units for ``mole per mass`` quantity.
* Define a ``molality`` category.

1.15.0 (2023-04-03)
-------------------

* Add ``cubic meter per day per kilogram-force per square centimeter`` (``m3/d/kgf/cm2``) unit to ``productivity index`` category.
* Add gauge pressures units ``Pa(g)``, ``kPa(g)``, ``bar(g)``, and ``kgf/cm2(g)`` to ``pressure`` category.

1.14.1 (2022-11-03)
-------------------

* Add ``mole per mass`` quantity (``mol/kg``).

1.13.0 (2021-11-30)
-------------------

* Update ``Newton second per meter`` unit from ``Ns/m`` to ``N.s/m`` to get unit display consistent with other units in the same category (support for the old unit input added).
* Add ``force per velocity squared`` quantity (``N.s2/m2``, ``lbf.s2/ft2``, ``lbf.s2/in2``, ``kgf.s2/m2``).

1.12.0 (2021-11-08)
-------------------

* ``barril`` is now fully type annotated, being tested with ``mypy``.
* ``Array`` and ``FixedArray`` are ``Generic`` subclasses, parametrized by the container type.

1.11.1 (2021-10-08)
-------------------

* Fixed typos in unit names: ``kilkodynes`` (unit=kdyne) fixed to ``kilodynes``, ``killowatts/cubic metre degree Kelvin`` (unit=kW/m3.K) fixed to ``kilowatts/cubic metre degree Kelvin``.

1.11.0 (2021-06-18)
-------------------

* Add new unit: "Stokes" (``St``).
* Use ``TypeCheckingSupport`` from ``oop-ext 1.1``.
* Add ``cubic feet per day per psi`` (``ft3/psi.d``) unit to ``productivity index`` category.
* Add ``calories/metre hour degree Celsius`` (``cal/m.h.degC``) unit to ``thermal conductivity`` category.
* Add ``calorie/hour square metre deg C`` (``cal/h.m2.degC``) unit to ``heat transfer coefficient`` category.
* Add ``std cubic metres/second`` (``sm3/s``) unit to ``standard volume per time`` category.
* Add ``million std cubic feet/stock tank barrel`` (``MMscf/stb``), ``stock tank barrel/std cubic feet`` (``stb/scf``) and ``stock tank barrel/million std cubic feet`` (``stb/MMscf``) units to ``standard volume per standard volume`` category.

1.10.0 (2020-10-22)
-------------------

* Removing ``thermodynamic temperature`` as default category for ``degF`` and ``degR`` units.

1.9.0 (2020-02-20)
------------------

* New ``classmethod`` ``Array.FromScalars`` that creates an ``Array`` from a ``List[Scalar]``.
* Add new unit: "barrel per second" (``bbl/s``).

1.8.0 (2020-01-10)
------------------

* Add new category: "standard volume per standard volume".
* Move unit ``sm3/sm3`` from "volume per volume" to "standard volume per standard volume".

1.7.2 (2019-10-16)
------------------

* ``_foundation`` has been renamed to ``_util``, and a lot of functions which were not being
  used anymore have been removed.
* Add new unit category mass temperature per mol (``kg.K/mol``).
* Some units have been renamed as they were deemed out-of-place in the oil industry to something more usual (for example, ``1000ft3/d`` became ``Mcf/d``).
  The old representation of those units is still supported, but they will be automatically translated during ``Quantity`` creation, so this change should not affect users much.
* Fix division ``1.0 / a`` where ``a`` is a ``Scalar`` or ``Array`` and also add support for floor
  division, i.e., operations like ``a // b``  where ``a`` and ``b`` are ``Scalar`` or ``Array``
  (and combinations with ``float`` or ``int``).
* Add new unit category for Joule-Thomson coefficient (``K/Pa``).
* Add new temperature unit for density derivative in respect to temperature (``kg/m3.K``).

1.7.1 (2019-10-03)
------------------

* Fixed bug in ``/`` and ``-`` operators for ``FixedArray``.

1.7.0 (2019-06-18)
------------------

* Add unit system.

1.6.1 (2019-04-11)
------------------

* Change export to include ICurve and Curve and exclude IReadOnlyScalar.

1.6.0 (2019-04-10)
------------------

* Add curve implementation.
* Add support to interfaces from oop-ext.
* Drop support to Python 2.

1.5.0 (2019-01-09)
------------------

* ``Quantity.CheckValue`` now raises ``QuantityValidationError`` instead of ``ValueError``.

1.4.0 (2018-12-17)
------------------

* Add new category for "concentration ratio".

1.3.0 (2018-10-13)
------------------

* Add "per micrometre" unit to "per length" category.
* Remove internal ``barril.fixtures``  module as it is not necessary or part of the public API.

1.2.0 (2018-09-26)
------------------

* Add units for defining Spring-Dashpot movements.

1.1.0 (2018-09-24)
------------------

* Add ``number`` and ``fraction`` properties to ``FractionValue``.
* Add ``unit`` read-only property to ``Quantity``.


1.0.0 (2018-09-21)
------------------

* First feature release.

0.1.0 (2018-09-03)
------------------

* First release on PyPI.