Getting started with Konjugate

Konjugate models a system as a graph: components hold their own state, and relationships describe how one component's state pulls on another's. This walkthrough starts from a blank canvas and builds the smallest possible example of that idea: a hot plate warming the air in a room, run through to a result. It should take about five minutes, and by the end you'll have touched every core piece of the workbench: nodes, states, relationships, equations and results.

Add the first node

Right-click anywhere on the empty canvas to open the add palette.

Choose Node. This opens the node builder, where you name the component and define what state it carries. Call it "Hot plate," and give it one state variable: name it "Temperature," symbol temperature, initial value 90.

Click Create node, and the hot plate appears on the canvas as a small cuboid with a label.

A quick note on symbols: they must start with a lowercase letter (temperature, not Temperature). The builder doesn't show an error if you get this wrong. It just quietly won't create the node, so if clicking "Create node" seems to do nothing, check the symbol field first.

A node placed on an otherwise-empty canvas always lands in the same default spot, so drag this one off to the side before adding the next one. Click and hold on the cuboid itself (not its floating label) and drag.

Add the second node

Right-click an empty area of the canvas again, choose Node, and create "Room air" the same way: one state named "Temperature," symbol temperature, initial value 20.

With both nodes placed, the canvas now shows two independent components. Nothing connects them yet, so running the model right now would just keep both temperatures exactly where they started.

Connect them with a relationship

Right-click an empty spot on the canvas once more, but this time choose Edge from the palette. This opens the relationship builder: set From node to "Hot plate" and To node to "Room air," and name it "Heat transfer."

The builder pre-fills a "Coefficient" parameter you won't need for this example, so remove it with the row's × button. Under Updates, choose target.temperature: this tells Konjugate which state's derivative this relationship contributes to. Then, in the equation field, build the expression 0.05 · (source.temperature − target.temperature) by typing 0.05, a multiplication and an opening parenthesis, clicking the source.temperature chip under "Available references" to insert a reference to the hot plate's temperature, typing a minus sign, clicking the target.temperature chip, and closing the parenthesis.

Every reference you click there, whether a state on either endpoint or a parameter, gets inserted as a ready-to-use symbol, so you never have to remember or type one by hand.

Click Create edge. The canvas now draws a line between the two nodes with a label showing the relationship.

This mirrors how every Konjugate model is built, no matter how large: local state on nodes, and small equations on relationships that describe how one component's state pulls on another's, never one large system-wide equation to maintain by hand.

Run it

Click Run in the top toolbar. In the dialog, set the simulation time to 20 seconds and leave offline mode as-is (offline runs at maximum speed; online paces itself to wall-clock time, which is useful for live interaction but unnecessary here).

Click Start. For a model this small, the run finishes essentially instantly.

The hot plate's temperature never moves: nothing feeds its derivative, so it stays exactly where it started. The room's temperature climbs from 20 toward 90, but never reaches it: the rate itself shrinks as the two temperatures converge, exactly what the differential equation dTemperature/dt = 0.05 × (90 − Temperature) describes. Solved out, that's Temperature(t) = 90 − 70 × e^(−0.05t), which works out to 64.2549 at t = 20, matching the run above.

That the hot plate holds steady is a deliberate simplification, not an oversight: it has no equation of its own, standing in for a thermostatically-controlled heater that maintains its setpoint regardless of how much heat the room draws from it. A model of two finite bodies genuinely exchanging heat would need an equation on the hot plate's temperature too, and the two would converge toward a shared equilibrium instead of the room simply chasing the plate's fixed value.

Inspect the result

Click on the "Room air" node, then open its Results tab to see the full curve rather than just the endpoint.

That curve is worth pausing on: it's not a coincidence or a rendering default, it's the direct, visible consequence of the one equation you wrote. Because the equation depends on the gap between the two temperatures, the rate of change is largest early on, when the gap is biggest, and shrinks as the room warms, so the curve decelerates rather than running in a straight line. That link between an equation on a relationship and a curve in a result is the whole idea behind Konjugate.

Where to go from here

This model used exactly one relationship and no source terms, geometry or add-ons. From here, worth exploring next:

• Subsystems and edge groups for organizing a model that outgrows a handful of nodes.
• The model assistant, which proposes the same kind of nodes, states and equations you just built by hand, from a plain-language description.
• Recovering structure from data, which goes the other direction entirely: instead of writing the equation yourself, Konjugate proposes one from a CSV of time-series data.