Scripting SDK

#Overview

Scripts let you run any Converge engine from JavaScript inside the app, loop over cases, and show the results as tables and plots. You write them on Integrations > Scripts. Each run executes in a fresh, sandboxed Web Worker in your browser, with no network access, and the worker is destroyed when the run ends.

The same engine functions are available over the REST API and to an MCP client, with the same inputs and outputs.

#How a script runs

Your script is the body of an async function, so you can use await at the top level and return a value. These names are in scope:

A return value is shown when the run ends. Every engine call is synchronous and returns plain data (objects, arrays, numbers).

Run with the run button or Ctrl/Cmd + Enter. Choose Time limit (5, 10, 30 or 60 s; 10 s by default). Save to project stores the script in the current project, up to 100 scripts per project; saved scripts are kept in project snapshots and exports.

#The converge object

#Engine functions

Every engine function has the form:

converge.<namespace>.<function>(input, options?)

• input: one object. Unknown keys are an error that lists the valid keys.
• options.units: 'field' (default) or 'metric', for this call only.

An invalid input throws an Error whose message names each bad field, for example converge.well.nodal: invalid input (fluid.api: ...).

#Helpers

describe and example take the full dotted name, for example converge.example('well.nodal'). They throw for an unknown name.

#Units

Field units by default: psia, degF, ft, STB/d, Mscf/d, scf/STB. Pass { units: 'metric' } as the second argument, or call converge.setUnits('metric') once, to send and receive bara, degC, m, sm3/d and sm3/sm3. The main outputs come back in the same system.

converge.setUnits('metric');
const z = converge.pvt.gasProperties({ psia: 200, TF: 90, gasSG: 0.7 }); // 200 bara, 90 degC

A metric result carries a units object: units.system is 'metric' and units.converted lists the output keys that were converted, with their unit. Keys not listed are still in field units.

#Function reference

Inputs listed are the main keys. Call converge.describe(name) for the full schema, defaults and limits.

#pvt (Black-oil PVT)

#eos (Compositional PVT)

fluid is { kind: 'eos', eos, components, plus, split, ... } or { kind: 'spe5' } for the SPE5 benchmark oil. eos is 'PR', 'PR78' (default) or 'SRK'.

#well (Well performance)

#mbal (Material balance)

#dca (Decline & RTA)

points are { t, q } with t in days since first production and q in the rate basis. Nominal declines are 1/day. rateUnit is 'STB/d' (default), 'Mscf/d' or 'sm3/d'.

#welltest (Well test)

#sim (Simulation)

#network (Network)

#integrated (Integrated forecast)

#econ (Economics)

#data (Data)

These two run under the Integrations licence.

#table and plot

#table(data, title?)

data can be:

• an array of objects (columns are the union of the keys),
• an array of arrays (columns col1, col2, ...),
• { columns, rows },
• a plain object (shown as key / value rows).

Nested values are shown as compact JSON, cut at 120 characters.

#plot(series, options?)

series is { name?, x, y } or an array of them; plot(x, y, options?) with two number arrays also works. x and y must have the same length. Pairs with a null or non-finite value are skipped.

options: title, xTitle, yTitle, logX, logY.

#Limits

When the time limit is reached, the worker is terminated, which stops even an endless loop.

#Sandbox rules

• No import anywhere in the script, not even inside a string or a comment. Everything you need is on converge.
• No network or storage: fetch, XMLHttpRequest, WebSocket, indexedDB, navigator and similar are removed.
• No code built from strings: eval, Function and string handlers for setTimeout and setInterval are removed.
• Nothing survives between runs.

#Seats

When you are signed in, the page takes the licence seat for each module a script uses before it runs, and returns the seats when the run ends. It finds them by reading converge.<namespace> in your code. Write calls out literally: a namespace reached another way (for example through a variable) throws converge.<ns> is not available in this run.

#Worked example

This script fits a decline to two years of monthly rates, ranks every model, and plots a five-year forecast. It is one of the built-in examples.

// Monthly rates (days, STB/d). Replace with your own.
const points = [];
for (let i = 0; i < 24; i++) {
  points.push({ t: i * 30.4, q: 1200 / Math.pow(1 + 0.9 * 0.004 * i * 30.4, 1 / 0.9) * (1 + 0.03 * Math.sin(i)) });
}

const fit = converge.dca.fit({ kind: 'arps', points, qEconomic: 20 });
const m = fit.model;
print(`Arps: qi = ${m.qi.toFixed(0)} STB/d, Di = ${m.Di.toFixed(5)} 1/d, b = ${m.b.toFixed(2)}, R2 = ${fit.r2Rate.toFixed(3)}`);
print('EUR to 20 STB/d:', Math.round(fit.eur.eur).toLocaleString(), 'STB');

const ranked = converge.dca.compare({ points, qEconomic: 20 });
table(ranked.map((r) => ({ model: r.kind, 'EUR (STB)': Math.round(r.eur), AIC: r.aic, 'R2 rate': r.r2Rate })), 'Models ranked by AIC');

const f = converge.dca.forecast({ model: fit.model, tMaxDays: 5 * 365.25, stepDays: 30.4 });
plot(
  [
    { name: 'data', x: points.map((p) => p.t), y: points.map((p) => p.q) },
    { name: 'forecast', x: f.t, y: f.q },
  ],
  { title: 'Rate and forecast', xTitle: 'Time (days)', yTitle: 'Rate (STB/d)', logY: true },
);

A second pattern: start from a documented example and vary one input.

const base = converge.example('well.nodal');
const rows = [];
for (const wct of [0, 0.2, 0.4, 0.6, 0.8]) {
  const well = { ...base.well, ratios: { ...base.well.ratios, wct } };
  const op = converge.well.nodal({ well, fluid: base.fluid }).nodal.operating;
  rows.push({ 'water cut': wct, 'liquid (STB/d)': op ? op.q : null, 'pwf (psia)': op ? op.pwf : null });
}
table(rows, 'Operating point vs water cut');

#Related

• REST API
• API keys
• MCP
• Units