Surefold
On this page

Computation engine · Rust

Watershed

Describe a calculation once. Choose how it runs afterwards.

Watershed holds your model as a graph of formulas and what each one depends on. From that one description it updates only what a change touches, runs millions of scenarios on GPUs with no GPU code from you, and brings a finished batch up to date without running it again.

  • 58 µsto update after one change
  • 10.2 sfor 10,000 scenarios on one GPU
  • 0.2 sto bring all 10,000 results up to date after a change, against 11.2 s to rerun
  • 70 sfor 2,000,000 scenarios on eight GPUs

One insurance model of 19.9 million calculations, written once, in all four. How they were measured.

See it run

This is the engine itself, compiled to WebAssembly, on a small model of an order. Edit an input or press one of the changes. The engine reports which formulas it recalculated, and the page shows them: highlighted where the value changed, green where it came out the same and the update stopped, faded where nothing was looked at.

The model, as it is written. With JavaScript on, this becomes the live graph.

inputs    qty = 10    price = 2.5    tax_rate = 0.2    free_shipping_over = 50

subtotal      = qty * price
with_tax      = subtotal * (1 + tax_rate)
free_shipping = with_tax >= free_shipping_over
shipping      = if free_shipping then 0 else 4.99
total         = with_tax + shipping

price to 3.0        recalculates subtotal, with_tax, free_shipping and total; shipping is not looked at
tax_rate to 0.25    recalculates with_tax, free_shipping and total; subtotal keeps its value
qty 5 and price 5   recalculates subtotal, which comes out the same, and nothing else
Then switch to Run scenarios: the same formulas compiled to a plan and run for three prices at once, or for a hundred thousand, while the graph you edited keeps its values.

Every update is also checked against recalculating everything, and the two agree. The playground has this model and three others, lets any value explain itself, runs each as a plan over a million scenarios, and times one change against recalculating everything on a graph of a million nodes.

What you can do with it

You write each policy, trade, loan or row as ordinary typed formulas. Watershed records the dependencies between them, and everything here follows from that record.

  • Update in proportion to the changeSet an input and only what depends on it is recalculated, stopping wherever a value comes out the same.
  • Run one model across millions of scenariosName the inputs that vary and the outputs you want. Watershed compiles the plan and the GPU kernels.
  • Keep a finished batch current ExperimentalChange one input after a batch and only the part it reaches is rerun, for every scenario.
  • Spread a batch across GPUs ExperimentalA plan saves to a file and runs in lots, handed to one worker per GPU and moved if a worker stops.
  • Ask any number whyEvery result prints the tree of values behind it, as it is now or as it stood at an earlier update.
  • Tables that total themselvesKeyed collections whose columns, totals and group totals update by the rows that changed.

Why it matters

A model that has to react to changes and also run across many scenarios usually ends up written twice: once so that a change is cheap, and again as an array program for batch runs. The two are then kept in agreement by hand.

Watershed keeps one description, and tests hold every way of running it to the same numbers. Execution becomes a decision you make later. The same model can absorb changes on a CPU, run ten thousand market paths on a GPU, and spread over eight GPUs when the batch grows, without being touched.

How execution works

The model says what is calculated. How it runs is decided separately, in three steps that build on each other.

  1. ComposeDescribe the calculation and its dependencies. Nothing here says how it will run.
    • Typed formulas over named inputs
    • Conditionals that depend only on the branch taken
    • Collections, totals and groups
    • Formulas from text or a workbook
  2. ExecuteRun it the way the question needs.
    • An update that reaches only what changed
    • A plan for batches: levels, kernels, reused memory
    • CPU threads or a GPU, as you choose
    • Data kept on the GPU between runs
    • Fused kernels Experimental
  3. ScaleGrow the same model to more scenarios and more hardware.
    • Thousands to millions of scenarios from one plan
    • Assumptions replaced without recompiling
    • A finished batch refreshed after a change Experimental
    • Lots across several GPUs Experimental
Each step uses what the one before recorded. Nothing is rewritten on the way.

Compose

A model is inputs and formulas. Watershed records what every formula reads, including which branch of a condition it took, and that record is the whole interface between your model and how it runs. The same graph can be updated, compiled, saved and split without the formulas knowing.

Execute

An update follows the record forwards from a change, lowest level first, and stops at any value that comes out the same. A plan follows it backwards from the outputs you want and compiles what they need for a batch of scenarios. Three parts of the plan do most of the work.

  • Execution planning

    34 kernelsrun 19.9 million calculations, in 344,124 values of working memory per scenario

    The plan sorts calculations into levels that can each run at once, compiles one kernel for every kind of arithmetic, and reuses a value’s storage after its last reader. That is what lets thousands of scenarios share one GPU.

  • Moving data only when it pays

    280 ms to 5 msa run, repricing five million policies on a GPU

    For a small model the arithmetic is nearly free and the cost is the copying. A plan and its inputs can stay on the GPU between runs, with results totalled there and only the totals returned.

  • Fusion Experimental

    12.2 s to 1.8 sfor 25,000 scenarios on an A100, once compiled

    By default a GPU thread does one calculation and writes it to memory for the next. Fusion gives a thread a whole group of calculations that feed one another: 1,741 kernel launches a pass where there were 6,027.

You choose where a plan runs. Calculations that are the same in every scenario run once on the CPU; the rest go to CPU threads or a GPU. A GPU does about 50 times the work per second of 32 CPU threads once a plan is large, and the two break even at a few million calculations in total, so small models belong on CPU threads. Choosing automatically from measured costs is research in progress.

Deeper: how updates work, how plans work, and the research note on choosing between CPU and GPU.

Scale

One plan runs any number of scenarios, and a stress test replaces a few shared assumptions and runs again with nothing recompiled. When an input changes after a batch, a refresh reruns only the part of the plan the change reaches, for every scenario.

Scenarios are independent, so a saved plan also runs in lots anywhere. The cluster module, built on Surefold’s actors and cluster, gives each worker one GPU and hands a lot to another worker if one stops or hangs. It has run on eight GPUs in one machine.

These stack. The 70-second run at the top of this page is a fused plan, saved to a file, run in lots by eight workers, and checked bit for bit against an unfused plan in one process.

Applications

Each of these is a working example in the repository, with its checks and its timings. The books, economies and populations are made up, except where an example says its data is real; the techniques are the ones used in practice.

A book that changes all day

Policies are amended, records corrected, trades arrive late. Rerunning the whole book for each is slow, and writing a shortcut for each kind of change means maintaining a second calculation.

In Watershed the change is set on the model and the engine works out what follows from it.

On a book of a million policies one amendment took 58 µs. A day of 100,000 amendments is 5.8 seconds of calculation.

Risk across thousands of market paths

What a guarantee costs, what a loan book will lose, whether a pension scheme runs out of money: each depends on the path the economy takes, so the model is run along thousands of paths.

The plan and its GPU kernels are compiled from the formulas you already have. Changing an assumption for a stress test replaces a few shared numbers and runs again, with nothing recompiled.

An insurance book on 10,000 paths ran in 10.2 s on one GPU, a loan book in 6.3 s and a pension scheme in 0.7 s. A million valuations for a nested capital calculation took 3 minutes.

Searching over a large population

Finding a price, a dose or a rule means trying many candidates against the same millions of customers, patients or households. The population does not change between candidates; only a few parameters do.

Watershed loads the population onto the GPU once. Each candidate changes the shared inputs, runs, and returns only totals.

A thousand price reviews over five million motor policies took 5 seconds. Fifty-one dosing protocols over five million simulated patients, each followed for 72 hours, took 3 seconds.

Two records that have to agree

Two parties record the same events, the records arrive in batches, and by the end of the day they have to reconcile. Each party also has a position that follows from them.

In Watershed each record is a row and the rules are formulas over rows. Every count, total and position is current after each batch, and a corrected record updates only what depends on it.

On a real week of Great Britain’s grid, 685,720 meter readings for 286 parties, each reading was reconciled as it arrived in about 10 µs, and a corrected one in 15 µs. The grid study says what is real and what is made up.

Results that have to stay current

A batch of scenario results is out of date the moment an input changes. During a trading day or a quote, running the batch again is too slow to be useful.

Watershed keeps chosen values from the batch and reruns only what the change reaches, for every scenario.

All 10,000 results for the insurance book came up to date in 0.2 s against 11.2 s for a rerun, and a loan book’s in 30 ms against 7.2 s, with identical results. This is experimental and suits changes that reach a small part of the model.

A spreadsheet, ten million times

A valuation workbook holds a model someone trusts. Running it across a range of assumptions usually means rebuilding it in code.

Watershed reads the formulas from the .xlsx file and runs them as a plan.

Ten million trials of one public valuation workbook ran in 0.46 s on a GPU and 1.8 s on CPU threads, with every one of its 176 cells agreeing with the values Excel stored. It has been tried on one workbook and reads a limited set of functions.

Live tables in the browser

A grid of positions or orders where every cell, column and total is a formula, and edits arrive continuously. The usual way is to work it out on a server and send the page each result.

The engine compiles to WebAssembly, so the whole graph runs in the page: formulas, totals, grouping, sorting and history. A change is recalculated where it is made, with no round trip, and the server only has to send the inputs. The engine can run in a Web Worker, so a large load leaves the page free: a million rows load while the page's longest pause is 21 ms. The grid is published as packages: a Table that holds the rows, and a grid component for Solid or React. The engine is 224 KB of WebAssembly, gzipped.

The data grid holds 50,000 rows. Five price changes recalculate 19 of its 550,007 values. The same page is built in Solid and in React.

Performance and research

Every figure on this page is measured on the hardware named. These are the questions the studies answer.

Findings from the benchmark studies · one synthetic insurance model unless it says otherwise
QuestionWhat we measuredWhere
Which work suits a GPU?A large model over many scenarios. 10,000 scenarios of 19.9 million calculations took 10.2 s on one RTX 3090, and about 7.5 minutes on 32 CPU threadsBenchmark study
When are CPU threads the better choice?Small models. A 49-calculation tax model over ten million households takes 0.6 s on either, because the GPU’s 19 ms of arithmetic is outweighed by transfersMeasurements
What does a change after a batch cost?0.14 to 0.22 s against 11.2 s to rerun, over five different changes, with identical resultsCombining the two paths
Does a batch divide across GPUs?Two million scenarios took 18 min 46 s on one A100 and 2 min 43 s on eight, 6.9 times faster. With fusion, 70 sEight-GPU study
Does generated GPU code keep up with hand-written?With fusion, yes on this model. Repeat runs on one RTX 3090: 6.2 s fused, 6.1 s for a hand-tuned JAX program, 9.4 s unfused. Fusion costs compile time, so it lost on a short batchFusion
Are the numbers right?The model agrees with lifelib, the open-source reference it follows, to 3.1 × 10⁻¹³. A plan on CPU threads is bit-identical to the graphCorrectness checks
Where each figure on this page comes from
Hardware, how many runs, and where the method is written down
FigureHardwareHow it was measuredMethod
58 µs for one changeRyzen 9 5950XMedian of five runs, each the mean of 1,000 changes to different recordsMeasurements
10.2 s for 10,000 scenariosOne RTX 3090Median of five runs. Includes copying data to and from the GPU and compiling its kernelsMeasurements
0.2 s against 11.2 sThe same desktop; the refresh runs on CPU threadsFive different changes, each a median of five runs: 0.14 to 0.22 sMeasurements
70 s, 2 min 43 s and 18 min 46 s for 2,000,000 scenariosEight A100 (40 GB) GPUs in one rented machineEight GPUs on the plain plan twice (163 and 166 s); the others once. From the job starting to its last resultEight-GPU study
34 kernels, 344,124 valuesNone: the plan’s own structureRead from the compiled plan of the insurance modelHow the plan compiler works
280 ms to 5 ms a runOne RTX 3090280 ms is the median of 20 runs with data copied each time, kernels already compiled. 5 ms is 1,000 repricings in 5.0 s with data kept on the GPUMeasurements
12.2 s to 1.8 s with fusionA100 (40 GB)One run each. The median time for 25,000 scenarios after a worker’s first batchEight-GPU study
About 50 times, and the break-evenRyzen 9 5950X and RTX 3090A synthetic model of 2.9 million calculations, three to seven runs of each sizeResearch note
Loans, pensions, pricing, dosing and the workbookOne RTX 3090Medians of five runs, whole runs including transfersMeasurements
6.2 s, 6.1 s and 9.4 s on repeat runsOne RTX 3090Median of 40 fused runs, ten JAX runs and a range of unfused runs, with kernels compiledEngine README

CPU figures quoted beside GPU ones are the same plan on 32 threads of the same desktop. Where one is scaled up from a sample, the measurements page says so.

Get started

The quickest start is the playground, with nothing to install. To build with Watershed, pick a language. Everything is pre-release and built from source, so each route needs a Rust toolchain.

Rust

The whole engine: updates, scenario plans, GPU execution.

Cargo.toml
[dependencies]
watershed-core = { git = "https://github.com/surefold/watershed" }
watershed-gpu  = { git = "https://github.com/surefold/watershed" }   # scenario plans; CPU threads by default
src/main.rs: change an input, then run the same model for three scenarios
use watershed_core::prelude::*;
use watershed_gpu::Scenarios;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut g = Graph::new();
    let qty = g.input("qty", 10.0)?;
    let price = g.input("price", 2.5)?;
    let tax = g.input("tax_rate", 0.2)?;
    let subtotal = g.define("subtotal", qty * price)?;
    let total = g.define("total", subtotal * (1.0 + tax))?;

    // Incremental: change one input and stabilise.
    g.set(price, 3.0)?;
    let report = g.stabilize();
    assert_eq!(g.get(total)?, 36.0);
    assert_eq!(report.recalculated, 2);        // subtotal and total
    println!("{}", g.explain(total));          // why total has its value, as a tree

    // Scenarios: vary `price`, read `total`, on all CPU cores.
    let plan = Scenarios::new(&g, &[price.id()], &[total.id()])?;
    assert_eq!(plan.run_cpu(&[2.5, 3.0, 4.0]), [30.0, 36.0, 48.0]);
    assert_eq!(g.get(total)?, 36.0);           // the graph is untouched
    Ok(())
}
cargo run prints
total = 36  ← subtotal * (1 + tax_rate)  [changed]
├── tax_rate = 0.2  (input)
└── subtotal = 30  ← qty * price  [changed]
    ├── qty = 10  (input)
    └── price = 3  (input)  [changed]

With the cuda feature, Gpu::new()?.run(&plan, &inputs) runs the same plan on a GPU. For a model of realistic size that needs no data files:

In a clone of the repository: a mortgage book on CPU threads, then full size on a GPU
cargo run --release -p watershed-gpu --example loans -- 2000 1000
cargo run --release -p watershed-gpu --features cuda --example loans

Python

The incremental engine, collections, formulas as text and explanation. Scenario plans are not exposed to Python yet. Python 3.9 or later.

Install from the repository
pip install "git+https://github.com/surefold/watershed#subdirectory=crates/watershed-py"
Change an input and see what was recalculated
import watershed as ws

g = ws.Graph()
qty = g.input("qty", 10.0)
price = g.input("price", 2.5)
tax = g.input("tax_rate", 0.2)
subtotal = g.define("subtotal", qty * price)
total = g.define("total", subtotal * (1 + tax))

g.set(price, 3.0)
g.stabilize()            # recalculates subtotal and total, nothing else
print(total.value)       # 36.0
print(g.explain(total))  # why total has its value, as a tree

It prints 36.0 and the same tree as the Rust example. Next: collections, grouping and formulas as text in the Python guide, which also lists what the bindings cover.

Kotlin

The incremental engine with typed expressions and failures as values. Scenario plans and the cluster are experimental. Needs JDK 25 and sbt.

Run the example program
git clone https://github.com/surefold/watershed-jvm && cd watershed-jvm
sbt exampleKotlin/run
From examples/kotlin, the program that command runs
fun main() = attempt<Refused, Unit> { tour() }.fold({ logError("refused: ${it.why}") }, {})

context(_: Fail<Refused>)
private fun tour() {
    val g = Graph()
    val qty = g.input("qty", 10.0)          // Input<Double>
    val price = g.input("price", 2.5)
    val taxRate = g.input("tax rate", 0.2)

    val subtotal = g.define("subtotal", qty * price)            // Node<Double>
    val total = g.define("total", subtotal * (1 + taxRate))

    // Change one input: only what depends on it is recalculated.
    g[price] = 3.0
    g.stabilize()
    logInfo("total = ${g[total]}")
    logInfo(g.explain(total))
}

It logs total = 36.0 and the tree behind it. Nothing the engine does throws: a call it can refuse is made in a scope that declares it. The full program goes on to decimals, collections and history, and the README covers scenario plans.

Scala

The incremental engine with typed expressions, in Scala 3. Scenario plans are Kotlin only so far. Needs JDK 25 and sbt.

Run the example program
git clone https://github.com/surefold/watershed-jvm && cd watershed-jvm
sbt exampleScala/run
From examples/scala, the program that command runs
@main def run(): Unit = attempt(tour()).left.foreach(refused => log(s"refused: ${refused.why}"))

private def tour()(using Refusing): Unit =
  val g = Graph()
  val qty = g.input("qty", 10.0)            // Input[Double]
  val price = g.input("price", 2.5)
  val taxRate = g.input("tax rate", 0.2)

  val subtotal = g.define("subtotal", qty * price)            // Node[Double]
  val total = g.define("total", subtotal * (1 + taxRate))

  // Change one input: only what depends on it is recalculated.
  g(price) = 3.0
  g.stabilize()
  log(s"total = ${g(total)}")
  log(g.explain(total))

It logs total = 36.0 and the tree behind it. The full program goes on to decimals, collections and history.

Browser

The data grid, as packages on GitHub Packages: @surefold/grid (a Table and a grid with no framework), @surefold/grid-solid and @surefold/grid-react. A table holds keyed rows with fields, formulas and totals; the grid draws it, and redraws what each change reaches.

Install from GitHub Packages, with a token that has read:packages
echo '@surefold:registry=https://npm.pkg.github.com' >> .npmrc
echo '//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}' >> .npmrc
npm install @surefold/grid-react      # or @surefold/grid-solid, or @surefold/grid
A table of orders, its total followed in React
import { Table } from '@surefold/grid';
import '@surefold/grid/grid.css';
import { Grid, useTotal } from '@surefold/grid-react';

const orders = new Table({
  fields: { region: 'text', qty: 'number', price: 'number' },
  formulas: { line: 'qty * price' },
  totals: { qty: 'sum', line: 'sum' },
});
orders.put('o-1', { region: 'EU', qty: 2, price: 10 });

function Orders() {
  const line = useTotal(orders, 'line');           // 20, then 50
  return <><p>{line}</p><Grid table={orders} style={{ height: 400 }} /></>;
}

orders.set('o-1', 'qty', 5);                       // recalculates o-1's line and two totals
orders.why('o-1', 'line');                         // what line was worked out from

orders.sort([{ column: 'line', desc: true }]);     // the grid shows it, and its headers set it
orders.filter('region', '=EU|US');                 // also >100, 5..10, or text to find
orders.viewState();                                // { sort, filters, search, group }

Sorting, filtering, searching and grouping belong to the table, so code and the grid set them alike; the data grid's "From code" buttons do it that way. The cookbook has whole examples that run on the page, in Solid and React: rows from an API, loading as you scroll, saving edits back, WebSocket and SSE streams, charts and a table in a worker. The package README has the whole API. The engine itself, with the playground’s models and scenario plans, builds from the repository with web/build.sh; the playground’s source uses it.

Engine
Rust, no unsafe in the core
Scenario execution
CPU threads, or CUDA (optional)
Licence
Apache 2.0

Watershed is independent of the other Surefold projects.

What is built today

Built and tested

  • Incremental updates with dynamic dependencies and early cutoff
  • Typed values: f64, i64, exact decimals, booleans, strings
  • Collections, totals and grouping
  • History, explanation and change sinks
  • Formulas parsed from text
  • Scenario plans on CPU threads and CUDA
  • Plans and inputs resident on the GPU, totals on the device
  • Python, Kotlin, Scala and WebAssembly interfaces to the incremental engine

Experimental

  • Refreshing a batch after a change. Suits changes that reach a small part of the model
  • Fused kernels. Off by default; pays on a large plan run many times
  • Saved plans and lots across GPUs. Run on eight GPUs in one machine
  • Scenario plans from Kotlin, and in the browser on one thread
  • Reading a model from an .xlsx workbook. One workbook tried

Research and planned

  • Choosing CPU or GPU automatically from measured costs
  • Choosing what to fuse from profiles
  • Workers on several machines
  • A release on crates.io

Details for each are in the core guide, how plans work and watershed-jvm.

Limits worth knowing

  • Plans cover numeric formulas. f64 and bool with arithmetic, min, max, abs, exp, ln, sqrt, pow, comparisons, logic and conditionals; collection and group totals (sum, min, max, count), bit for bit the graph's; and choose by an option number that is the same in every scenario. Integer arithmetic, decimals and text are incremental only, and a plan names the node it cannot take.
  • Setup is paid once. Building a graph and compiling a plan each take about a microsecond a node, around 40 s for the insurance model. Watershed earns that back on the second run and every change after; for a single valuation from nothing, an array program that valued the same book in 3.6 s is the quicker tool.
  • GPU agreement has documented allowances. CPU and GPU results are tested for bit equality, allowing for NaN payloads, signed zero and rounding in exp, ln and pow.
  • CUDA only on the GPU side, and APIs may change before a release.

The full list is in the README.

Where to go next