Random Sankey Flow Conservation Dataset Generator

Description

Construct synthetic source-to-branch-to-sink flows with exact integer conservation at every intermediate node.

A chart dataset contains values plus the labels, grouping, totals, or missing-value conventions needed to interpret them. Separating the numeric construction from plotting makes conservation rules and deliberate edge cases visible before a chart is rendered.

Construct synthetic source-to-branch-to-sink flows with exact integer conservation at every intermediate node.

When to use this tool

Use this generator to create reproducible sankey flow conservation dataset cases from the supplied model or bank. Inspect the returned evidence before using cases in a test or exercise.

How to use the tool and how it works

Supply source, sink, branches, total in the field shapes below. Set seed when you need an explicit replay.
Run the tool and correct any input error. For generated controls, distinguish a successful fixture containing an invalid case from failure to generate the fixture.
Read links, balances, sourceTotal, sinkTotal. Use the conventions below and keep answer-bearing fields separate when presenting an exercise.

Sequentially split the integer source total among branches, assigning the final branch the residual. Emit source-to-branch and branch-to-sink links with equal branch inflow and outflow and verified source and sink totals.^[1]

Input field	Meaning and units	Accepted input
source	Source	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
sink	Sink	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
branches	Branches	Required. Array of Text; minimum UTF-16 length 1; maximum UTF-16 length 64.; minimum items 1; maximum items 16.
total	Total counted observations or the conserved total identified in the mechanics.	Required. Safe integer; minimum 0; maximum 9007199254740990.
seed	Optional numeric seed; takes precedence over context randomness. Without either, use the fixed tool.io default seed.	Optional. Safe integer.

Output field	Interpretation	Returned shape
links	Links	Required. Array of Object; no unknown keys.; minimum items 2; maximum items 32.
links[].source	Source	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
links[].target	Target	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
links[].value	Value	Required. Safe integer.
balances	Balances	Required. Array of Object; no unknown keys.; minimum items 1; maximum items 16.
balances[].id	Literal identifier used to match records, independently of their display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 64.
balances[].inflow	Inflow	Required. Safe integer.
balances[].outflow	Outflow	Required. Safe integer.
sourceTotal	Source Total	Required. Safe integer.
sinkTotal	Sink Total	Required. Safe integer.
randomness	Replay metadata: source is seed or context; seed is the normalized 32-bit seed or null for a context source.	Required. Object; no unknown keys.
randomness.seed	Optional numeric replay seed; normalization and precedence are explained below.	Required. Safe integer. or Null.
randomness.source	Source	Required. Text; one of "context", "seed".

An explicit safe-integer seed takes precedence over injected context randomness and is normalized to an unsigned 32-bit integer. With no seed and no context source, replay uses the fixed tool.io default seed. A context source must return finite values from zero inclusive to one exclusive; its advancing state must be retained separately. randomness records the source and normalized seed, or null for context. These generators are not cryptographic random sources.

json

{
  "input": {
    "source": "in",
    "sink": "out",
    "branches": [
      "a",
      "b"
    ],
    "total": 10,
    "seed": 42
  },
  "output": {
    "links": [
      {
        "source": "in",
        "target": "a",
        "value": 6
      },
      {
        "source": "a",
        "target": "out",
        "value": 6
      },
      {
        "source": "in",
        "target": "b",
        "value": 4
      },
      {
        "source": "b",
        "target": "out",
        "value": 4
      }
    ],
    "balances": [
      {
        "id": "a",
        "inflow": 6,
        "outflow": 6
      },
      {
        "id": "b",
        "inflow": 4,
        "outflow": 4
      }
    ],
    "sourceTotal": 10,
    "sinkTotal": 10,
    "randomness": {
      "seed": 42,
      "source": "seed"
    }
  }
}

Limitations and assumptions

Zero-valued links are possible. Sequential splitting favors no uniform composition guarantee; the data does not specify a rendered Sankey layout or measured physical flow.
A replay requires the same complete input and implementation. Randomized construction does not guarantee uniform coverage of every feasible output; finite samples can repeat unless a distinct-selection rule is explicitly stated.
The field tables state structural bounds; cross-field constraints and bounded search or output budgets also apply. Unknown keys are rejected where the object contract disallows them. Input errors are distinct from null fields and deliberate invalid controls in a successful output.

Alternative or Complementary methods

For a supplied example, inspect the returned construction or delegated check directly. To evaluate a consumer, also test cases chosen for its own boundaries; a generated finite corpus does not establish exhaustive coverage.

References

Tool behavior and example: Random Sankey Flow Conservation Dataset Generator — tool.io

Similar or alternative tools

Random Heatmap Block Structure Dataset Generator
Construct labeled heatmap blocks with bounded integer noise and optional mirrored symmetry, retaining the planted block mask.
Random Histogram Bin Edge Challenge Generator
Generate observations exactly on or one supplied epsilon around explicit bin edges, retaining endpoint-policy membership and outside labels.