Understanding Parameters

Value Types

ADS Ptolemy requires specific parameter value types (string, real array, or complex) for the component parameter values you enter in schematic designs.

Component parameter values can be entered several ways:

• Editing the component parameters dialog box. Double-click the component symbol on the schematic, the dialog box appears. Parameter values can be selected from lists or entered. The dialog box lists the value type expected, such as real or integer.
• Editing values directly on the schematic. Click the parameter value and type.
• Editing default values in the Design Definition dialog box. Choose File > Design/Parameters > Parameters tab. A type of parameter value can be selected from the Value Type list, and a default value can be entered in the Default Value field.

The following table describes each value type.

Ptolmey Parameter Value Types

Value Type	Description
Real	Editing in Component Parameter dialog box: A. Enter real number. B. Enter expression for a real value†”Example: X*cos(Y), where X and Y are defined expressions. Parameter editing on schematic: Highlight parameter value on schematic and enter real value or expression.
Integer	Editing in Component Parameter dialog box: A. Enter integer. B. Enter expression for an integer value†”Example: X+Y, where X and Y are defined expressions. Parameter editing on schematic: Highlight parameter value on schematic and enter integer value or expression.
Fixed Point	Parameter editing in Component dialog box: A. Enter real value, but the value used will be based on the precision used with this parameter. B. Enter expression for a real value†”Example: X*cos(Y), where X and Y are defined expressions. Parameter editing on schematic: Highlight parameter value on schematic and enter real value or expression.
Complex	Editing in Component Parameter dialog box: A. Enter a complex number using the form Re + j * Im. B. Enter expression for a complex value†”Example: cos(X)+j*sin(Y), where X and Y are defined expressions, j is the imaginary operator. Parameter editing on schematic: Highlight parameter value on schematic and enter complex value or expression.
String	Editing in Component Parameter dialog box: A. Enter string. Do not enclose this string with any double quote symbols. Note for embedded double quotes ("), use double double quotes (""). B. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a string value. Parameter editing on schematic: Highlight parameter value on schematic and enter string value enclosed with double quote symbols.
Precision	Editing in Component Parameter dialog box: A. Enter string in the form X.Y or Y/W. Do not enclose this string with any double quote symbols. The form X.Y, such as 8.24, means that there are X bits (including sign bit) to the left of the decimal point, and Y bits to the right of the decimal point. The form Y/W, such as or 24/32, means that there are Y bits to the right of the decimal point and W bits total. Note that X+Y=W. B. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a precision value. Parameter editing on schematic: Highlight parameter value on schematic and enter string value enclosed with double quote symbols.
Filename	Editing in Component Parameter dialog box: A. Enter string for the name of a file including the pathname and select an extension type. The filename may include environment variables such as Ëœ/, $HOME, $HPEESOF_DIR, or others. B. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a filename value. Parameter editing on schematic: Highlight parameter value on schematic and enter string value enclosed with double quote symbols.
Integer Array	Editing in Component Parameter dialog box: A. Enter integer values directly†”Example: 1 -2 5 2 (spaces separate data). B. Enter values from a file†”Example: <filename. If the filename has no path specified, the project data directory is used. The content of the file must be numbers separated by spaces or on a new line. For example: 1 -2 5 2 and 1 -2 5 2 are equivalent. C. Enter values directly in addition to file data†”Example: 1 <file1 2. If file1 contains -2 5, then the array would be the same as in A. D. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for an integer array. E. Enter values separated by commas, and surrounded by curly braces. Example: @{1,-2,5,2}. Parameter editing on schematic: Highlight parameter value on schematic, then: enter array values enclosed with double quote symbols or enter array values as shown in E without the @ and double quote symbols.
Fixed Point Array or Real Array	Editing in Component Parameter dialog box: A. Enter fixed-point values directly†”Example: 1.2 -2.3 5.6 2.8 (spaces separate data). B. Enter values from a file†”Example: <filename. If the filename has no path specified, the project data directory is used. The content of the file must be numbers separated by spaces or on a new line. For example: 1.2 -2.3 5.6 2.8 and 1.2 -2.3 5.6 2.8 are equivalent. C. Enter values directly in addition to file data†”Example: 1.2 <file1 2.8. If file1 contains -2.3 5.6, then the array would be the same as in A. D. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a fixed-point or real array. E. Enter values separated by commas, and surrounded by curly braces. Example: @{1.2,-2.3,5.6,2.8}. Parameter editing on schematic: Highlight parameter value on schematic, then: enter array values enclosed with double quote symbols or enter array values as shown in E without the @ and double quote symbols.
Complex Array	Editing in Component Parameter dialog box: A. Enter complex values directly as ordered pairs separated by a comma (optional spaces may follow the comma). Each ordered pair must be enclosed in parentheses, and separated from other ordered pairs by spaces. Example: (1.2,2.5) (-2.3,1.3) (5.6, -1.4) (2.8, 3.4) B. Enter values from a file†”Example: <filename. If the filename has no path specified, the project data directory is used. The content of the file must be ordered pairs of numbers separated by a comma (optional spaces may follow the comma). Each ordered pair must be enclosed in parentheses, and separated from other ordered pairs by spaces or on a new line. For example: (1.2, 2.5) (-2.3, 1.3) (5.6, -1.4) (2.8, 3.4) and (1.2, 2.5) (-2.3, 1.3) (5.6, -1.4) (2.8, 3.4) are equivalent. C. Enter values directly in addition to file data†”Example: (1.2,2.5) <file1 (2.8,3.4). If file1 contains (-2.3, 1.3) (5.6, -1.4), then the array would be the same as in A. D. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a complex array. E. Enter values separated by commas, and surrounded by curly braces. Complex values must be entered using the format a+j*b. Example: @{1.2+j*2.5, -2.3+j*1.3, 5.6-j*1.4, 2.8+j*3.4} Parameter editing on schematic: Highlight parameter value on schematic, then: enter array values enclosed with double quote symbols or enter array values as shown in E without the @ and double quote symbols.
String Array	Editing in Component Parameter dialog box: A. Enter string values directly†”Example: "Button 1" "Button 2" "Button 3"(each string is enclosed with double quote marks, spaces separate each string). B. Enter values from a file†”Example: <filename. If the filename has no path specified, the project data directory is used. The content of the file must be text separated by spaces or on a new line. For example: "Button 1" "Button 2" "Button 3" and "Button 1" "Button 2" "Button 3" are equivalent. C. Enter values directly in addition to file data†”Example: "Button 1" <file1 "Button 3". If file1 contains "Button 2," then the array would be the same as in A. D. Enter value by reference†”Example: @Y, where Y is a the name of a Variable or Expression for a string array. Parameter editing on schematic: Highlight parameter value on schematic and enter array value enclosed with double quote symbols.
Enumerated Type (with form specific to the component)	Editing in Component Parameter dialog box: A. Select enumerated type from selection list specific to the component parameter. For example, Time Unit (milliseconds, etc.) is an Enumerated Type you choose from a list. The Data Flow Controller parameter Scheduler Type is also an Enumerated Type. B. Select the "Standard" enumerated type and enter an integer value in the entry field provided. The integer value is associated with an option in the selection list with the first selection list entry associated with the integer 0,the second entry with the integer 1, etc. C. Select the "Standard" enumerated type and enter the expression in the entry field provided for an integer value†”Example: X+Y, where X and Y are defined expressions. Parameter editing on schematic: Highlight parameter value on schematic and enter enumerated value, or use the up or down arrow keys on the keyboard to scroll through the enumerated options available.

To define or see the list of value types for a schematic design, from a Signal Processing Schematic window, choose File > Design/Parameters > Parameter. The list of parameter types available for a schematic design can be seen by selecting the Value Type drop-down list.

All parameter types except Enumerated, are directly available to define parameters in a schematic design. To use the Enumerated type for a schematic design, you must edit the design AEL file (located in the project networks directory) and implement the AEL code for the desired Enumerated type. Examples of AEL for Enumerated types can be observed in the file $HPEESOF_DIR/adsptolemy/ael/stars.ael.

Parameter Editing

When an instance of a component or design is placed on the schematic, its parameters can be viewed below its symbol.

The default is for parameters to be visible on the schematic. To enable parameter visibility on the schematic, check two areas. From the Schematic window, choose Options > Layers , a dialog box appears. In the Layers list (left), select Parameters. Make sure that the Visible box is checked (center). Next double-click any component in the schematic. This displays the component parameters dialog box. Make sure that the Display parameter on schematic box (lower-center) is checked.

To illustrate this procedure, we will place an instance of the FreqPhase component.

1. Choose Insert > Component > Component Library.
2. From the Library list, select Numeric Communications and then FreqPhase from the Components list on the right.
3. Place this component on the schematic.

Observe that its parameters (visible below its symbol on the schematic) are SampleRate, PhaseJitterFrequencyHz, FrequencyOffsetHz, and PhaseJitterAmplitudeDeg, as shown here.

Notice that each parameter has a numeric value. These values could just as easily be an expression. Note that the SampleRate parameter is given as an expression, 2*pi. The full features of Advanced Design System expressions are discussed in the Simulator Expressions, and Measurement Expressions documentation.

To observe the detail of the schematic design associated with the FreqPhase component, click the symbol to highlight it, then choose View > Push into Hierarchy or click the Push into Hierarchy button (down arrow icon) from the toolbar. The FreqPhase schematic opens.

Notice that the various components in this schematic reference the top-level FreqPhase parameters by name. The RampFloat component Step parameter= 2*Π*FrequencyOffsetHz/SampleRate, where FrequencyOffsetHz and SampleRate values are passed in from the top level.

To view the parameters defined (or to define additional parameters) for this schematic design, choose File > Design/Parameters. The Design Parameters dialog box appears. Select the Parameters tab and you will observe fields to enter parameter definition information. For more information on the Design Definition dialog box refer to Creating Hierarchical Designs.

Parameter Expressions

Parameter values can be arithmetic expressions. This is particularly useful for propagating values down from a top-level system parameter to component parameters down in the hierarchy. An example of a valid parameter expression is:

x = pi/(2*order)

where order is a parameter defined in the network or top-level system, and pi is the built-in constant Π. The basic arithmetic operators are addition (+), subtraction (-), multiplication (*), division (/), and exponentiation (^). These operators work on integers and floating-point (real) numbers. Currently, all intermediate expressions are calculated in double-precision values and only the final value is converted to the type of the parameter being computed. Hence, it is necessary to be very careful when, for example, using floating-point (real) expressions, to compute an integer parameter. In an integer parameter specification, all intermediate expressions will be calculated with double-precision floating-point (real) values and the final value is cast to an integer value.

Complex-Valued Parameters

When defining complex values, the basic syntax is

real + j*imag

where real and imag evaluate to double-precision, floating-point (real) values, which may be numbers or expressions, and where j is the imaginary operator.

There are also other functions in ADS Ptolemy that can be used with complex values. These include:

• An expression/function that returns a Cartesian form: complex (X, Y), where X is the real part and Y is the imaginary part.
• An expression/function that converts a polar form to Cartesian form: polar (X, Y), where X is magnitude and Y is in degrees.
• An expression/function that converts a decibel form to a Cartesian form: dbpolar (X, Y), where X is in decibels and Y is in degrees.

Parameters for Fixed-Point Components

Many fixed-point components used in ADS Ptolemy use one or more common parameters that identify the specific characteristics of the finite-precision, fixed-point value. These include characteristics specifying overflow, overflow reporting, quantization, and finite precision bit format. The following describes several properties in common use by these components.

• Parameters specifying fixed-point value precision are typically labeled Precision, InputPrecision , OutputPrecision , or some other token containing Precision.
  Fixed-point parameter precision is defined by either of two types of syntax:
  Syntax 1

  As a string such as "3.2", or more generally " m.n ", where m is the number of integer bits (to the left of the binary point) and n is the number of fractional bits (to the right of the binary point). Thus length is m + n.

  Syntax 2

  A string like "24/32" which means 24 fraction bits from a total word length of 32. This format, n/w, is often more convenient because the word length often remains constant while the number of fraction bits changes with the normalization being used.

  In both cases, the sign bit counts as one of the integer bits, so this number must be at least one. The maximum value of w (or x+y) is 256.
  Thus, for example, a fixed-point value of 0.8 may have a precision defined as 2/4. This means that a 4-bit word will be used with two fraction bits. Since the value "0.8" cannot be represented precisely in this precision, the actual value of the parameter will be rounded to "0.75".
  When an input pin with an associated fixed-point signal class (scalar or matrix) receives another class of signal (scalar or matrix, respectively), the received signal is automatically converted to the fixed-point class. A pin specified for use with fixed-point scalar signals does not accept any matrix class signals, and vice versa. The automatic conversion from timed, complex or floating-point (real) signals to a fixed-point signal uses a default bit width of 32 bits with the minimum number of integer bits needed to represent the value. For example, the automatic conversion of the floating-point (real) value of 1.0 creates a fixed-point value with precision of 2.30, and a value of 0.5 would create one of precision of 1.31. For details on data/signal conversion rules, refer to Conversion of Data Types.

• ArithType is used to specify the arithmetic form of a fixed-point value. This parameter is an enumerated type with two options: TWOS_COMPLEMENT and UN_SIGNED. Fixed-point components in the Numeric Fixed Point DSP library use either arithmetic form; fixed-point components outside the Numeric Fixed Point DSP library use only the TWOS_COMPLEMENT form (the default).
• RoundFix is used to specify the quantization property of a fixed-point value. This parameter is an enumerated type with two options: ROUND and TRUNCATE. The quantization property is used to convert a floating-point (real) value to its fixed-point value. The ROUND quantization property causes this float-to-fixed transformation to occur such that the nearest fixed-point value to the floating-point (real) value is used. For example, consider the floating-point (real) value 0.1. It is not possible to represent this number exactly as a two's complement fixed-point value. Remember that a fractional decimal number is represented in its fixed-point form by composing it of the summation of fractional powers of two (2 ^-N ). 0.1 is represented as 0.0001100110011...with an infinite number of fractional binary terms. If the precision is 2.8 and the quantization is ROUND , then this above fixed-point value is rounded up to the nearest fractional power of 2 ^-8 which is 0.00011010. If the precision remains at 2.8 and the quantization is TRUNCATE , then the value is truncated to 0.00011001.
• OverflowHandler or OvflwType parameters are used to specify the overflow properties of fixed-point mathematical operations. These parameters are an enumerated type. The overflow parameter specifies the overflow characteristic to use when the result of a fixed-point operation cannot fit into the precision specified.

  OvflowType has two options: WRAPPED or SATURATE. OvflwType is used only by fixed-point components in the Numeric Fixed Point DSP library.

  OverflowHandler has four options: wrapped, saturate, zero_saturate , or warning. OverflowHandler is used by all fixed-point components except Numeric Fixed Point DSP components.

  Consider a fixed-point ramp data source (RampFix) as shown in the following figure. It has a step size of 0.2, initial value of 0, output precision of 2.14, with round type quantization.
  
  

  Schematic Using the RampFix Component

  When OverflowHandler = wrapped, the following data display results:
  
  

  Simulation Plot with OverflowHandler Set to wrapped

  Note that as a 2's complement signal, the maximum value for a 2.14 precision with rounding is nearly 1.9 and the minimum value is nearly −2.0. There are actually more decimal places in these values due to the quantization of the step size. This maximum and minimum is obtained by first converting the step size of 0.2 into its fixed-point form with 2.14 precision. This becomes the step size for the fixed-point ramp accumulation. The signal begins at zero, and increments by the fixed-point binary representation of 0.2 with each sample. When the maximum value is reached, the output wraps to the minimum value for the given precision and quantization.
  When the above example uses the TRUNCATE type of quantization the following data display results:
  
  

  Simulation Plot with TRUNCATE Quantization

  Note that as a 2's complement signal, the maximum value for a 2.14 precision with truncation is 2.0, and the minimum value is -1.9. The signal begins at zero, and increments by 0.2 with each sample. When the maximum value is reached, the output wraps to the minimum value for the given precision.
  With truncation used, but with overflow set to saturate , the following data display results:
  
  

  Simulation Plot with TRUNCATE Quantization and OverflowHandler Set to saturate

  Note that when the ramp rises to 2.0, it stays constant at that level.
  With truncation used, but with overflow set to zero_saturate , the following data display results:
  
  

  Simulation Plot with TRUNCATE Quantization and OverflowHandler Set to zero_saturate

  Note that when the ramp rises to 2.0, it resets to the value of zero and continues to rise.
  Again with truncation used, but with overflow set to warning the following data display results:
  
  

  Simulation Plot with TRUNCATE Quantization and OverflowHandler Set to warning

  Note that the saturate characteristic is used. Additionally, the warning mode results in ReportOverflow being set to REPORT, which reports the number of overflows at the end of the simulation.

• ReportOverflow is used to specify whether overflow is reported. This enumerated type parameter provides two options: REPORT and DONT_REPORT. Consider the preceding overflow displays; for each case, when ReportOverflow = REPORT a warning message is displayed in the Simulation/Synthesis Messages window after simulation. In the previous simulation for the zero_saturate data display, the warning is:

  1: R1: experienced overflow in 9 out of 101 fixed-point calculations checked (8.9%)

  When you click this message, the RampFix component with the name R1 is highlighted in the schematic window.
  When ReportOverflow = DONT_REPORT, a warning message does not appear.

• UseArrivingPrecision is used to specify whether a component is to use the input signal with its arriving precision, or whether this signal is to be cast into another component's specific precision. This enumerated type parameter provides two options: NO or YES. UseArrivingPrecision is used with the InputPrecision parameter; when UseArrivingPrecision = NO, the input signal is cast to the precision specified by InputPrecision; otherwise, the input signal's precision is used.

String Parameters

String parameters are assigned a text value that may include any alpha-numeric symbol, including spaces and other punctuation symbols. If a double-quote symbol (") is to be used, it must be used with two such sequential symbols ("") and will be interpreted as only a single, double-quote symbol.

Filename Parameters

Filename parameters are assigned a filename value that may include the file path name and environment variables such as ~/, $HOME, $HPEESOF_DIR, or others. If no path name is provided, the current project data subdirectory is the assumed path for the file.

Array Parameters

There are two notations for defining array parameters: curly braces and double quotes. The curly brace notation is the preferred method for entering array values. It supports use of variables, variable expressions, simulator expressions, and multiplier symbols (p, n, u, m, k, M, G, ...). The double quote notation is deprecated and should only be used in the special cases described later in this section.

When defining arrays of integers, floating-point (real) numbers, complex numbers, or fixed-point numbers, the basic syntax is a simple comma separated list of values enclosed in curly braces, as shown in the following examples:

• Array of integer numbers specified with literal values
  • value entered in Component Parameter dialog box: @{1, 2, -6, 0, -3}
  • value entered on schematic: {1, 2, -6, 0, -3}
• Array of floating point or fixed-point numbers using a combination of literal values, multipliers, variables, variable expressions, and simulator expressions
  • value entered in Component Parameter dialog box: @{1.5, X, X+sin(Y), 2.3M, 1.8p, -4.1}
  • value entered on schematic: {1.5, X, X+sin(Y), 2.3M, 1.8p, -4.1}
• Array of complex numbers
  • value entered in Component Parameter dialog box: @{1.2+j*2.5, -2.3+j*1.3, 5.6-j*1.4, 2.8+j*log(Y)}
  • value entered on schematic: {1.2+j*2.5, -2.3+j*1.3, 5.6-j*1.4, 2.8+j*log(Y)}

The double quote notation uses a comma or space separated list of values enclosed in double quotes (double quotes are omitted when value is entered in Component Parameter dialog box). This notation does not readily support variables and variable expressions (variables and variable expressions need to be enclosed in parentheses in order to work), and does not support at all simulator expressions and multipliers (entering a simulator expression, e.g. 3*sin(X), will result in an initialization error, whereas using a multiplier, e.g. 3.5m, will result in the multiplier being ignored but no error or warning reported). Therefore, double quote notation should only be used in the special cases listed below:

• For arrays of strings (the curly brace notation does not support strings)
  • value entered in Component Parameter dialog box: "FOO" "BAR" "ABC"
  • value entered on schematic: """FOO"" ""BAR"" ""ABC"""
• For reading the array values from a file (the curly brace notation does not support reading values from a file)
  • value entered in Component Parameter dialog box: 1 -1 <file1.txt 2 -3
  • value entered on schematic: "1 -1 <file1.txt 2 -3"
    (see Reading Array Parameter Values From Files for more details)
• When using a repetition factor for a certain value. When a value is repeated several times then the abbreviation value[n] can be used to represent n instances of the same value (the curly brace notation does not support repetition factors)
  • value entered in Component Parameter dialog box: 1[3] -1[5] (same as 1 1 1 -1 -1 -1 -1 -1)
  • value entered on schematic: "1[3] -1[5]" (same as "1 1 1 -1 -1 -1 -1 -1")
• When entering complex numbers using the format (real, imag) instead of real + j*imag (the curly brace notation only supports the format real + j*imag)
  • value entered in Component Parameter dialog box: (1.2, 3.5) (-1.8, 4.21) (6.12, -5.1)
    (same as (1.2+j*3.5) (-1.8+j*4.21) (6.12-j*5.1) or @{1.2+j*3.5, -1.8+j*4.21, 6.12-j*5.1})
  • value entered on schematic: "(1.2, 3.5) (-1.8, 4.21) (6.12, -5.1)"
    (same as "(1.2+j*3.5) (-1.8+j*4.21) (6.12-j*5.1)" or {1.2+j*3.5, -1.8+j*4.21, 6.12-j*5.1})

Reading Array Parameter Values From Files

The values of all array parameter types can be read from a file. The syntax for this is to use the symbol < as in the following example:
< filename
or
1.2 2.6 <filename 2.8 6.4
This syntax is only supported with the double quote notation (see Array Parameters for more details).

If the filename has no path specified, the project data directory is used. Otherwise, the filename should typically contain the full pathname to the file. Any references to environment variables or home directories are substituted to generate a complete path name. All values in the filename must be numeric values for the numeric array types (integerarray, realarray, fixedpointarray, complexarray), and must be string values for the string array type. The contents of the file are read and spliced into the parameter expression and re-parsed. File inputs can be very useful for array parameters which may require a large amount of data. Other expressions may come before or after the < filename syntax (any white space that appears after the < character is ignored). Within the file, comment lines containing a leading pound (#) symbol are ignored by the file parser.

Parameters With Optimization and Swept Attributes

Many component parameters may have associated attributes that are used during nominal optimization. Within the Component dialog box, any parameter of type real, fixed point, integer, or enumerated, may also be optimized for design performance. A complex value may be optimized by optimizing its real and/or imaginary parts.

Parameters of type Complex, Precision, Array, String, or Filename can be optimized or swept by creating a string that references optimized or swept variables. To reference an optimized variable, the variable must be defined in a VAR (Variables and Equations) component with the Standard entry mode and with Optimization/Statistic Setup enabled.

In a manner similar to optimization attributes, there can also be parameters with swept attributes.

For more information on optimization in ADS Ptolemy, refer to Using Nominal Optimization. For more information on sweeping parameters in ADS Ptolemy, refer to Performing Parameter Sweeps.