The component library: reusable parts for your model

Most models are built out of parts that other models have already needed: a thermal mass, a conductor between two bodies, a battery, a controller. Writing each one from scratch means choosing states, writing an equation and checking that the units agree, which is real work for a part whose behavior is well known. The component library is a panel of ready-made parts that you place into a model instead. This page builds a small model from it, then shows how to save your own parts so the next model starts further along.

Opening the library

The Component library button in the toolbar opens a panel down the left side of the canvas and keeps it there while you work. It is a panel rather than a dialog because building a model usually means pulling in several parts in a row.

There are five kinds of part, and the chips at the top filter by them:

• Nodes are a body with its states already defined, such as a Thermal mass with a temperature state, a Battery or a Motor.
• Edges are a relationship with its equation already written, such as Conduction or Resistive heating.
• Bundles are several edges placed among several nodes in one step, because some physics cannot be one edge. The Battery-powered motor drive creates three.
• Assemblies are a piece of model placed whole, with its nodes and relationships. The two PID controller parts are assemblies.
• My library holds the parts you have saved yourself.

A second row of chips filters by domain, and the search box filters by name. As soon as either is used, the grouped list becomes a flat list of matches.

Each part carries a description, and it is copied onto the node or relationship you place, so what the part is and how to use it travels with it. Open a placed Thermal mass and its Description field already says what its state means and which edges are meant to feed it.

Building with it

The example is two bodies that exchange heat: one starts at 353.15 K (80 °C) and the other at 293.15 K (20 °C). Click Thermal mass in the library and a node is placed on the canvas with its editor open. Rename it Hot body and set its Temperature to 353.15. Click Thermal mass again, rename the second one Cold body and leave its 293.15.

A placed node appears at a fixed position with a small offset from the last one, so drag one of them clear of the other. Then select both nodes and click Thermal link, a bundle, in the library.

A bundle takes whatever the selection is and decides by itself which node plays which role. A node fits a role when it has the states that role's edges name, so you do not have to remember an order. The first node you select is the First body when two nodes fit equally well. If the selection cannot be assigned, nothing is created and the library says which role has no match.

The Thermal link creates two edges, Heat into second body and Heat into first body. Each divides the heat flow by the thermal capacitance of the body it warms, so a small body changes temperature faster than a large one and energy is conserved exactly. Both share one Conductance (50 W/K) as a single shared parameter, so changing it once changes both directions. Each edge also has its own Thermal capacitance (1000 J/K by default), which you set to the capacitance of the body it warms. The description in the library says all of this too.

An edge placed from the library works the same way when you connect two nodes yourself. Its ports are looked up on the nodes by state name, so a thermal edge finds a state called temperature on each end and binds to it without asking. There is deliberately no picker for a near match, because a plausible but wrong choice, such as a voltage state bound to a temperature difference, is exactly the mistake the library exists to prevent. An edge with no match is left unbound, and the model validator flags it like any other incomplete relationship.

Running it

Run the model for 100 seconds.

The two bodies meet at 323.15 K, which is the midpoint of 353.15 and 293.15, because they have the same capacitance. That is the check that the bundle did its job: with equal capacitances and no heat lost anywhere, the energy that one body gives up is exactly what the other gains.

Saving your own parts

When you have built something worth keeping, select the nodes and press Save to my library on the selection toolbar, or right-click the selection and choose it from the menu. A dialog asks for a name, an optional description and an optional section.

The selected nodes and the relationships between them are kept as an assembly, with their programs, descriptions and the shared parameters they link to. It then appears under My library, filed in its section, and is placed in any model the same way as a bundled one.

Each part and each section has a pencil button that renames or re-files it, and a part has a cross that deletes it after asking. A selection is refused, with a sentence that says what to change, if it holds something that could not travel to another machine: a program that points at an installed FMU or plugin instead of containing its source, or a node that reads the state of a node outside the selection. Bundled parts and the ones that add-ons contribute cannot be changed or deleted from here.

The desktop app keeps each saved part as its own file in the user data folder, in the same format as the bundled ones, so a file can be copied to another machine and dropped in. The web edition keeps them in the browser's own storage. Parts saved in one edition are not carried to the other.

Where to go from here

"Sharing one parameter across relationships" covers the shared parameter that a bundle such as the Thermal link creates for you. "The graph canvas" covers selecting, moving and connecting nodes by hand.