Metadata Tags

Some metadata tags are reserved by either the GUI application or the various backends. This page is a registry of reserved tag names and their semantics. For backends, this page gives general conventions while leaving detailed information to the page associated with each backend.

Tags that apply to any item (variable, part, top-level model):

• notes -- Documentation for the item. This will sometimes be shown as a tool-tip when the mouse hovers over the item. The tool-tip will only show the first sentence (up to newline or full stop, whichever comes first). Synonyms include "note" and "description".

Tags that appear on the top-level model or component:

• backend={backend name} -- Specifies which backend should execute the model. Default is "internal".
  • {backend name} -- Detailed configuration of a specific backend.
  • all -- Configurations that all backends should follow, if possible.
    • event={before,during,after} -- Event-delivery mode. If an event is scheduled to arrive at exactly the same moment as a simulation step, this mode determines which gets done first. "before" means that equations associated with the event are evaluated before the simulation step. Likewise, "after" means the simulation step is executed first, then equations associated with the event are evaluated. "during" means that the associated equations are evaluated as part of the simulation step.
    • fastExit -- When the top-level part dies, shut down the simulation without going through formal destruction of all the sub-parts. This can save time that would otherwise be spent freeing many small objects, but it also skips evaluation of equations that might be useful for the final result of the simulation.
    • integrator={Euler,RungeKutta} -- Indicates the desired method to integrate derivatives each simulation step. "RungeKutta" is expected to be RK4. There are of course many other integration methods. These will be added as the repertoire of backends grows. If nothing is specified, the simulator uses its default integration method.
• gui -- Tags that affect behavior of the GUI application.
  • category -- A comma-separated list of categories under which to list the part. These appear as folders on the left in the Models tab. A category may be specified as a sub-folder using the forward slash. For example: Base/Synapse puts the part in the Synapse folder inside the Base folder. Any depth of folder is possible.
  • dropin -- Indicates that we are meant to modify another component via inclusion. For example, a calcium channel in a compartment model. During drag-n-drop, the GUI inserts a sub-component rather than a peer of the drop target. See mixin for related functionality.
  • icon -- String containing Base64-encoded image data, typically in PNG format. This specifies the image displayed next to the part in the component library.
  • mixin -- Indicates that this component is meant to modify another component via multiple inheritance. During drag-n-drop, the GUI inserts our class name ahead of any others in $inherit.
  • pin={pin name} -- All features associated with dataflow-style modeling store their information under this key. See description of pin for parts.
    • {in/out} -- Describes the input pin block and the output pin block for this component. These are actually two separate keys, but they have the same structure.
      • {pin name} -- Indicates which pin in the block this item describes.
        • color -- The GUI display color for the pin. Specified as an integer or #hex (similar to CSS color names).
        • notes -- Documentation specific to this pin. Provides a tooltip in the GUI. See the "notes" tag.
        • order -- Position when enumerating pins along the side of a component. Default sort key is the pin name (alphanumeric order).
    • bounds -- Of the input and output blocks as displayed on a part's canvas.
      • {in/out} -- Specifies the block type.
        • x,y -- Position of the block. (The size of the block is automatic.)
• host -- Specifies which system should execute the model. This is the name you assign in Settings:Hosts, which may be different than the network name. Subkeys specify details such as scheduler parameters, which are interpreted by the specific class as configured in Settings:Hosts. Some of these keys are standardized across Slurm, LSF and MPI.
  • time -- Maximum time the job is expected to run. Specify with UCUM time units (d, h, min).
  • nodes -- Number of compute nodes. Not to be confused with number of tasks or ranks.
  • tasksPerNode
  • cpusPerNode
  • gpusPerNode
  • study={list} -- See "study" below. Causes the study to iterate over different hosts.
  • files -- Subkeys provide a list of files to copy from local system before starting remote job. These go beyond the files normally transmitted by the backend. For example, there may be a data file that must be present for the job to run properly.
    • {local path}={remote path} -- Path is relative to the local job directory, but can also be absolute. Remote path is relative to remote job directory, but can also be absolute. Remote path is optional. If omitted, then remote path is the same as local path. Forward slash is always a valid separator, regardless of which OS is involved.
• seed -- Sets the random seed for a simulation. Value is an integer. When absent, a different seed will be generated for each run of the model. The seed for a given simulation is reported as part of the summary information in the Runs tab, so it should be possible to reproduce a given simulation by copying this value into metadata (and running only one thread). Also, it be necessary to specify seed for a fully deterministic model. Even if it does not directly call random number functions like uniform() or gaussian(), a model can still do random draws, for example when $p is not 1 or when permuting a population for connection.
  • study -- For studies (see below), this flag indicates to set the seed to a random value drawn in a repeatable way from the study's own random sequence. See study.seed below. If the model uses random numbers and seed is not specified and this flag is not specified, then the simulations will not be repeatable (whether in a study or a regular run).
    • count -- Run this many simulations with different seeds.
• study -- Indicates special treatment when executed in multi-run mode. There are several different types of studies, including parameter sweeps and optimization. The exact type depends on the overall combination of sub-keys.
  • group -- A list of group names and their iterator types. Currently, this is only needed to specify Latin-hypercube iteration.
    • {name}={type} -- Type indicates how the group is iterated. "latin" or "permute" indicates to use Latin-hypercube iteration on the members of the group.
  • maxIterations={number} -- Stop optimizing after this many cycles.
  • optimizer={name} -- Specifies which algorithm to use.
  • plugin
    • {plugin name} -- Flag that enables the named extension. Plugins modify each sample job before it runs. Keys that appear below this level can provide additional information. Notice that an inherited plugin setup can be disabled by specifying {plugin name}=0.
  • seed={value} -- Random seed for the study itself, as distinct from the seed for a given simulation. For example, this seeds the random number for generating sample points in parameter space. If seed is not specified, a different seed will be set each time the study runs.
  • toleranceF={value} -- Stop optimizing when loss variable changes less than this amount.
  • toleranceX={value} -- Stop optimizing when free variables change less than this amount.
  • toleranceG={value} -- Stop optimizing when gradient becomes less than this amount.
• watch -- Controls how watched variables are output. This adds keyword arguments to each output() statement generated by the watch mechanism, so sub-keys have the same definitions.
  • timeScale={value} -- Specifies the spacing between tick marks on the horizontal axis. This is a quantity of seconds. It is often simpler to specify this using units. For example: 1h for a tick mark once per hour.
  • scale={value} -- Specifies the spacing between tick marks on the vertical axis as an SI quantity.
  • interval={value} -- How frequently the watched variable should be output, particularly if it is less frequent than the simulation time step $t'.

Tags that appear on parts:

• backend
  • {backend name}
    • part={part name} -- Indicates that this part gets special treatment, such as mapping to a prefab component. Once a backend is selected, it is free to interpret part names as it sees fit. This tag is not necessary unless the given backend specifically requires it. The optional name overrides the part name to ensure the backend finds the correct mapping.
    • ignore -- Prevents the backend from giving this part special treatment.
  • all
    • ignore -- Prevents any backend from giving this part special treatment.
• gui
  • arrow -- String specifying arrow type on a connection: arrow, circle, circleFill.
    • straight -- Indicates straight line rather than curved.
  • bounds
    • x, y -- Position of component.
    • width, height -- Size when in closed state.
    • open -- Boolean indicating open/close state of node.
      • width, height -- Size when in open state.
    • parent -- Boolean indicating open/close state when this node is the parent in NODE view.
      • width, height -- Of parent box in NODE view.
  • icon -- Specifies the image displayed next to the part in an equation tree or the canvas. Generally inherited from a component.
  • order -- Names of items (variables and sub-parts) inside a part, listed in the order they should appear in the GUI. Any other names appear in alphabetical order after these.
  • pin={pin name} -- When the key exists but has no bindings (in/out) specified, then it simply exposes this part as a pin of its container. Connections are exposed as inputs. Populations are exposed as outputs. The default name of the pin is the name of the part.
    When bindings are specified, this part is connected to its peers inside the container. To also expose it as a pin of the container, specify an explicit name.
    If an input pin name ends with "#", then this is an "auto-pin". Auto-pins generate a new pin each time a connection is made to it. Those pins replace # with 1,2,3... This is useful when the number of inputs is not known ahead of time.
    • append={offset} -- For auto-pins, there are two possible behaviors. The connection part is always duplicated for each bound pin. The downstream part it connects to can either be duplicated, or there can be a single population with groups of instances associated with each generated pin. The size of each group is determined by the size ($n) of the respective upstream population. This flag activates the second behavior. If an offset value is specified, then the first bound pin will connect instances with $index starting at the given value. Each subsequent generated pin will connect to the next available $index. This feature involves generating additional variables at compile time. If sufficient constant data are available, they will optimized out. Otherwise they will get computed during the init cycle at runtime.
    • topic -- Multiple parts can be exposed through the same pin. The topic allows them to be distinguished when binding. The topic can be thought of as a category of information which is handled by a particular part. Default is the name of the exposed part.
    • type -- Indicates the data type for the exposed part. Used only by the Fugu backend.
    • pass={pin name} -- Sets up a pass-through on a connection part. With a pass-through, a connection to an output pin is forwarded to the input pin. In addition, any variables defined in the connection part override corresponding variables in the connection part that ultimately gets bound to the output pin. This allows, for example, to define a dataflow block that simply applies a weight matrix to the connection. Default name for the output pin is the name of the connection part.
    • {in/out}
      • {pin name}
        • bind={part name} -- Which peer part this pin is bound to.
          • pin={pin name} -- Which pin on the peer part is bound.

Tags that appear on variables:

• backend
  • {backend name}
    • param={names} -- Indicates that this variable gets special treatment, such as mapping to a parameter of a prefab component. The optional name overrides the variable name. In some case (as specified by the backend) several mappings may be listed, separated by commas.
    • ignore -- Prevents the backend from giving this variable special treatment.
  • all
    • ignore -- Prevents any backend from giving this variable special treatment.
• notes -- Documentation for this variable. Will be shown as a tool-tip when the mouse hovers over the variable. Useful for parameter display mode. Synonyms include "note" and "description".
• param={UI hint} -- Marks a variable to be displayed when filter mode is set to Parameter. The UI hint is optional. Hint types include:
  • a comma-separated list of options -- These are presented in the UI as a drop-down list.
  • [lo,hi,step]unit -- Presented in the UI as a slider. Step is optional. If present, it sets the increments on the slider. Unit is optional. If present, the string is appended to the selected value.
  • "flag" -- Presented in the UI as a checkbox (boolean).
  • "watch" -- Makes the variable show up in Parameter mode, but not have any editable value. This allows the user the mark the variable to be watched.
• poll -- Specifically under $p, indicates the maximum amount of time allowed for one complete pass through all latent connections. Less than 0 disables polling, even if the model logically requires it. 0 means a complete pass every simulation step. Greater than 0 indicates number of seconds. Default value is 1 second. This does not specify how evenly the work is distributed. It may all be done in a single busrt at the last moment, or spread over multiple simulation cycles. See $p in Special variables.
• study={range} -- Indicates special treatment when executed in mulit-run mode. Range can be blank, a comma-separated list, or [lo,hi,step]unit. Step may be omitted. Default step is 1. Unit may be omitted. If present, the string is appended to the current value before the model is parsed. Sub-keys include:
  • count={number} -- How many times to iterate over this variable. Useful when the overall study configuration contains some randomly-generated values.
  • group={name} -- Indicates membership in a set of variables that iterate over a set of values in lock-step, as opposed to all possible combinations.
  • start={value} -- Initial value for optimization. If absent, the optimizer will try to get this from the variable directly. If the variable lacks a direct assignment, then the start value is zero.
  • loss -- Indicates that this variable contains the value to be minimized by the optimizer.
  • max={value} -- Variable should not exceed this. Somewhat redundant with [lo,hi].
  • min={value} -- Variable should not be less than this.
  • optimize -- Indicates that this is a free variable that the optimizer should adjust. Starts at the default value assigned to the variable.
• watch -- Flag that indicates this variable should have an output() statement generated for it automatically. This happens at compile time.

Metadata tags can themselves participate in the parameter user interface and in studies, in a way similar to variables. Certain subtags activate these behaviors:

• study -- Notice that seed.study.count and host.study are specific examples of this. Most other tags can also participate in the study variation process. However, study is not recursive. You can't apply variation to study itself or its sub-tags.
• param
• notes