API Overview
Units
Categories and Related Units
The following data structure lists the supported unit type/categories and actual units supported for each category:
{
density: ['sg', 'ppg', 'kg/m3', 'lb/ft3'],
diameters: ['in', 'm', 'ft'],
dls: ['deg/30m', 'deg/100ft'],
duration: ['s', 'h', 'd', 'min'],
length: ['m', 'ft', 'km', 'in'],
pressurechange: ['bar', 'psi', 'Pa', 'MPa', 'kPa'],
temperature: ['C', 'F', 'K'],
tempgrad: ['C/100m', 'F/100ft', 'C/m', 'F/ft', 'K/m'],
volume: ['m3', 'ft3', 'bbl', 'STB', 'Sm3', 'MMSCF', 'MSm3', 'SCF'],
weight: ['tonnes', 'kg', 'mt', 'lbf', 'kip', 'N'],
force: ['N', 'lbf', 'tonnes'],
torqueGradient: ['N', 'lbf'],
wgrad: ['sg', 'ppg'],
wltubulars: ['ppf', 'kg/m'],
weightGradient: ['ppf', 'kg/m'],
flowrate: ['lpm', 'bpm', 'm3/s', 'm3/d', 'gpm', 'ft3/s', 'ft3/d', 'Mm3/d', 'bbl/d', 'MMSCFD', 'STB/d', 'Sm3/d', 'MSm3/d', 'SCF/d'],
massFlowRate: ['kg/s', 'lbm/s'],
permeability: ['mD', 'm2'],
interfacialTension: ['dyn/cm', 'N/m', 'mN/m', 'lbf/ft'],
forceGradient: ['N/m', 'lbf/ft'],
percentage: ['%', 'fr'],
deg: ['deg', 'rad'],
power: ['W', 'kW', 'MW', 'hp', 'BTU/h'],
latitude: ['°N', '°S'],
longitude: ['°E', '°W'],
speed: ['m/s', 'ft/s', 'm/min', 'ft/min', 'm/h', 'ft/h', 'mph'],
acceleration: ['m/s2', 'ft/s2'],
torque: ['Nm', 'ftlbf'],
rpm: ['rpm', 'Hz'],
sdstats: ['CI', 'Sigma'],
viscosity: ['Pa*s', 'P', 'mPa*s', 'cP'],
pressureGradient: ['Pa/m', 'bar/m', 'bar/100m', 'psi/ft', 'psi/100ft'],
angleGradient: ['deg/30m', 'deg/100ft', 'deg/m', 'deg/m', 'deg/ft', 'rad/m', 'rad/ft'],
intensity: ['W/m2', 'hhp/in2', 'hhp/ft2'],
gor: ['Sm3/Sm3', 'SCF/STB']
}
Unit Values
Inside the application (and API), unit values are stored as a pipe separated string, where the first value is the numerical value and the second value is the unit. E.g. 100|m means "100 meters", and 100|ft means "100 feet".
Unit Tables
To keep tables simple (and to support copy/paste from/to spreadsheets), tables with units are supported by indicating the unit of each column in a first unit row. For instance the first row ['ft', 'deg/100ft'] indicates a table where the first column (in the rows below) are given in feet and degrees per 100 ft (unit category dls, dogleg severity).
Load Cases and External Gradients
Load Cases and External Gradients typically contains a reference to a type and it's input parameters. Load cases is typically a list of depth internal pressure values, while external gradients is similar but with external pressure values. These are combined to create the differential pressure used in calculating casing loads (internal pressure - external pressure).
The type value indicates whether this is a load case or an external gradient.
In the paramdefs list, the order is important. Arguments to load cases etc need to be passed as a list of strings (with units). The d is short for description and explains what the parameter is (and used as a label in the app GUI). u denotes the unit category, what type of value this is, e.g. length or wgrad, which again indicates what kind of units are supported for that category. The ucalc indicates what the load case expects, and what value any type of unit value gets converted to before it is fed to the calculation engines.
Please note that paramdefs etc is not needed when using the API directly; it's mostly used by the app GUI for helping users get the correct values in the right places.
The following list shows the currently supported load cases, types, parameters definitions and parameter default values (what the GUI uses as defaults when one of these get added to a dataset):
[
{
"default_params": ["mw", "hid", "0"],
"id": "hydrostatic_isolation_depth",
"name": "Hydrostatic Isolation Depth",
"paramdefs": {
"paramdefs": [
{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "HID", "t": "num", "u": "length", "ucalc": "mMD"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "eg"
},
{
"id": "frac_prev_shoe_gg_above",
"name": "Frac@Prev Shoe/GG above",
"paramdefs": {
"paramdefs": [
{"d": "Gas gravity", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "FG below prev shoe", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Frac. error margin", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "eg"
},
{
"default_params": ["1.1|sg"],
"id": "mud_cement_mix_water",
"name": "Mud and Cement Mix-Water",
"paramdefs": {
"paramdefs": [
{"d": "Cem.mix/water d.", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": [1],
"id": "min_form_pore_pressure",
"name": "Minimum Formation Pore Pressure",
"paramdefs": {
"paramdefs": [
{"d": "Cem.mix/water d.", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Mud.Dr=1,No=0", "t": "bool", "u": "0/1"},
{"d": "0=P.Shoe,1=TOC", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": ["pp_prev_shoe", "mw"],
"id": "shoe_mud_grad_w_pp",
"name": "Shoe/Mud grad. w/PP",
"paramdefs": {
"paramdefs": [
{"d": "PP Prev.Shoe", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Mw above TOC", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "eg"
},
{
"default_params": ["0.998"],
"id": "above_below_prior_shoe",
"name": "Above/Below Prior Shoe",
"paramdefs": {
"paramdefs": [{"d": "Cem.mix/water d.", "t": "num", "u": "wgrad", "ucalc": "sg"}]
},
"type": "eg"
},
{
"default_params": ["mw", "1"],
"id": "fluid_gradients_burst",
"name": "Fluid Gradients (Burst)",
"paramdefs": {
"paramdefs": [
{"d": "FG above TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "FG below TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": ["mw", "mw"],
"id": "fluid_gradients_collapse",
"name": "Fluid Gradients (Coll.)",
"paramdefs": {
"paramdefs": [
{"d": "FG above TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "FG below TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": ["mw", "mw"],
"id": "fluid_grad_w_pp_collapse",
"name": "Fluid Gradients w/PP (Collapse)",
"paramdefs": {
"paramdefs": [
{"d": "FG above TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "FG below TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": ["mw", "1"],
"id": "fluid_grad_w_pp_burst",
"name": "Fluid Gradients w/PP (Burst)",
"paramdefs": {
"paramdefs": [
{"d": "FG above TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "FG below TOC", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}
]
},
"type": "eg"
},
{
"id": "mud_cem_slurry",
"name": "Mud and Cement Slurry",
"paramdefs": {"paramdefs": [{"d": "SC Emu/No SW", "t": "bool", "u": "0/1"}]},
"type": "eg"
},
{
"default_params": ["max_pp_bottom_next_oh_section_md", "0", "mw_next", "gas_gradient", "", "0"],
"id": "displacement_to_gas",
"name": "Displacement To Gas",
"paramdefs": {
"paramdefs": [
{"d": "Influx depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Mud/Gas interf.", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg", "usuff": "EMW"},
{"d": "Gas Gradient", "t": "num", "u": "wgrad", "ucalc": "sg", "usuff": "EMW"},
{"d": "Limit frac@shoe", "t": "bool", "u": "0/1"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg", "usuff": "EMW"}
]
},
"type": "lc"
},
{
"default_params": [],
"id": "custom_internal_pressure",
"name": "Custom Internal Pressure",
"paramdefs": {
"paramdefs": [{"d": "Custom Table", "t": "dropdown", "u": "dropdown", "ucalc": ""}]
},
"type": "lc"
},
{
"id": "custom_external_pressure",
"name": "Custom External Pressure",
"paramdefs": {
"paramdefs": [{"d": "Custom Table", "t": "dropdown", "u": "dropdown", "ucalc": ""}]
},
"type": "eg"
},
{
"default_params": ["gas_gradient", ""],
"id": "frac_at_shoe_gg_above",
"name": "Frac@Shoe/GG Above",
"paramdefs": {
"paramdefs": [
{"d": "Gas/Fl.Grad.Ab.", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["mw_next", "0.036"],
"id": "drill_ahead_burst",
"name": "Drill Ahead (Burst)",
"paramdefs": {
"paramdefs": [
{"d": "Mud weight next", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "ECD", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["mw_next", "0.036"],
"id": "drill_ahead_collapse",
"name": "Drill Ahead (Collapse)",
"paramdefs": {
"paramdefs": [
{"d": "Mud weight next", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "ECD", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": [
"max_pp_bottom_next_oh_section_md",
"gas_vol_next_casing_last_liner",
0,
"mw_next",
0.7,
0,
5,
0,
0,
0
],
"id": "gas_kick_profile",
"name": "Gas Kick Profile",
"paramdefs": {
"paramdefs": [
{"d": "Influx depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Kick volume", "t": "num", "u": "volume", "ucalc": "m3"},
{"d": "Kick intensity", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Max mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Kick gas gravity", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Fracture MoE", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "DP OD", "t": "num", "u": "diameters", "ucalc": "in"},
{"d": "Collar OD", "t": "num", "u": "diameters", "ucalc": "in"},
{"d": "Collar length", "t": "num", "u": "length", "ucalc": "m"},
{"d": "Limit frac@shoe", "t": "bool", "u": "0/1"}
]
},
"type": "lc"
},
{
"default_params": ["0", "mw"],
"id": "pressure_test",
"name": "Pressure Test",
"paramdefs": {
"paramdefs": [
{"d": "Test Pressure", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "Fluid.d", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["surface_35_70", "mw_next", 0],
"id": "pa_pressure_test",
"name": "P&A Pressure Test",
"paramdefs": {
"paramdefs": [
{"d": "Surf.p.", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "MW in Hole", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["0", "mw"],
"id": "green_cem_pt_burst",
"name": "Green Cement Pressure Test (Burst)",
"paramdefs": {
"paramdefs": [
{"d": "Surf.p", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "Fluid.d", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["max_pp_bottom_next_oh_section_md", "packer_depth", "sw_sg", "gas_gravity"],
"id": "tubing_leak",
"name": "Tubing Leak",
"paramdefs": {
"paramdefs": [
{"d": "Perf.Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Packer Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Packer fl.d", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Gas gravity", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["shoe_over_oh_md", "0", "mw_next_casing_last_liner"],
"id": "lost_ret_w_water",
"name": "Lost Returns w/Water",
"paramdefs": {
"paramdefs": [
{"d": "Mud/Water If.", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "MW In Hole", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["gas_gradient", "0.998", "0"],
"id": "surf_protection_bop",
"name": "Surface Protection (BOP)",
"paramdefs": {
"paramdefs": [
{"d": "Gas Gradient", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Water Density", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["sw_sg", "packer_depth", 100, 1],
"id": "stim_surf_leak",
"name": "Stimulation Surface Leak",
"paramdefs": {
"paramdefs": [
{"d": "Packer Fl. Density", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Packer Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Injection Press.", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "Injection Dens..", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": [100, 1],
"id": "inj_down_casing",
"name": "Injection Down Casing",
"paramdefs": {
"paramdefs": [
{"d": "Injection Press.", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "Injection Dens..", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": [100, "sw_sg"],
"id": "perf_gun_pressure",
"name": "Perforating Gun Pressure",
"paramdefs": {
"paramdefs": [
{"d": "Max Trigger Press.", "t": "num", "u": "pressurechange", "ucalc": "bar"},
{"d": "Fluid Dens. w/Perf.", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": [
"max_pp_bottom_next_oh_section_md",
"gas_gradient",
"0",
"mw_next_casing_last_liner",
"50",
"wh_depth",
"0"
],
"id": "gas_over_mud_ratio",
"name": "Gas Over Mud Ratio",
"paramdefs": {
"paramdefs": [
{"d": "Influx depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Gas gradient", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Frac.Err.Margin", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Mud@Shoe Next", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Gas Percent", "t": "num", "u": "percentage", "ucalc": "%"},
{"d": "Depth Ref.", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "MASP/MAWP to Fr.@Shoe", "t": "num", "u": "0/1"},
{"d": "Limit to Frac@Shoe", "t": "num", "u": "0/1"}
]
},
"type": "lc"
},
{
"default_params": ["100", "", "mw_next"],
"id": "casing_evac",
"name": "Casing Evacuation",
"paramdefs": {
"paramdefs": [
{"d": "Pct Evac", "t": "num", "u": "percentage", "ucalc": "%"},
{"d": "Mud Level", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Mud Weight", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": [],
"id": "full_evac",
"name": "Full Evacuation",
"paramdefs": {"paramdefs": []},
"type": "lc"
},
{
"default_params": ["sw_sg"],
"id": "gas_migration",
"name": "Gas Migration",
"paramdefs": {"paramdefs": [{"d": "Packer fl.d.", "t": "num", "u": "wgrad", "ucalc": "sg"}]},
"type": "lc"
},
{
"default_params": [],
"id": "eg_gas_migration",
"name": "Gas Migration Extgrad",
"paramdefs": {
"paramdefs": [
{"d": "Fluid.d", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Limit to Frac@Shoe", "t": "num", "u": "0/1"}
]
},
"type": "eg"
},
{
"default_params": ["min_pp_bottom_next_oh_section_md", "mw_next"],
"id": "lost_returns_w_mud_drop",
"name": "Lost Returns With Mud Drop",
"paramdefs": {
"paramdefs": [
{"d": "Lost Ret. Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Mud Weight", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["mw"],
"id": "cementing",
"name": "Cementing",
"paramdefs": {"paramdefs": [{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"}]},
"type": "lc"
},
{
"default_params": [1.0324129651860743, "gas_gradient"],
"id": "wcst",
"name": "WCST",
"paramdefs": {
"paramdefs": [
{"d": "Seawater grad.", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Gas/Oil grad.", "t": "num", "u": "wgrad", "ucalc": "sg"}
]
},
"type": "lc"
},
{
"default_params": ["max_fp_bottom_next_oh_section_md", "packer_depth", "sw_sg", 0, "0"],
"id": "above_below_packer",
"name": "Above/Below Packer",
"paramdefs": {
"paramdefs": [
{"d": "Perf. Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Packer Depth", "t": "num", "u": "length", "ucalc": "m", "usuff": "MD"},
{"d": "Dens.Above Packer", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Dens.Below Packer.", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Fluid Drop Above Packer", "t": "num", "u": "0/1"}
]
},
"type": "lc"
},
{
"default_params": [10],
"id": "green_cem_pt",
"lctype": "axial",
"name": "Green Cement Pressure Test (Axial)",
"paramdefs": {
"paramdefs": [{"d": "Surface pressure", "t": "num", "u": "pressurechange", "ucalc": "bar"}]
},
"type": "lc"
},
{
"default_params": ["51|tonnes"],
"id": "overpull",
"lctype": "axial",
"name": "Overpull",
"paramdefs": {
"paramdefs": [{"d": "Overpull force", "t": "num", "u": "weight", "ucalc": "tonnes"}]
},
"type": "lc"
},
{
"default_params": [1],
"id": "running_in_hole",
"lctype": "axial",
"name": "Running in hole",
"paramdefs": {"paramdefs": [{"d": "Running speed", "t": "num", "u": "speed", "ucalc": "m/s"}]},
"type": "lc"
},
{
"default_params": ["0tonnes"],
"id": "pre_cem_static_load",
"lctype": "axial",
"name": "Pre-Cement Static Load",
"paramdefs": {
"paramdefs": [{"d": "Applied force", "t": "num", "u": "weight", "ucalc": "tonnes"}]
},
"type": "lc"
},
{
"id": "post_cem_static_load",
"lctype": "axial",
"name": "Post-Cement Static Load",
"paramdefs": {"paramdefs": []},
"type": "lc"
},
{
"default_params": ["mw"],
"id": "riser_margin",
"lctype": "collapse",
"name": "Riser Margin",
"paramdefs": {"paramdefs": [{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"}]},
"type": "lc"
},
{
"default_params": ["mw"],
"id": "fluid_grad_open_water",
"name": "Fluid Gradient for Open Water",
"paramdefs": {"paramdefs": [{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"}]},
"type": "eg"
},
{
"default_params": ["mw", "hid", "0"],
"id": "fluid_grad_apb",
"name": "Fluid Gradient w/APB",
"paramdefs": {
"paramdefs": [
{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "HID", "t": "num", "u": "length", "ucalc": "m"},
{"d": "APB", "t": "num", "u": "pressurechange", "ucalc": "bar"}
]
},
"type": "eg"
},
{
"default_params": ["mw", 304.8, 34.4738],
"id": "negative_pressure_test",
"lctype": "collapse",
"name": "Negative Pressure Test",
"paramdefs": {
"paramdefs": [
{"d": "Mud weight", "t": "num", "u": "wgrad", "ucalc": "sg"},
{"d": "Seawater height below mudline", "t": "num", "u": "length", "ucalc": "m"},
{"d": "Pressure Drop", "t": "num", "u": "pressurechange", "ucalc": "bar"}
]
},
"type": "lc"
}
]