Units and bare numbers

A model has one unit system, ps.Model(units=...): "metric", "field" or "lab". A loaded deck keeps its own (m.units). Every bare number you type is in that system: a pressure in a METRIC model is barsa, in a FIELD model psia. PetroScript does not guess a unit, so a FIELD gas-oil ratio typed in scf/stb instead of Mscf/stb is 1000 times too high and runs. Two exceptions are in the table below: report-step lengths are days in every system, and an absolute temperature (a component’s critical temperature) is K or degR.

The same rule holds everywhere a number goes: a table column, a control’s target, a rule’s threshold, a lift table’s axis. A run’s results come back in the same system, each frame with a unit column.

The common quantities

Quantity	FIELD	METRIC	LAB
Depth, length, thickness, cell size, well diameter	ft	m	cm
Pressure (BHP, THP, datum, PVT tables)	psia	barsa	atma
Oil, water or liquid rate (surface)	stb/day	sm3/day	scc/hr
Gas rate (surface)	Mscf/day	sm3/day	scc/hr
Reservoir volume rate	rb/day	rm3/day	rcc/hr
Oil or water total	stb	sm3	scc
Gas total	Mscf	sm3	scc
Gas-oil ratio (solution GOR, a GOR rule, a lift-table GOR axis)	Mscf/stb	sm3/sm3	scc/scc
Water-gas or oil-gas ratio	stb/Mscf	sm3/sm3	scc/scc
Water cut	fraction, 0 to 1	fraction	fraction
Water-oil ratio	stb/stb	sm3/sm3	scc/scc
Porosity, saturation, net-to-gross	fraction	fraction	fraction
Permeability	mD	mD	mD
Oil formation volume factor	rb/stb	rm3/sm3	rcc/scc
Gas formation volume factor	rb/Mscf	rm3/sm3	rcc/scc
Viscosity	cP	cP	cP
Density (surface densities)	lb/ft3	kg/m3	g/cc
Compressibility (rock, water)	1/psi	1/bar	1/atm
Temperature	degF	degC	degC
Absolute temperature (a component’s critical temperature, a density’s reference temperature)	degR	K	K
Report-step length (ps.Every)	day	day	day (a LAB deck writes it in hours: ps.Every(1.0) is TSTEP 24)

Three that trip people up:

• Gas-oil ratio in FIELD is Mscf/stb. A GOR of 800 scf/stb is 0.8. A rule ps.actions.well(prod).gas_oil_ratio > 20.0 in a FIELD model shuts at 20 Mscf/stb.
• A water cut is a fraction. 50 % is 0.5, in a rule, a lift-table axis and a result.
• A well diameter is a length. 0.3 ft in FIELD, 0.2 m in METRIC: ps.Perforate(diameter=0.3).

ps.help("units") prints the same rule, and every unit word a ps.Quantity takes.

A number with its own unit

Where a field states what kind of number it is (a pressure, a length, a rate, a permeability, a temperature, a time), it also takes a ps.Quantity(value, unit), which converts on the way in. A rule’s threshold and a table’s column take bare numbers only, so a Quantity there is refused.

import petroscript as ps

m = ps.load("opm-tests/spe1/SPE1CASE1.DATA")        # SPE1: a FIELD deck
assert m.units == "field"

# a datum pressure typed in bar converts to the model's psia
m = m.set("initial/1/datum_pressure", ps.Quantity(330.0, "barsa"))

# a rule's threshold is a bare number in the model's units: 20 Mscf/stb here
producer = m.get("wells/PROD")
rule = ps.actions.When(ps.actions.well(producer).gas_oil_ratio > 20.0,
                       then=[ps.Shut(well="PROD")], name="HIGH_GOR")
m = m.at(m.start, rule)
assert "WGOR 'PROD' > 20" in ps.compile(m).files["SPE1CASE1.DATA"]

try:
    ps.actions.well(producer).gas_oil_ratio > ps.Quantity(20.0, "mscf/stb")
except ValueError as refused:
    print(refused)    # [units.wrong_kind] an expression's number takes a bare number ...

When a number is in the wrong system

m.check() looks for numbers that only make sense in another unit system and says so at their address. The quickstart’s datum pressure, typed in psi into a METRIC model, reads:

warning initial/1/datum_pressure [physics.pressure_gradient.other_unit] The datum pressure 3626
  is 13.4 times the model's own water column at the datum depth 2420 ...; read in psi it is
  0.923 times that column, nearer than the pressure as stated

Fix the number at its address (m.set("initial/1/datum_pressure", 250.0)), or state it as a ps.Quantity with its unit.