null Steve Neuendorffer null

The SDF Director is often used to oversee fairly simple, sequential workflows in which the director can determine the order of actor invocation from the workflow. Types of workflows that would run well under an SDF Director include processing and reformatting tabular data, converting one data type to another, and reading and plotting a series of data points. A workflow in which an image is read, processed (rotated, scaled, clipped, filtered, etc.), and then displayed, is also an example of a sequential workflow that requires a director simply to ensure that each actor fires in the proper order (i.e., that each actor executes only after it receives its required inputs).

The SDF Director is very efficient and will not tax system resources with overhead. However, this efficiency requires that certain conditions be met, namely that the data consumption and production rate of each actor in an SDF workflow be constant and declared. If an actor reads one piece of data and calculates and outputs a single result, it must always read and output a single token of data. This data rate cannot change during workflow execution and, in general, workflows that require dynamic scheduling and/or flow control cannot use this director. Additionally, the SDF Director has no understanding of passing time (at least by default), and actors that depend on a notion of time may not work as expected. For example, a TimedPlotter actor will plot all values at time zero when used in SDF.

By default, the SDF Director requires that all actors in its workflow be connected. Otherwise, the director cannot account for concurrency between disconnected workflow parts. Usually, a PN Director should be used for workflows that contain disconnected actors; however, the SDF Director's allowDisconnectedGraphs parameter may also be set to true. The SDF Director will then schedule each disconnected "island" independently. The director cannot infer the sequential relationship between disconnected actors (i.e., nothing forces the director to finish executing all actors on one island before firing actors on another). However, the order of execution within each island should be correct. Usually, disconnected graphs in an SDF model indicate an error.

Because SDF Directors schedule actors to fire only after they receive their inputs, workflows that require loops (feeding an actor's output back into its input port for further processing) can cause "deadlock" errors. The deadlock errors occur because the actor depends on its own output value as an initial input. To fix this problem, use a SampleDelay actor to generate and inject an initial input value into the workflow.

The SDF Director determines the order in which actors execute and how many times each actor needs to be fired to complete a single iteration of the workflow. This schedule is calculated BEFORE the director begins to iterate the workflow. Because the SDF Director calculates a schedule in advance, it is quite efficient. However, SDF workflows must be static. In other words, the same number of tokens must be consumed/produced at every iteration of the workflow. Workflows that require dynamic control structures, such as a BooleanSwitch actor that sends output on one of two ports depending on the value of a 'control', cannot be used with an SDF Director because the number of tokens on each output can change for each execution.

Unless otherwise specified, the SDF Director assumes that each actor consumes and produces exactly one token per channel on each firing. Actors that do not follow the one-token-per-channel firing convention (e.g., Repeat or Ramp) must declare the number of tokens they produce or consume via the appropriate parameters.

The number of times a workflow is iterated is controlled by the director's iterations parameter. By default, this parameter is set to "0". Note that "0" does not mean "no iterations." Rather, "0" means that the workflow will iterate forever. Values greater than zero specify the actual number of times the director should execute the entire workflow. A value of 1, meaning that the director will run the workflow once, is often the best setting when building an SDF workflow.

The amount of data processed by an SDF workflow is a function of both the number of times the workflow iterates and the value of the director's vectorizationFactor parameter. The vectorizationFactor is used to increase the efficiency of a workflow by increasing the number of times actors fire each time the workflow iterates. If the parameter is set to a positive integer (other than 1), the director will fire each actor the specified number of times more than normal. The default is 1, indicating that no vectorization should be performed. Keep in mind that changing the vectorizationFactor parameter changes the meaning of a nested SDF workflow and may cause deadlock in a workflow that uses it.

The SDF Director has several advanced parameters that are generally only relevant when an SDF workflow contains composite components. In most cases the period, timeResolution, synchronizeToRealTime, allowRateChanges, timeResolution, and constrainBufferSizes parameters can be left at their default values.

For more information about the SDF Director, see the Ptolemy documentation (http://ptolemy.eecs.berkeley.edu/papers/05/ptIIdesign3-domains/ptIIdesign3-domains.pdf).

 Specify whether to allow disconnected actors in the workflow (by default, all actors are required to be connected). If disconnected actors are permitted, the SDF Director will schedule each disconnected 'island' independently. Nothing "forces" the director to finish executing all actors on one island before firing actors on another. However, the order of execution within each island should be correct. Usually, disconnected graphs in an SDF workflow indicate an error. Specify whether dynamic rate changes are permitted or not. By default, rate changes are not permitted, and the director will perform a check to disallow such workflows. If the parameter is selected, then workflows that require rate parameters to be modified during execution are valid, and the SDF Director will dynamically compute a new schedule at runtime. This is an advanced parameter that can usually be left at its default value. The time precision used by this director. All time values are rounded to the nearest multiple of this number. The value is a double that defaults to "1E-10" (which is 10-10). This is an advanced parameter that can usually be left at its default value. Specify whether buffer sizes are fixed. By default, buffers are fixed, and attempts to write to the buffer that cause the buffer to exceed its scheduled size result in an error. This is an advanced parameter that can usually be left at its default value. Specify the number of times a workflow is iterated. By default, this parameter is set to "0". Note that "0" does not mean "no iterations." Rather, "0" means that the workflow will iterate forever. Values greater than zero specify the actual number of times the director should execute the entire workflow. A value of 1, meaning that the director will run the workflow once, is often the best setting when building an SDF workflow. The vectorizationFactor is used to increase the efficiency of a workflow by increasing the number of times actors fire each time the workflow iterates. If the parameter is set to a positive integer (other than 1), the director will fire each actor the specified number of times more than normal. The default is 1, indicating that no vectorization should be performed. Keep in mind that changing the vectorizationFactor parameter changes the meaning of a nested SDF workflow and may cause deadlock in a workflow that uses it. Specify whether the execution should synchronize to real time or not. By default, the director does not synchronize to real time. If synchronize is selected, the director will only process the workflow when elapsed real time matches the product of the period parameter and the iteration count. Note: if the period parameter has a value of 0.0 (the default), then selecting this parameter has no effect. This is an advanced parameter that can usually be left at its default value. The time period of each iteration. The value is a double that defaults to 0.0, which means that the director does not increment workflow time. If the value greater than 0.0, the actor will increment workflow time each time it fires. This is an advanced parameter that can usually be left at its default value. null Edward Lee null

The StringConstant actor outputs a string specified via the actor's value parameter.

Specifying strings with the StringConstant actor is convenient, as the actor does not require that strings be surrounded by quotes. The actor is often used to specify file paths, which can be selected using the Browse button available in the actor's parameters.

Specified string values can include references to parameters within scope (i.e., parameters defined at the same level of the hierarchy or higher).

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts a string constant specified by the value parameter. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the actor. Specified strings do not require enclosing quotes. (To include a '$' sign in the string, enter '$$'.) null null null

The Constant actor outputs a constant, which is specified by the value parameter. By default, the actor outputs the integer 1.

The actor can be used to output other types of values, e.g., a string (such as "Hello") or a double (such as 1.2). The actor' s output type matches the type of the specified value.

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts the specified constant. By default, the output is 1. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the Constant actor. By default, the value is the integer token 1. The value can be set to another type, e.g., a string (such as "Hello") or a double (such as 1.2). The output type matches the type of the value specified here. null null null

The Constant actor outputs a constant, which is specified by the value parameter. By default, the actor outputs the integer 1.

The actor can be used to output other types of values, e.g., a string (such as "Hello") or a double (such as 1.2). The actor' s output type matches the type of the specified value.

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts the specified constant. By default, the output is 1. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the Constant actor. By default, the value is the integer token 1. The value can be set to another type, e.g., a string (such as "Hello") or a double (such as 1.2). The output type matches the type of the value specified here. null Daniel Crawl null

This actor executes web services defined by WSDLs. Given a web service's URL of a WSDL and an operation name, this actor specializes its input and output ports to reflect the input and output parameters of the operation. For simple web service types, e.g. string, int, or double, this actor's ports are configured to the matching ptolemy type. Otherwise, the ports are set to XMLTOKEN. When this actor fires, it reads each input port, invokes the web service operation and sends the input data, and outputs the response to the output ports.

The inputMechanism and outputMechanism parameters control the creation of helper actors for complex/nested web service types. (These parameters have no effect for simple web service types). By setting either to 'composite', a composite actor is created for each parameter that is complex/nested. Each composite actor is populated with necessary XML Assembler or XML Disassembler actors needed to build the nested web service type, and the composite actor ports are all simple ptolemy types. Changing the mechanism back to 'simple' deletes the connected helper actors. If you have made changes to the composite actors and don't want them lost, disconnect them from this actor before changing the mechanism to 'simple'.

Limitations:

  • Unused input ports on composite actors must have the corresponding internal links to XML Assembler actors removed. This is because the XML Assembler actors will read a token from each input port whose width is greater than 0.
  • If the input to the web service contains an array of a nested type, the generated composite actors will use SequenceToArray with arrayLength defaulting to 1. For longer arrays, you must manually create them and send to the appropriate XML Assembler actor.
  • Web service responses containing multi-reference values (elements refering to other elements for their content) are not handled.
  • If the WSDL doesn't fully define the operation response, then the corresponding output port is set to XMLTOKEN. You can access the values by using XML Disassembler actor(s).
  • A web service parameter with the WSDL type "any" sets the corresponding actor port type to XMLTOKEN.
  • Multidimensional arrays not handled and the corresponding port is set to XMLTOKEN. You can get or set the values by using XML Assembler or Disassembler actor(s).

If true, then each output port whose name is not a child element of the web service response XML document outputs a nil token. The web service WSDL address. Setting to composite creates XML Disassembler actors for complex (nested) output parameters. Setting to composite creates XML Assembler actors for complex (nested) input parameters. The password for authentication. The timeout in milliseconds. The username for authentication. The web service method name to run. null Edward Lee null

The StringConstant actor outputs a string specified via the actor's value parameter.

Specifying strings with the StringConstant actor is convenient, as the actor does not require that strings be surrounded by quotes. The actor is often used to specify file paths, which can be selected using the Browse button available in the actor's parameters.

Specified string values can include references to parameters within scope (i.e., parameters defined at the same level of the hierarchy or higher).

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts a string constant specified by the value parameter. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the actor. Specified strings do not require enclosing quotes. (To include a '$' sign in the string, enter '$$'.) null Edward Lee null

The StringConstant actor outputs a string specified via the actor's value parameter.

Specifying strings with the StringConstant actor is convenient, as the actor does not require that strings be surrounded by quotes. The actor is often used to specify file paths, which can be selected using the Browse button available in the actor's parameters.

Specified string values can include references to parameters within scope (i.e., parameters defined at the same level of the hierarchy or higher).

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts a string constant specified by the value parameter. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the actor. Specified strings do not require enclosing quotes. (To include a '$' sign in the string, enter '$$'.) null Edward Lee null

The StringConstant actor outputs a string specified via the actor's value parameter.

Specifying strings with the StringConstant actor is convenient, as the actor does not require that strings be surrounded by quotes. The actor is often used to specify file paths, which can be selected using the Browse button available in the actor's parameters.

Specified string values can include references to parameters within scope (i.e., parameters defined at the same level of the hierarchy or higher).

NOTE: If using a PN Director, the 'firingCountLimit' parameter is often set to a finite integer (e.g. '1') so that the workflow will terminate.

An output port that broadcasts a string constant specified by the value parameter. A multiport that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. The limit on the number of times the actor will fire. The default value is 'NONE', meaning there is no limit on the number of time the constant will be provided to the output port. Any integer can be provided as a value for this parameter. The value produced by the actor. Specified strings do not require enclosing quotes. (To include a '$' sign in the string, enter '$$'.) null Yuhong Xiong, Edward A. Lee null

The Ramp actor is the equivalent of the "for loop" in many traditional computer languages. Its parameters include an intial value, the amount the value is incremented each time the actor fires (the 'step'), and the upper limit of the value (the firingCountLimit). The actor outputs an integer each time it is fired.

The actor's output can be used as a counter (increasing or decreasing), or as a parameter used in an incremented workflow. For example, the output of a Ramp actor can be input to an Expression actor to create file names that are unique for each iteration (e.g., 'file1', 'file2', etc.) The Ramp actor is also particularly useful with PN directed workflows where there is no way to set the number of iterations as a Director parameter.

The first time the actor fires, it outputs the value of its init parameter. The increment value, specified with either the step port or parameter, will only be added on the following iteration. To add an increment to the first iteration, use the Accumulator actor.

The actor accepts values of any type that support addition.

 An output port that broadcasts the incremented value. An input port that has no declared type (in other words, the port can accept any data type: double, int, array, etc.) If the port is connected, the actor will not fire until the trigger port receives an input token. Connecting the port is optional, but useful when scheduling the actor to perform at a certain time. An input port that accepts the amount by which the output is incremented on each iteration. The port accepts a value of any type that supports addition. The value is an integer and defaults to 1. The number of iterations that transpire before the actor indicates that it is finished. If firingCountLimit is set to zero, the actor has no limit imposed. The amount by which the output is incremented on each iteration. The port accepts a value of any type that supports addition. The default is the integer 1. The value produced by the Ramp on its first iteration. The default value is the integer 0. null Daniel Crawl null

This actor executes web services defined by WSDLs. Given a web service's URL of a WSDL and an operation name, this actor specializes its input and output ports to reflect the input and output parameters of the operation. For simple web service types, e.g. string, int, or double, this actor's ports are configured to the matching ptolemy type. Otherwise, the ports are set to XMLTOKEN. When this actor fires, it reads each input port, invokes the web service operation and sends the input data, and outputs the response to the output ports.

The inputMechanism and outputMechanism parameters control the creation of helper actors for complex/nested web service types. (These parameters have no effect for simple web service types). By setting either to 'composite', a composite actor is created for each parameter that is complex/nested. Each composite actor is populated with necessary XML Assembler or XML Disassembler actors needed to build the nested web service type, and the composite actor ports are all simple ptolemy types. Changing the mechanism back to 'simple' deletes the connected helper actors. If you have made changes to the composite actors and don't want them lost, disconnect them from this actor before changing the mechanism to 'simple'.

Limitations:

  • Unused input ports on composite actors must have the corresponding internal links to XML Assembler actors removed. This is because the XML Assembler actors will read a token from each input port whose width is greater than 0.
  • If the input to the web service contains an array of a nested type, the generated composite actors will use SequenceToArray with arrayLength defaulting to 1. For longer arrays, you must manually create them and send to the appropriate XML Assembler actor.
  • Web service responses containing multi-reference values (elements refering to other elements for their content) are not handled.
  • If the WSDL doesn't fully define the operation response, then the corresponding output port is set to XMLTOKEN. You can access the values by using XML Disassembler actor(s).
  • A web service parameter with the WSDL type "any" sets the corresponding actor port type to XMLTOKEN.
  • Multidimensional arrays not handled and the corresponding port is set to XMLTOKEN. You can get or set the values by using XML Assembler or Disassembler actor(s).

The web service WSDL address. If true, then each output port whose name is not a child element of the web service response XML document outputs a nil token. Setting to composite creates XML Assembler actors for complex (nested) input parameters. Setting to composite creates XML Disassembler actors for complex (nested) output parameters. The password for authentication. The timeout in milliseconds. The web service method name to run. The username for authentication. null null null

The ArrayElement actor reads an array of elements and "looks up" an element specified by a given index number. The specified element is output.

The first element in an array has an index of 0 (the second 1, and so on).

The ArrayElement actor is similar to the LookupTable actor in function; however, the two actors specify arrays and index numbers in different ways. The ArrayElement actor receives an array via its input port and an index number via a parameter. The LookupTable actor specifies an array with its table parameter and receives an index number via its input port.

 An input port that accepts an array from which a value is "looked up" and output. An output port that broadcasts the array element identified by the index number. The index number of an element in the array. The index must be an integer. If the index is out of range (i.e., is greater than or equal to the length of the array), the actor will output nothing. The index can be specified via either the index port or parameter. null Yuhong Xiong, Edward A. Lee null

The Display actor reads tokens of any type via its input multiport, and displays each token on a separate line in a text display window.

Specify the size of the text display window with the rowsDisplayed and columnsDisplayed parameters. Simply resizing the window onscreen does not persistently change the size when the workflow is saved, closed, and then re-opened.

If the input is a string token, then the actor strips the surrounding quotation marks before displaying the value.

Select the suppressBlankLines parameter to specify that the actor not add blank lines to the display. By default, the actor will add blank lines.

Note: this actor can consume large amounts of memory. It is not advisable to use it to display large output streams.

 A multiport that accepts tokens of any type. Specify whether the actor should display blank lines (the default) or suppress them. The vertical size of the display, in rows. The value is an integer that defaults to 10. The horizontal size of the display, in columns. The value is an integer that defaults to 40. The title of the text display window. If specified, the value will appear in the title bar of the text display window. null Xiaowen null

The XPathProcessor is used to extract a specified tag element from an XML file. The actor outputs an array of selected XML tokens.

The actor uses an XPath string, which provides an XML addressing syntax. XML is a markup language for files containing structured information (content as well as its context, e.g., a value and the fact that it is a "header" or a "footnote"). For more information about XML and XPaths, see http://www.w3.org/.

An output port that broadcasts an array of selected XML tokens. An input port that accepts an xpath string used to identify XML elements (e.g., //tag_name) An input port that accepts an XML token. An input port that accepts an xpath string used to identify XML elements (e.g., //tag_name)