MANUAL

Loading parameters from a file

Use apply to configure a component from a data file. This is useful for calibrated parameters, controller gains, or several operating configurations of the same model. The file supplies values for declarations already present in the component.

Load a parameter set

Suppose your library is named MyLibrary. Define a component in its dyad/ directory:

component Relaxation
  parameter tau::Real = 1
  parameter target::Real = 0
  variable x::Real
relations
  initial x = 1
  der(x) = (target - x) / tau
end

Save the parameter values in assets/slow.toml:

tau = 5.0
target = 2.0

Apply them when declaring an instance:

component Experiment
  response = Relaxation(apply "dyad://MyLibrary/slow.toml")
end

response now uses tau = 5 and target = 2. The generated model reads the file when it is constructed. After editing the data, construct or run the model again to use the new values; recompiling the Dyad source is unnecessary.

The URI names a file in the containing library's assets/ directory. Use that library's name, even when the instantiated component comes from a dependency. Cross-library URIs and file:// paths are unsupported for apply.

TOML (.toml) and JSON (.json) files are supported. TOML uses Julia's standard library. JSON requires JSON in your library's Project.toml; add it if your library does not already declare it.

Address nested parameters and variable attributes

A file key names a parameter of the applied component. For a component containing a child named controller, a TOML table sets that child's parameters:

[controller]
kp = 2.0
ki = 0.5

Equivalently, use dotted keys at the top level of the file:

controller.kp = 2.0
controller.ki = 0.5

A variable's initial and guess attributes can also be supplied by a file applied to an instance inside a component. For a declared variable pressure, use:

[pressure]
initial = 100000.0
guess = 101325.0

These values have the same roles as declaration attributes: an initial value constrains initialization, while a guess supplies a starting point. See Initial conditions and guesses. Supply only the independent initial conditions your model needs.

Arrays and matrices

Write array values as arrays in the file. For parameter K::Real[2,2] and parameter offsets::Real[3], use:

K = [[1.0, 2.0], [3.0, 4.0]]
offsets = [0.1, 0.2, 0.3]

The outer array is the first axis, so the first row of K is [1.0, 2.0]. The nesting depth, dimensions, and element types must match the declaration; rows must have equal lengths.

Combine file values and explicit settings

For ordinary parameters on an instance inside a component, modifications are resolved left to right. The last value wins:

component Comparison
  from_file = Relaxation(tau=3, apply "dyad://MyLibrary/slow.toml")
  explicit = Relaxation(apply "dyad://MyLibrary/slow.toml", tau=3)
end

Here from_file.tau is 5, and explicit.tau is 3. Multiple apply clauses work the same way: a later file overrides keys shared with an earlier one. Values supplied by the caller constructing the model take precedence over these defaults.

Some declarations have additional rules:

Target	Rule
final parameter	The declared value is preserved; an applied value is ignored with a warning.
Structural parameter of the applied component	A file can supply it, but an explicit modification wins regardless of order.
Structural parameter of a nested child	The applied value is ignored with a warning. Set it through the child's supported configuration interface.
Instance declared inside an analysis	Explicit modifications win regardless of order. Applied initial, guess, and opaque Native table values are ignored with warnings.

For example, an analysis can load the model's ordinary parameters directly:

analysis RelaxationStudy
  extends TransientAnalysis(stop=20)
  model = Relaxation(apply "dyad://MyLibrary/slow.toml")
end

Supported positions and errors

In Dyad 3.4.0, apply is supported on subcomponent instances declared in components or analyses. It is unsupported in extends, variable declarations, subcomponent constraints, and nested modifications such as part(inner(apply "dyad://MyLibrary/slow.toml")).

An invalid URI scheme, library name, or file extension is a compilation error. File-content problems—such as a missing file, malformed data, an unknown name, or a value of the wrong type—produce compilation warnings. Model construction checks the file again and rejects those errors with an apply: message. The ignored values listed above remain warnings rather than preventing construction.