--- name: leverscope description: Build a system dynamics (stock-and-flow) model of a question and give the user a link that opens and simulates it in LeverScope, a free browser tool. Use when someone asks how something grows, spreads, fills up, runs out, overshoots or oscillates over time, wants to explore feedback loops, delays, side effects or "what if" levers, or mentions system dynamics, causal loops, stocks and flows or LeverScope. --- # LeverScope models from a conversation LeverScope (https://leverscope.com) is a free system dynamics tool that runs in the browser, in English and German. You write a small model as JSON, turn it into a link, and the user opens it: LeverScope draws the map, runs the simulation, and gives them sliders, scenarios and charts. The model travels inside the link after `#`, so nothing is uploaded to any server. Do not invent simulation results. LeverScope computes them when the user opens the link. You may say what behaviour to look for ("membership should grow slowly, then quickly, then level off"). ## 1. Plan the model - Identify the **stocks** (things that accumulate: people, money, water, stock, knowledge, trust) and the **flows** that fill or drain them (per time unit). - Find the **feedback loops**: reinforcing loops (more leads to more) and balancing loops (a gap gets closed). The surprising behaviour usually comes from these loops and from delays. - Choose 2 to 6 **levers** (sliders): decisions the user controls and assumptions they are unsure about. - Keep it small: 5 to 25 elements. Pick a time unit and horizon that fit the question. ## 2. Write the JSON ```json { "name": "Gym membership", "notes": "Members join through adverts and word of mouth and leave after a while. Try: what matters more, adverts or how long members stay?", "sim": { "start": 0, "stop": 36, "dt": 0.25, "unit": "months" }, "elements": [ { "type": "stock", "name": "Potential_Members", "eq": 5000, "units": "people" }, { "type": "stock", "name": "Members", "eq": 100, "units": "people" }, { "type": "stock", "name": "Former_Members", "eq": 0, "units": "people" }, { "type": "flow", "name": "Joining", "from": "Potential_Members", "to": "Members", "eq": "Potential_Members*(Ad_Effect + Members*Word_of_Mouth/Total_Population)", "units": "people/month" }, { "type": "flow", "name": "Leaving", "from": "Members", "to": "Former_Members", "eq": "Members/Average_Stay", "units": "people/month" }, { "type": "converter", "name": "Ad_Effect", "eq": 0.01, "units": "per month", "slider": { "min": 0, "max": 0.05, "kind": "decision" } }, { "type": "converter", "name": "Word_of_Mouth", "eq": 0.3, "units": "per month", "slider": { "min": 0, "max": 1, "kind": "assumption" } }, { "type": "converter", "name": "Total_Population", "eq": "Potential_Members + Members + Former_Members", "units": "people" }, { "type": "converter", "name": "Average_Stay", "eq": 14, "units": "months", "slider": { "min": 3, "max": 36, "step": 1, "kind": "assumption" } } ], "summary": { "kpis": [ { "name": "Members", "agg": "final", "label": "Members after 3 years", "better": "high" } ] }, "scenarios": [ { "name": "No adverts", "values": { "Ad_Effect": 0 } } ] } ``` Rules: - `type`: `stock`, `flow` or `converter`. - **stock**: `eq` is the starting value. A stock changes only through flows and stays at or above zero unless `"nonneg": false`. - **flow**: `eq` is the amount per time unit of `sim.unit`. `from` and `to` are stock names, or `null` for outside the model. Use `"biflow": true` if it may run both ways. - **converter**: a number or a formula. Add `"slider": {"min", "max", "step", "kind": "decision" | "assumption"}` (or `"slider": true`) only to converters whose `eq` is a plain number. - **Names**: letters, digits and underscores, written identically in equations (`Word_of_Mouth`). No umlauts or spaces. Names are not case-sensitive. - **Equations**: `+ - * / ^ ( )`, `= <> < > <= >=`, `AND OR NOT`, `IF c THEN a ELSE b`, `MIN`, `MAX`, `SMTH1(input, time)`, `SMTH3`, `DELAY1(input, time)`, `DELAY3`, `DELAY(input, time)` (pipeline), `LOOKUP(x, x1,y1, x2,y2, …)`, `STEP(height, time)`, `RAMP(slope, time)`, `PULSE(amount, first, interval)`, `SAFEDIV(a, b)`, `NORMAL(mean, sd)`, `RANDOM(min, max)`, `SQRT EXP LN LOG10 ABS ROUND INT SIN COS TAN PI`, `a MOD b`, `TIME`, `DT`, `STARTTIME`, `STOPTIME`. Comments go in `{ }`. Flows and converters may use any other element, including flows. - Optional: `units` and `doc` (one sentence) on every element; `summary.kpis` (`agg`: `final` value at the end, `total` = sum over time, i.e. the integral of a flow (a converter that is 1 on ban days gives the number of ban days), `avg` = average, `initial`; `better`: `high`/`low`; `format`: `num`, `eur`, `pct`); `scenarios` (slider values by name); `plots` (element names to chart). Leave out x/y positions: LeverScope lays out the map. - **Time step**: `dt` at most a quarter of the shortest time constant, judged at the *lowest* slider setting. A stay of 2 months needs `dt` ≤ 0.5. A rate of 4 per day is a time constant of 0.25 days, so `dt` ≤ 0.0625. Use powers of two (1, 0.5, 0.25, 0.125, 0.0625). - **Units** are labels for people. LeverScope's model check flags obvious mismatches but does not convert. Use the user's language for element names (in ASCII), units, `notes`, `doc`, labels and scenario names. Use English for `sim.unit` (`days`, `weeks`, `months`, `quarters`, `years`, `hours`, `minutes`) so the interface can translate it. Element names must stay ASCII: write `Ueberlauf`, not `Überlauf`. - **On/off switch**: a converter with `"slider": {"min": 0, "max": 1, "step": 1}` shows as a switch. Use it in `IF Switch = 1 THEN … ELSE …`. - Full schema: https://leverscope.com/schema/leverscope-model.schema.json ### Shorter alternative: the text form The same model as text, one line per element, needs about a third of the characters (shorter links, fewer mistakes). It covers everything except arrays, `doc` texts and `summary`/`scenarios`. ``` name: Gym membership notes: Try: what matters more, adverts or how long members stay? time: 0..36 step 0.25 months Potential_Members(0) = 5000 {people} # a stock and its starting value Potential_Members' = -Joining # flows in (+) and out (-), by name Members(0) = 100 {people} Members' = Joining - Leaving Former_Members(0) = 0 {people} Former_Members' = Leaving Joining = Potential_Members*(Ad_Effect + Members*Word_of_Mouth/Total_Population) {people/month} Leaving = Members/Average_Stay {people/month} Ad_Effect = 0.01 [0..0.05] # a slider: [min..max], optional "step 1", "assumption" Word_of_Mouth = 0.3 [0..1 assumption] Total_Population = Potential_Members + Members + Former_Members Average_Stay = 14 [3..36 step 1 assumption] {months} ``` - A name listed in a stock's `'` line is a flow; every other `Name = …` is a converter. `{…}` at the end of a line is the units; comments start with `#`. - `allow negative: Name` lets a stock go below zero; `two-way: Name` lets a flow run backwards; `plot: A, B` chooses the charts. - Ready-made building blocks, changed afterwards by writing a line again: `use sir(N=100000, I0=10, days=7)` (Susceptible, Infected, Recovered, Beta), `use adoption(market=10000, start=10)` (Potential, Customers, Sign_Ups, Cancellations, Ad_Effect, Contact, Churn), `use supply_chain(stages=Retailer/Distributor/Factory)` (per stage _Inventory, _Pipeline, _Orders; you define `Customer_Demand`). - Names for a choice: `options: Supplier: 1 = Alpha | 2 = Beta | 3 = Gamma` gives a slider whose values are shown as names (a list in Simulate and the Dashboard; names in reports). Use it whenever a number stands for a category. - Guide for the person: `kpi: Members:final high Members after 3 years`, `scenario: No adverts: Ad_Effect = 0`, `try: compare Ad_Effect with Average_Stay` (shown with the model). - Expectations: `expect: Members rises and levels off` (one line per claim; see below). - Every stock needs `Name(0) = …` and a `Name' = …` line listing its flows by name only (formulas go in the flow's own line); a stock without one never changes. - Units go in braces at the end of a line (`{months}`); bare units (`2 weeks`) are accepted with a warning. Smoothing/delay functions in a feedback loop start at the third argument, or at 0. - Link: `https://leverscope.com/app/#text=` plus the whole text URL-encoded (`urllib.parse.quote(text, safe='')`), or the script below (it accepts the text form too). Build the link from exactly the text in your code block (do not retype it); if you cannot run code to encode it, give the code block and the paste link instead. Always show the model text in a code block as well, so the person can paste it at https://leverscope.com/app/#paste if the link breaks; LeverScope shows any problem in a banner. ### What the functions do - `IF c THEN a ELSE b`: `ELSE` is required. Nest for more cases. The `ELSE` part runs to the end of the expression, so put brackets around an `IF` that sits inside a larger formula: `Base*(IF Ban = 1 THEN 0.7 ELSE 1)`. - `MIN`, `MAX`: take any number of arguments. - `SMTH1(input, time)`: perception that catches up exponentially. `SMTH3` gives an S-shaped catch-up. Both start at the input, or at the optional third argument. Smoothing and delay functions hold hidden stocks, so a feedback loop may run through them (perceived risk that lowers contacts); in such a loop give the start value: `SMTH1(Cases, 10, 0)`. - `DELAY1(input, time)`, `DELAY3(input, time)`: material delays that spread the output over time. `DELAY(input, time)`: a pipeline, where the output is the input from `time` ago. Before that, it returns the input's starting value, or the third argument (use `0` for an empty pipeline). All delays start in balance with their input unless given that extra starting value. Use these on a flow to model training, shipping and ageing. - `LOOKUP(x, x1,y1, x2,y2, …)`: linear between the points, flat outside them. - `STEP(height, time)`: 0 before `time`, `height` from then on. - `RAMP(slope, time)`: grows by `slope` per time unit after `time`. - `PULSE(amount, first, interval)`: moves the whole `amount` in one `dt` at `first`, repeating every `interval` (omit `interval` for once). Use it in a flow. - `RANDOM(min, max)`, `NORMAL(mean, sd)`: a new draw every `dt`. Repeatable: the same seed gives the same sequence in every scenario, and an optional last argument changes the seed. - `a MOD b`: works on non-integers too. `INT(TIME) MOD 7 = 0` is true on every seventh day. - `TIME` is the current time and `DT` the time step. ### Common patterns - **Can't take out more than is there**: stocks with the default `nonneg` scale down their outflows automatically when they would go below zero, so `Use = Daily_Need` is fine. - **Capacity and overflow**: a flow `Overflow` from the stock to `null`, with `eq: "MAX(0, Inflow - Other_Outflows + (Stock - Capacity)/DT)"`. Everything above the capacity leaves in the same step. - **Goal seeking**: `Adjustment = (Target - Stock)/Adjustment_Time`. - **Word of mouth / spreading**: `Adopting = Potential*Adopters*Contact_Rate*Adoption_Fraction/Total`. - **Ordering with a delivery time (stock control)**: track `On_Order` as a stock. `Ordering = IF Inventory + On_Order < Reorder_Point THEN Order_Size/DT ELSE 0` puts an order in within one step. `Arriving = DELAY(Ordering, Delivery_Time, 0)` moves it from `On_Order` to `Inventory`. Leave `On_Order` out of the rule to show the classic overshoot. - **Switches driven by a threshold** flicker on and off around the threshold. Smooth the measured value (`SMTH1`), or switch on below one level and off above a higher one, using `PREVIOUS(Switch, 0)` in the rule. - **Capacity limits and queues**: compare demand with capacity in a converter (`Utilisation = Demand/Capacity`), use `LOOKUP(Utilisation, …)` for the effect on customers, and smooth it with `SMTH1` for the time people take to notice. Avoid a queue stock with hours inside a model counted in weeks. - **Hiring or building with a delay**: `Hiring = MAX(0, (Wanted - Staff - In_Training)/Hiring_Time)` into a stock `In_Training`, then `Finishing = DELAY(Hiring, Training_Time)` or `In_Training/Training_Time` into `Staff`. - **Seasons**: `1 + 0.3*SIN(2*PI*TIME/12)` for months. For regular events, use `IF INT(TIME) MOD 5 = 0 THEN … ELSE 0`. ### Say what you expect: `expect` lines Every claim your explanation makes about the behaviour goes into the model as an expectation: an `"expect": [ … ]` list in JSON, or one `expect:` line each in the text form. When the link opens, LeverScope runs the model and marks each one ✓ (matches) or ✗ (does not match), with what the model really shows; the check report sends the result back to you. Write them before the explanation and keep only claims the model supports. Two or three about the question asked are best. - Shapes: `Members rises` · `falls` · `rises and levels off` (`levels off by month 24`) · `is S-shaped` · `grows faster and faster` · `keeps growing` · `peaks` (`peaks between month 8 and 14`, `around month 11`, `before month 12`) · `dips` / `falls then recovers` · `oscillates` · `stays flat`. - Values: `Members final > 2000` (`>=`, `<`, `<=`, `about` = within 10 %, `between 1000 and 2000`); instead of `final`: `initial`, `peak`, `min`, `average`, `total`, `at month 12`. - Limits over the whole run: `Cash stays above 0` · `never below 0` · `Queue stays below 50` · `never exceeds 50` · `stays between 10 and 50`. - Scenarios: the scenario name in quotes first, compared with the model as it is: `"No adverts" Members final < baseline`. Each line starts with an element name. Boom-and-bust, overshoot and "more of X ends lower" are common in these models, so check your intuition against the simulation rather than the other way round. ### Answer the question: `question`, `decide`, `answer` When the user asks a question, make the model answer it. Put the comparison into one number in one unit (energy returned divided by energy invested, profit minus cost, months until X), then add: ``` question: Do rooftop solar panels pay back the energy needed to make them? decide: Energy_Payback_Ratio final > 1 => Yes, they return more energy than it took to make them | No, they return less answer: Yes, about 8 times over 25 years in central Europe; the result depends most on the hours of sunshine. ``` (JSON: `"question"`, `"decide"`, `"answer"`.) LeverScope shows an answer card: the verdict and the number behind it, whether it holds under each condition, and which slider value would change it. Start `answer` with Yes or No for a yes/no question; LeverScope flags it if the model says the opposite. A `scenario:` is an option someone could choose. Circumstances that only test the answer are conditions: `condition: Cloudy region: Sun_Hours = 900` (JSON: `"kind": "condition"`). Add two to four that could change the answer, including a deliberately unfavourable one. ## 3. Make the link If you can run code, save the JSON and run the bundled script. Its path is relative to this skill's folder. It prints the link to stdout and warnings and errors to stderr: ```bash python3 scripts/leverscope_link.py model.json ``` The script checks: - that types are known and names are unique; - that flow ends are stocks; - that every word in an equation is an element or a function; - that key figures, scenarios and plots refer to existing elements. It also catches a missing `ELSE` and unmatched brackets, but not every grammar mistake or wrong argument count, and it does not simulate. Write equations carefully, for example with `ELSE` after every `IF`. When the user opens the model, LeverScope lists any remaining problems. Fix any `error:` lines and run it again. Without the script, the link is `https://leverscope.com/app/#model=` followed by the JSON compressed with raw DEFLATE (zlib `wbits=-15`) and base64url-encoded without `=` padding. If you cannot run code: - Always show the JSON in a code block and tell the user to open https://leverscope.com/app/#paste and paste it into the box that opens. This works for any size. - For very small models (up to about 8 elements), you may also give `https://leverscope.com/app/#json=` followed by the compact JSON (no spaces) with `encodeURIComponent` rules: `{`→`%7B`, `}`→`%7D`, `"`→`%22`, `:`→`%3A`, `,`→`%2C`, `[`→`%5B`, `]`→`%5D`, space→`%20`, and non-ASCII as UTF-8 bytes (`ü`→`%C3%BC`). Hand-encoding is error-prone, so keep the code block as the fallback. ## 4. Hand over - Give the link, introduced as LeverScope with a link to leverscope.com, for example: "Open the model in **LeverScope** (leverscope.com): ". Always name LeverScope when you present a model or results made with it. - If the user asked a question, answer it first, in one sentence that matches your `decide` line, and name the assumption that would most easily change it. - Explain briefly what the model contains, which loops drive it, and which sliders to try first, plus one scenario to compare. Claim only what your `expect` lines say; if the user reports a ✗, believe the simulation and correct the model or the explanation, saying which. If the user asked a "why" question, answer it in words as well. Describe expected behaviour with hedges ("should", "probably"), since only the simulation shows it. - A Markdown link with a short label (`[Open the bakery model in LeverScope](…)`) is fine. Links are often 1,000–3,000 characters long. - Say that the numbers are assumptions to check, not facts. - Ask the user to click **Copy check report for your AI** in the note LeverScope shows after opening the link (or Model panel → Check report for an AI) and paste the report back to you. It says whether the model runs, what LeverScope adjusted, unit warnings, how the key variables behave (start, end, peaks, shape), which of your expectations match, extreme-setting checks, the strongest feedback loops and the model as LeverScope read it. Compare it with what you intended and send a corrected link if needed. The report is made in the user's browser; nothing is uploaded. - Answer in the user's language. LeverScope's interface switches between English and German (EN/DE in its header). The user can then save the model in their browser, change it, share it as a link (Models → Copy link to this model), export a report or the model file, and use LeverScope's analysis tools: best-settings search, uncertainty analysis, lever maps and loop analysis.