TUTORIAL

Getting Started with Dyad Studio

In this section, we will discuss the basics for using Dyad for modeling and simulation. This includes:

• How to use Dyad Studio

• How to create a Dyad model

• How to compile a model for simulation

• How to run basic simulations

• How to bring in standard libraries and compose models from components

Before starting this tutorial, install Dyad Studio.

First Step: Creating a Component Library

In Dyad, all new components must be created in a component library. Thus our first step will be to create a new component library which we can use as a playground.

In Dyad Studio, you can create a new library by opening the Command Palette (⇧ ⌘ P on MacOS, Ctrl-Shift-P on Windows). From the Command Palette, type Dyad and you should see the following options:

Select Dyad: Create Component Library from the list. You will then be prompted for the name of the library with a dialog like this one (although the appearance of the UI elements can differ from operating system to operating system).

Enter a library name that contains only letters, such as TutorialComponents. The name must be a valid Julia identifier and directory name. The optional Components suffix identifies the package as a Dyad component library.

Select a directory for the new package. The Create Component Library command creates a child directory with the library's name inside your selected directory.

When the library creation process is done, a new Dyad Studio window will open in the newly created directory.

NOTE

If you want to create a new Dyad component library with the Dyad CLI, you can simply run:

$ dyad create <LibraryName>

...from any directory and this command will create a new directory called with the library name you provided.

Setting Up Your Environment

The generated library includes a sample component and analysis. Open the library in Dyad Studio and wait for initialization to finish. Studio installs the library's Julia dependencies automatically with its default settings.

The first setup and analysis run can take several minutes while packages download and precompile. Subsequent runs are faster; see the FAQ for more about precompilation.

Running Our First Simulation: Lumped Thermal Model

Before getting to anything fancy, let's see how to use Dyad to define a lumped thermal model and simulate to see the solution. We use Newton's Law of cooling/heating which can be represented by the following simple linear ODE:

In the rest of this section, we will:

1. Look at a component representing this lumped thermal system.

2. Discuss an analysis for simulating the thermal response of the system.

3. Explore the analysis results via plots and other solution artifacts.

Newton's Law of Cooling/Heating

TIP

By whatever means you created the library, for the rest of this section we will assume you have opened the Dyad library in Dyad Studio.

As mentioned previously, the result of all of this will be a new Julia package pre-configured for use as a Dyad library. Included will be a Project.toml file that identifies the directory as a Julia package and lists its (initial) dependencies. You will also find a dyad directory that includes a file called hello.dyad. In there you will find two things. First, you'll find a Dyad component definition that should look something like this:

# A simple lumped thermal model
component Hello
  # Ambient temperature
  parameter T_inf::Temperature = 300
  # Initial temperature
  parameter T0::Temperature = 320
  # Convective heat transfer coefficient
  parameter h::CoefficientOfHeatTransfer = 0.7
  # Surface area
  parameter A::Area = 1.0
  # Mass of thermal capacitance
  parameter m::Mass = 0.1
  # Specific Heat
  parameter c_p::SpecificHeatCapacity = 1.2
  variable T::Temperature
relations
  # Specify initial conditions
  initial T = T0
  # Newton's law of cooling/heating
  m*c_p*der(T) = h*A*(T_inf-T)
end

In addition you should also find an analysis that looks something like this:

analysis World
  extends TransientAnalysis(stop=10)
  model = Hello(T_inf=T_inf, h=h)
  parameter T_inf::Temperature = 300
  parameter h::CoefficientOfHeatTransfer = 0.7
end

The Hello definition describes a first order system. The temperature response of the system is contained in the variable T. The various physical properties of the material are represented by the mass (m), the surface area (A), and the specific heat capacity (c_p). The environmental conditions are represented by the ambient temperature (T_inf) and the convective heat transfer coefficient (h). Finally, the initial temperature for T at the start of the simulation is prescribed using the parameter T0 (and the initial T = T0 relation).

Simulating the Thermal Model

Save hello.dyad. In the Analyses sidebar, click Run Analysis (the play button) beside World.

Illustration of the Analyses sidebar. YourComponents stands for the library you created earlier.

Dyad Studio compiles the model and runs the transient simulation of Hello with T_inf=300 and h=0.7. It displays the simulation plot and leaves the result in the Julia REPL as solution.

The plot shows T cooling from toward the ambient temperature of . Use solution in the Julia REPL for further plots and artifact queries. To plot the response again with Plots.jl, enter:

using Plots
plot(solution)

Interactively Modifying Analyses

The World analysis exposes the ambient temperature and heat transfer coefficient as parameters and passes them to Hello. To simulate heating, change their values in hello.dyad:

analysis World
  extends TransientAnalysis(stop=10)
  model = Hello(T_inf=T_inf, h=h)
  parameter T_inf::Temperature = 400
  parameter h::CoefficientOfHeatTransfer = 0.2
end

Save the file and click Run Analysis beside World again. The new result replaces solution in the Julia REPL. Plot it with the same command:

plot(solution)

The body now heats toward the ambient temperature of , starting from . The smaller heat transfer coefficient makes the response slower than in the cooling case.

Obtaining Artifacts from an Analysis

An analysis exposes plots, tables, and other results as artifacts. List the artifacts available from the latest run:

using DyadInterface
artifacts(solution)

6-element Vector{Symbol}:
 :SimulationSolutionPlot
 :SimulationSolutionTable
 :ObservablesTable
 :RawSolution
 :SimplifiedSystem
 :InitialSystem

The transient result includes a plot and a solution table. Retrieve the table with:

table = artifacts(solution, :SimulationSolutionTable)

30×2 DataFrame

Row	timestamp	T(t)
	Float64	Float64
1	0.0	320.0
2	0.0270361	323.525
3	0.0800624	329.993
4	0.145411	337.218
5	0.22629	345.135
6	0.320872	353.136
7	0.430032	360.932
8	0.552807	368.161
9	0.689319	374.64
10	0.839177	380.245
11	1.00251	384.953
12	1.17944	388.796
13	1.37044	391.85
14	1.57615	394.216
15	1.79754	396.001
16	2.0359	397.312
17	2.29288	398.248
18	2.57057	398.897
19	2.87162	399.332
20	3.19933	399.613
21	3.55786	399.787
22	3.95252	399.89
23	4.39011	399.947
24	4.87949	399.976
25	5.4325	399.991
26	6.06518	399.997
27	6.80004	399.999
28	7.66961	400.0
29	8.72283	400.0
30	10.0	400.0

As described in the TransientAnalysis documentation, this returns a data table of the solution values that can be used to serialize the information.

Each analysis provides its own artifacts. A controls analysis can provide Bode plots, while a surrogate analysis can provide a trained neural network. The analysis documentation describes its available results.

Using Model Libraries and Composing Components: Generating an RLC Circuit

Build an RLC circuit from components in the ElectricalComponents standard library. These components use acausal equations: they relate physical quantities without specifying which variable to calculate from the others. For example, a resistor supplies v = R * i; the surrounding circuit determines its voltage and current together. Dyad determines how to solve the connected equations. Add the library from the Julia REPL:

using Pkg
Pkg.add("ElectricalComponents")

This is just one of many standard libraries included in Dyad, peruse the documentation pages on the component libraries to see all of the prebuilt models for fluids, hydraulics, mechanical systems, and much more!

Create dyad/rlc.dyad in your library. Start with a partial component that defines the shared two-pin interface and current balance. Its metadata places the built-in positive and negative pin icons on opposite edges:

partial component TwoPin
  p = Pin() {^p}
  n = Pin() {^n}
  variable v::Voltage
  variable i::Current
relations
  v = p.v - n.v
  i = p.i
  p.i + n.i = 0
metadata {
  "_links": {
    "p": {
      "Dyad": {
        "placement": {"icon": {"iconName": "pos", "x1": -50, "y1": 450, "x2": 50, "y2": 550}}
      }
    },
    "n": {
      "Dyad": {
        "placement": {"icon": {"iconName": "neg", "x1": 950, "y1": 450, "x2": 1050, "y2": 550}}
      }
    }
  }
}
end

The partial component leaves the voltage–current relationship open. Derive StepVoltage from it and add the source's voltage law:

Assemble the local voltage source with ElectricalComponents' resistor, inductor, capacitor, and ground:

Each component supplies its own equations. The connect relations add equations that equate voltages and balance currents at the connected pins. Add this analysis to dyad/rlc.dyad to simulate the circuit for 10 seconds:

analysis SimRLC
  extends TransientAnalysis(stop=10, abstol=1m, reltol=1m)
  model = RLC()
end

Save rlc.dyad and click Run Analysis beside SimRLC in the Analyses sidebar. The circuit's simulation result is now solution in the Julia REPL. Plot it there:

using DyadInterface, Plots
plot(solution)

Use the idxs keyword to select the capacitor voltage and resistor current for the plot. Retrieve their symbolic names from the SimplifiedSystem artifact:

sys = artifacts(solution, :SimplifiedSystem)
plot(solution; idxs = [sys.capacitor.v, sys.resistor.i])

Next Steps and Where to Learn More

Congrats! You now know how to build some basic components in Dyad, run simulations, and stitch together pre-built components for more complex models. But there are lots of other features to explore and much more to learn. Some recommended next steps are:

• See how to construct more complex models using the standard libraries. This is recommended if you want to get up and running with complex simulations quickly.

• Learn more about how acausal modeling works by building the RLC circuit from scratch. This is for if you care about the details: how was everything defined? How does it know equations to simulate? Etc.

• Want more details on the Dyad language? Check out the Dyad Language Guide

• Learn how to do more with your models by seeing analysis-specific tutorials, such as learning how to perform a design optmization or build an inversion-based control

• Explore other standard libraries, like the HydraulicComponents and ThermalComponents

If you have questions or just want to chat with Dyad devs, feel free to reach out on the #dyad Slack channel on the JuliaLang Slack. (If you're not already on JuliaLang Slack, this page can help you join.) If you find bugs or want to suggest features, you can also create issues on the DyadIssues Github repo.