meadows/CONTEXT.md

meadows

The ubiquitous language for meadows — a web app for building systems-thinking models (stock-and-flow diagrams with feedback loops) in the spirit of Donella Meadows' Thinking in Systems. The diagram is the product now; numeric simulation is a planned later phase, so the language is chosen to be simulation-ready.

Part of meadows; see DESIGN.md for how these terms map to goals, functions, and components.

Language

System: The real-world thing being studied — an interconnected set of elements producing a behaviour over time. It is the referent, never the artifact in the app. Avoid: model, diagram, map (those are the artifact, not the real thing).

Model: One saved document — a simplified representation of a System, made of Stocks, Flows, Converters, and Information Links. The unit of save / export / reopen. Avoid: system, diagram, map, canvas, sheet, project.

Stock: An accumulation that holds a quantity over time — the system's memory (e.g. water in a bathtub, money in an account, a population). Avoid: Box, level, container, node.

Flow: A rate that moves quantity into (inflow) or out of (outflow) a Stock — the only element that can change a Stock's value; drawn as a pipe with a valve. Inflow/outflow is one Flow's direction relative to a given Stock, not a separate element type (a stock→stock Flow is an outflow for one and an inflow for the other). Avoid: faucet, drain, pipe, rate (that's the Flow's value), arrow.

Converter: A stateless helper value, recomputed each instant from its inputs (or a fixed constant), that feeds Flows or other Converters via Information Links — e.g. birth rate = fertility × 0.01. A constant is a Converter with no inputs. Avoid: variable (Stocks and Flows are variables too), function, auxiliary, parameter, node.

Information Link: A connector showing that one element's value influences a Flow's or Converter's value; carries no quantity, never changes a Stock. Avoid: arrow, dependency, edge, connector.

Source / Sink: The model boundary on an open Flow end — a Source is where a Flow originates outside the model (unlimited supply), a Sink is where it disappears. Drawn as a cloud, auto-rendered when a Flow has no Stock at one end. Avoid: cloud (that's the symbol, not the term), external, environment.

Polarity: The sign on an Information Link (and inherent to a Flow): + when more cause means more effect, − when more cause means less effect. The input that lets loops be classified. Avoid: sign, direction (direction is inflow/outflow), weight.

Feedback Loop: A closed cycle in the wiring (Stock → … → Flow → same Stock); detected from structure, never stored or hand-drawn. Classified by the product of polarities around the cycle. Avoid: cycle (internal term), circle, circuit.

Reinforcing: A Feedback Loop with an even number of − polarities — it amplifies change (the snowball); labelled R. Avoid: positive, self-reinforcing, vicious/virtuous.

Balancing: A Feedback Loop with an odd number of − polarities — it counteracts change and seeks a goal (the thermostat); labelled B. Avoid: negative, stabilizing, goal-seeking.

Relationships

• A Stock is the only stateful element — it accumulates (∫ flows) and has memory; it changes only through Flows.
• A Flow and a Converter are stateless — recomputed each instant from their inputs; neither has memory.
• An Information Link feeds a Stock, Flow, or Converter value into a Flow or Converter (never into a Stock — Stocks change only via Flows), and carries a Polarity.
• A Feedback Loop is a detected cycle in the wiring; it is Reinforcing when it has an even number of − polarities, Balancing when odd.

Example dialogue

Dev: "For a population model, Population is a Stock, and births is a Flow into it — an inflow. Where do the births come from?" Modeller: "From outside the model — so the Flow's other end is a Source cloud. Same with deaths: an outflow from Population to a Sink." Dev: "And births depend on how many people there are?" Modeller: "Right — an Information Link from Population to the births Flow, with + Polarity: more people, more births. That closes a cycle, so the app detects a Feedback Loop. Even number of − links — zero here — so it's Reinforcing." Dev: "And birth rate = fertility × 0.01?" Modeller: "That's a Converter — stateless, recomputed each step. The Population Stock is the only thing that remembers."

Flagged ambiguities

• "arrow" was used for two distinct things — resolved into Flow (moves material, changes a Stock) and Information Link (carries influence only).
• "function" was the user's word for the stateless helper — resolved to Converter (avoids collision with programming "function" and with the stateful Stock).
• "positive / negative feedback" — resolved to Reinforcing / Balancing (Meadows' preferred terms; +/− is reserved for link Polarity).