What haql-units does
haql-units is a small Python library for converting oil and gas quantities without hiding the assumption. Every conversion carries its definition, time base and source. If the library cannot state the conversion, it raises an error instead of inventing a constant.
In one sentence: It gives the suite one cited unit definition instead of a column of inherited spreadsheet factors.
Convert with confidence
Use declared units and time bases instead of a guessed factor.
Stop silent factors
Make a dimension mismatch fail before it reaches a filing.
Reuse a small library
Add checked conversions without a whole analysis stack.
Why it matters
A wrong unit can survive a summary because the factor is under its resolution. An ambiguous “daily” rate can use a 28-day assumed month. A spreadsheet formula can be inherited with no citation. Units are part of the evidence.
- One export is in Sm³ and another in BBL; the aggregation multiplies by the wrong constant.
- A daily rate is not the same as a rate on a 28-day assumed month; the denominator is a choice.
- Conversion formulas live inside cells, inherited from someone who left in 2019.
- QC only works if the units feeding it are the units you think they are.
A column is labelled “volume”. The aggregation picks a factor, the mismatch lands under the summary's resolution, and it ships.
The unit and time base are declared, the conversion is defined from first principles, and a dimension mismatch raises an error.
What goes in
The library is used in Python; the important input is the declared unit, not the column name.
| What goes in | What it means |
|---|---|
| A quantity | A numeric value with a unit and, where relevant, a time base. |
| A target unit | The unit you want the result in. |
| A declared rate basis | For rates, the time denominator is stated explicitly. |
What comes out
Every result can carry the reasoning behind it.
| What comes out | How to use it |
|---|---|
| Converted value | The numeric result in the requested unit. |
| Conversion explanation | The factor plus the standard and citation that define it. |
| Dimension guard | A TypeError instead of an invalid addition such as bbl plus ft. |
| Round-trip check | The conversion can be inverted and checked. |
What it checks
The library checks the things a spreadsheet formula usually leaves implicit.
| Check area | What it flags |
|---|---|
| Dimension compatibility | Adding or comparing quantities with different dimensions fails early. |
| Time-base declarations | A rate must state the denominator instead of assuming a month length. |
| Conversion definition | The factor is defined from first principles, not copied without a source. |
| Round-trip behaviour | A conversion can be inverted and return the original quantity within tolerance. |
Every factor carries a source such as NIST SP 811 (US National Institute of Standards and Technology), the BIPM SI Brochure (International Bureau of Weights and Measures) or SPE (Society of Petroleum Engineers), so the conversion is an argument rather than a claim.
What it does not do
A useful tool should be clear about its boundaries. These are the current limits, not hidden caveats.
- It is a conversion library, not an automatic data-cleaning or unit-inference tool.
- You still have to declare the unit and time base; the library will not guess from a column name.
- It does not replace a company's measurement standards or regulatory reporting rules.
- A correct conversion does not make the underlying measurement correct.
Findings are advisory. The tool names a contradiction or a risk with the evidence behind it. The engineering, legal or commercial judgement remains with you.
How to try it
Install it in seconds and convert the next export you would otherwise do by hand.
pip install haql-units- Create a quantity with an explicit unit and time base.
- Call
convert_explained()and keep the factor and citation with the result.
Nothing leaves your machine. The paid tools run offline. The free libraries have no account, cloud call or telemetry.
Common questions
Is it really free?
Yes. haql-units is MIT-licensed, with no account, cloud call, seat count or telemetry.
Does it guess units from column names?
No. That is the failure mode it is designed to avoid. You declare the unit.
Can it convert anything?
It covers the oil and gas units and time bases used by the suite. If it cannot state the conversion, it errors rather than inventing a factor.
What is a time base?
The denominator in a rate, such as per day or per month. The same number means different things on a 28-day assumed month versus a calendar day.