YAML File Format

The Waveform Editor uses YAML files to define the desired waveforms, their organization, and global settings for export. This page describes the structure and syntax of these files.

An example configuration file is provided on the following page:

Overall Structure

A Waveform Editor YAML file is a standard YAML dictionary containing two main types of top-level keys:

  1. globals: A key holding settings that apply to the entire configuration.

  2. Groups: These represent logical groupings for organizing waveforms. They can be nested to create a hierarchy.

Basic File Structure
globals:
  # Global settings here...

top_level_group_1:
  # Waveforms and nested groups here...

top_level_group_2:
  nested_group_A:
    # More waveforms/groups...
  # More waveforms/groups...

Global Properties

The globals section defines parameters applicable to the entire waveform configuration. These parameters can be changed under the "Edit Global Properties" tab in the GUI.

  • dd_version: Specifies the IMAS Data Dictionary version to be used when handling this configuration.

    globals:
  dd_version: 3.42.0

  • imports: Named external data entries that waveforms read from (see Import), keyed by names you choose and refer to with {ref: <name>}. Each value is an IMAS URI, or {port: <name>} for an IDS received on a MUSCLE3 port at run time (used by the actor).

    globals:
  dd_version: 3.42.0
  imports:
    machine: imas:hdf5?path=machine_description1
    scenario: imas:hdf5?path=scenario_run
    live_eq: {port: equilibrium_in}

    Overlay a machine-description IDS with an <ids>/* wildcard import, then override individual nodes.

    ec_launchers:
  ec_launchers/*:
    - {ref: machine}                            # overlay base
  ec_launchers/beam(1)/phase/angle: -1.65898    # then override leaves

Grouping Waveforms

Keys at any level that contain a dictionary represent logical groups. These are primarily for organizing the YAML file and do not affect the final IMAS path of the waveforms defined within them.

ec_launchers: # Top-level group
  beams:      # Nested group
    phase_angles: # Another nested group
      # Waveforms defined here...
    steering_angles:
      poloidal:
        # Waveforms defined here...
      toroidal:
        # Waveforms defined here...

Defining Waveforms

Waveforms are defined by key-value pairs where the key contains a string, a list of waveforms, or a single number (float or integer).

  • Waveform Name: The waveform name represents the unique identifier for the waveform. In order to export the waveform to an IDS the following naming structure must be used. The first segment should refer to the IDS name and the second part should refer to the path in that IDS the waveform applies to, e.g., ec_launchers/beam(1)/phase/angle. It is allowed to not adhere to this format, but in this case the waveforms will not be saved to an IDS during export.

  • Waveform Definition: The value associated with the key defines how the waveform evolves over time. It can take several forms:

    1. List of Tendencies: A YAML list defines a sequence of time-dependent segments, known as Tendencies. Each item in the list is a dictionary specifying the parameters for one tendency.

      ec_launchers/beam(4)/power_launched:
    # Linear ramp from 0 to 8.33e5 for 20 seconds
  - { type: linear to: 8.33e5, duration: 20 }
    # Constant value for the next 20 seconds
  - { type: constant, duration: 20 }
    # Implicit linear ramp back to 0 over 25 seconds
  - { duration: 25, to: 0 }

      If type is omitted it is inferred from the entry's keys: ref → import, to → linear, time → piecewise, value → constant; anything else defaults to linear. Tendencies with no distinguishing key (the periodic shapes, smooth, a value-less constant) must name their type.

      Refer to the Available Tendencies documentation for details on the different tendency types and their parameters.

    2. Constant Value: A simple number (integer or float) defines a constant waveform over time.

      ec_launchers/beam(1)/phase/angle: -1.65898 # Constant value

    3. Empty Waveform: An empty list [{}] defines a waveform that is constantly zero.

      some_ids/data: [{}] # Represents a waveform that is always 0
# This is equal to:
some_ids/data: 0

    4. Derived Waveform: Waveforms may contain calculations or be derived from other waveforms. For more information, see Derived Waveforms.

Slice Notation

Slice notation simplifies addressing ranges within Arrays of Structures (AoSs) in YAML configuration. Slices use Fortran-style indexing, and therefore are: 1-based and inclusive. For example: (1:5) indicates the first 5 elements.

Available Slice Types:

  • Full Slice: (:) - All elements.

  • Range Slice: (start:end) - All elements between start and end.

  • Half Slices:

    • (start:) - All elements starting at start.

    • (:end) - All elements upto and including end.

Example Slices:

The following example will fill the power_launched IDS node in ec_launchers for beam 1, 2, and 3.

ec_launchers/beam(1:3)/power_launched: 5.0

Slicing can be applied at multiple nested levels. For example, the following fills the phase_corrected/data node of the interferometer IDS, for the wavelengths 1 through 4, for channel 2 and 3.

interferometer/channel(2:3)/wavelength(1:4)/phase_corrected/data: 15.0

Complete Example

The following configuration exercises the full imports mechanism: a machine-description overlay (<ids>/*), a scalar import with interpolation, a static value, trailing-subtree and index wildcards (source(*), ion(*)), a 0D composite, and a runtime port-import.

# Reference example for the `imports` mechanism. The URIs are illustrative.
globals:
  dd_version: 4.0.0
  imports:
    machine:  imas:hdf5?path=/path/to/machine_description    # static (no /time)
    scenario: imas:hdf5?path=/path/to/scenario_run           # time-dependent
    live_eq:  {port: equilibrium_in}                         # received at run time

ec_launchers:
  # Whole-IDS import = machine-description overlay: copied in first (as a base),
  # then the leaves below override individual nodes.
  ec_launchers/*:
    - {ref: machine}
  ec_launchers/beam(1)/phase/angle:
    - {type: linear, to: 1.65, duration: 100}

Heating:
  # Scalar (0D) import, resampled onto the export /time with linear interpolation.
  core_sources/source(1)/global_quantities/total_ion_power:
    - {ref: scenario, interp: linear}

  # Static value (not a time series) -- names the source.
  core_sources/source(1)/identifier/name:
    - {value: ec}

  # Trailing /* -- mirror every filled leaf of the subtree from the entry.
  core_sources/source(1)/profiles_1d/*:
    - {ref: scenario}

  # Index wildcard -- import the leaf for every source.
  core_sources/source(*)/global_quantities/total_ion_power:
    - {ref: scenario}

  # Multiple index wildcards -- every (source, ion) combination.
  core_sources/source(*)/profiles_1d/ion(*)/z_ion:
    - {ref: scenario}

Plasma current:
  # Composite (0D only): an analytic segment, then an imported segment. Each fills its
  # [start, end] window.
  equilibrium/time_slice/global_quantities/ip:
    - {type: constant, value: -1.0e6, duration: 1}
    - {ref: scenario, duration: 1, time_offset: 0.5}

  # Overlay onto a live IDS received over a MUSCLE3 port (the actor's equilibrium_in),
  # then override a leaf. Same shape as the machine-description overlay above, but the
  # source is runtime data rather than a file.
  equilibrium/*:
    - {ref: live_eq}
Last update: 2026-07-16