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

• Create a release-VERSION branch from upstream/master.
• Update CHANGELOG.rst.
• Push a branch with the changes.
• Once all builds pass, push a VERSION tag to upstream.
• 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.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.