MANUAL

Parameters, Variables, and Equations

A component declares typed parameters and variables, then relates them through equations. This page follows that order: choose types, configure parameters, declare unknowns, and describe their behavior.

Types, units, and attributes

A declaration puts the type after ::: variable position::Real declares a real-valued unknown. Use Real for continuous physical quantities, Integer for integer values, Boolean for true or false, and String for text.

A named type attaches units and other attributes to a base type. A library can define types for quantities it uses repeatedly:

type Length = Real(units="m")
type Speed = Real(units="m/s")

A component can then declare variable position::Length or variable velocity::Speed. Attributes can also appear directly on a declaration:

variable position::Real(units="m", min=0, max=10, guess=1)

Attribute	Purpose
units	Records the physical unit.
min, max	Record bounds for downstream tools.
guess	Supplies a starting point for initialization.

Bounds describe the quantity. They do not add clipping equations or a physical stop to the model. Express that behavior through equations or an appropriate library component.

Use consistent units throughout a physical model. Unit attributes are carried into generated ModelingToolkit models when units are enabled; analysis and unit-checking behavior also depends on the compilation and analysis configuration.

Parameters and variables

Parameters and defaults

A parameter holds a model setting that stays fixed during a simulation. A declaration can supply a default:

parameter tau::Real = 2

An instance modification chooses a different value. For example, CoolingBody(tau=10) sets the time constant of the component from the Language Guide to 10. Each instance has its own parameter values. A final parameter fixes a setting against modification by an enclosing model.

Use apply to load a set of instance parameters from a TOML or JSON file.

Variables

A variable declares an unknown that the equations determine:

variable x::Real

A differential equation describes how a state changes over time; an algebraic equation relates quantities at each time. The following examples use both.

Write equations in a relations block

The relations keyword introduces the equations and connections of a component. In this complete component, an initial equation fixes the starting state and a differential equation describes exponential decay:

component Decay
  parameter tau::Real = 2
  variable x::Real
relations
  initial x = 1
  der(x) = -x / tau
end

der(x) is the derivative of x with respect to simulation time. For positive tau, the state decays toward zero. initial x = 1 supplies the starting condition.

An equation constrains both sides to have equal values. Its position in the relations block does not define an execution order. You can express a force law as force = mass * der(velocity) and let the solver determine the unknowns together with the rest of the model.

Algebraic equations describe quantities without their own differential state:

component DecayWithEnergy
  parameter tau::Real = 2
  variable x::Real
  variable energy::Real
relations
  initial x = 1
  der(x) = -x / tau
  energy = x^2 / 2
end

Here energy follows from x through the algebraic equation.

Initial conditions and guesses

Initial equations constrain the starting state. Supply independent physical conditions and let the remaining values follow from the equations: adding an initial equation for every algebraic quantity can overconstrain initialization. A guess gives the initialization solver a starting point for its numerical search.

This excerpt gives the pressure solver an initial guess and fixes the initial temperature:

variable pressure::Real(guess=100000)
variable temperature::Real
relations
  initial temperature = 300

guess=100000 does not require the solved pressure to equal 100000. initial temperature = 300 does require the initial temperature to equal 300. Choose guesses near a physically meaningful solution when nonlinear equations admit several roots or are difficult to initialize.

Clocked states use initial values at past ticks. Their initialization is explained in Discrete-Time Modeling.

Expressions and time

Expressions appear in defaults, equations, function arguments, and structural choices. Common forms include arithmetic (+, -, *, /, ^), comparisons (<, >=, ==, !=), and boolean combinations (and, or, !). The Syntax Reference lists supported operators and forms.

time gives the current continuous simulation time. This complete component produces a piecewise constant signal:

component StepValue
  parameter start::Real = 1
  variable y::Real
relations
  y = time < start ? 0 : 1
end

The ternary expression condition ? a : b selects a value. Both branches should describe compatible quantities. A discontinuous expression alone does not specify a sampled controller; use clocks to express behavior that executes at discrete ticks.

Literals include integers (10), reals (3.14), scientific notation (1.5e-3), booleans (true, false), and quoted strings ("steel"). Numeric engineering suffixes include 10k for 10000; these scale a number and do not assign units.

Arrays and repeated equations

Array dimensions follow the type, and indices start at one. A structural parameter can set a dimension because its value is known during model construction. Changing it requires constructing and symbolically processing the model again; the equations or unknowns may change.

component DecayArray
  structural parameter N::Integer = 3
  parameter tau::Real = 2
  variable x::Real[N]
relations
  for i in 1:N
    initial x[i] = 1
    der(x[i]) = -x[i] / tau
  end
end

During model construction, the loop creates a differential equation and an initial condition for each element of x.

Array literal declarations use commas. Matrix literals contain a list of rows:

parameter weights::Real[3] = [1, 2, 3]
parameter A::Real[2, 2] = [[1, 2], [3, 4]]

Use A[1, 2] to access the first row's second element. A comprehension such as [Cell() for i in 1:N] constructs an array of components; see Arrays of components.

Structural choices

A relation if chooses equations using a condition known during model construction:

component ConfigurableDecay
  structural parameter active::Boolean = true
  parameter tau::Real = 2
  variable x::Real
relations
  initial x = 1
  if active
    der(x) = -x / tau
  else
    der(x) = 0
  end
end

The selected branch becomes part of the constructed system. Use a value expression such as condition ? a : b when a quantity changes according to a condition during the simulation.

Enum-valued structural parameters provide named alternatives for initialization policies and model variants. switch selects the corresponding relations. See the Syntax Reference for enum constructors, payloads, and cases.

Libraries and Julia functions

Import library definitions or Julia functions when a model needs behavior supplied by another package. A component library's Project.toml declares its dependencies. Dyad source can refer to a dependency's definitions by qualified name or import names with using. This example assumes Mechanical is a dependency:

using Mechanical: Flange, Spring

A Julia function imported from another package needs a named function type. If MyLibrary provides myfunc(x, y), its import can take this form:

type BinaryOp = func(::Real, ::Real)::Real
using MyLibrary: myfunc::BinaryOp

BinaryOp declares the argument types and return type of myfunc. A function's ability to participate in an equation also depends on its compatibility with symbolic arguments and differentiation.

The Native type carries Julia values, such as the medium data used in Media and Fluids.

Julia definitions in a library's own dyad/definitions.jl are available to its Dyad sources. See Julia-Based Component Libraries for that integration and Syntax Reference for import forms.