Because SansGUI supports hierarchical levels of classes, an attribute entered in a super class is inherited by all its subclasses. Therefore, the attribute list of a class is defined as a collection of attributes from all of the classes in the path, root down to the actual class.
To add attributes to a class, you need to access the Attribute Grid View of the class. The Attribute Grid View of the class can be obtained in the right pane by selecting the class in the Tree View in the left pane. The Attribute Grid View contains a list of all of the class attributes either inherited from its ancestor classes in the class path or created locally in the class. At the class level, you can only modify locally created attributes. All the inherited attributes are protected, as shown by the background color similar to that of the tool tips registered in the Windows environment. Each row in the Attribute Grid View represents an attribute definition in the class.
If an attribute can be added to a class, the first column of the last row of the Attribute Grid View contains a New>> cursor. In order to create a new attribute, merely enter the attribute code. Once the code is entered, a sequence number is automatically assigned and the New>> cursor is move down to a newly appended row. You need to enter the attribute label and change the default attribute definitions to fit your requirements. The following are a couple notes that may help before going into the details of Attribute Definitions:
Coherence: Although some of the GUI control types can coexist due to the dynamic typing nature in SansGUI, certain types may not coexist. The implementation of SansGUI contains a rich set of validation rules to make sure that you will not have any conflicts in your attribute specifications.
Completeness: The default setting is for a single precision floating point number with In/Out scope. No matter how you modify the definitions, SansGUI will maintain that the specification is complete with all the necessary information at all times.
The following describes the groups of columns used for class attributes:
The attribute code is an internal key for the attribute. It is used by SansGUI to find a matching attribute during class schema version evolution. The code should be unique in the entire class path, including those inherited from the ancestor classes. The attribute code is used as the variable name during source code generation. Taking all of that into consideration, you should apply the variable identifier rules and conventions to select the attribute code. For example, a variable must start with a letter or an underscore in the C programming language. SansGUI will turn all non-alphanumeric characters into underscores and prefix an underscore to the variable name if the first character is a digit.
The attribute field contains the name of the attribute to be displayed in the user interface. It is a short description of the attribute and can be any arbitrary string.
All the attributes in a class will be turned into variables local to the class. Programmatically, a class function has read and write privileges for all the data members in any instance of the class. The class function can also access any data object that is passed to it through the SansGUI application programming interface (API). For example, the simulation control object is passed to all the class functions; therefore, the data members in it become globally accessible. Certainly, a good programming practice is to treat global variables with extreme care, especially when there are synchronization concerns.
In addition to local and global visibility of attributes, SansGUI has a set of copy rules for synchronizing the values in the GUI controls and the internal object data. For a cell attribute, which occupies a single cell in a data input sheet, the copy rules are applicable because the GUI control and the object data have different data storage. The copy rules are not applicable to any array attribute because the same data storage is used for both the GUI control and the internal object data in order to save memory space.
Input: SansGUI will request input from the user. The value entered from the GUI control is copied to the internal object during the initialization stage and will not be copied back after calling a class function. This is for the purpose of retaining the user's input data. Because array attributes have the same storage for GUI control and internal object data, they cannot be specified as input-only.
In/Out: SansGUI will request input from the user. In addition to copying the GUI control data to the internal object during the initialization stage, SansGUI will copy the object data back to the GUI control after calling a class function. The user will see the value change in the GUI control if the data object value is modified programmatically.
Output: SansGUI will not request input from the user. For cell attributes, the object data will always be copied back to the GUI controls after a class function has been called.
Hidden: It is a special Output attribute, which is hidden from the user. You may hide certain working variables critical to the algorithm of your simulator which you do not wish your users to know. A hidden attribute can be revealed in a service session, which can be entered by typing in the password specified by the simulation developer. If you allow the class functions to be overridden by the user, it is suggested that there should not be any hidden attribute in the class.
Port - In/Out: This is a special type of In/Out attribute associated with explicitly defined ports. All port attributes are array attributes because each attribute may occupy multiple cells in a port data entry table. When a port attribute is added to a component class, it should have explicitly defined ports. See the Defining Component Classes section for more details.
The above scopes are mutually exclusive, meaning that only one scope can be selected at a time. One is suppressed when the other is turned on.
Logistic definitions of an attribute indicates how the attribute is managed in the SansGUI environment and in the textual Model File. The available definitions are:
Value Not Required: Check this box if it does not require the user to enter a value for the simulator to run. If a value is not supplied by the end user, the simulator should initialize the value or perform some procedure to provide one. For the special symbol representing uninitialized value written to the Model File, see the SansGUI Model File Format chapter in the SansGUI Reference Manual. This definition can be used for some dynamic default values based upon certain conditions instead of a single default value.
Append Line Break: When writing model data to a textual Model File, SansGUI will send a new line character to the file after the value of the variable is written. You can use this to control the number of variables/values being written for each line.
Allow Parameter: Check this box if you want to allow the user to enter a symbolic parameter for the attribute. Due to data types and memory limitations, array attributes cannot allow parameters.
Allow Part Override: Check this box if you want to allow the user to override values for components, parts or links. If this definition is not turned on, the user will have parts with exactly the same input values derived from a component object. You are encouraged to enable this feature to avoid from having to create a component object for each part that varies only slightly.
String literals in this group differ from those string types listed in the Special Types group in the sense that these types can coexist with other type definitions, such as a numerical quantity. Because SansGUI is dynamically typed during model configuration, you can specify more than one type in the attribute definition. For example, a numerical field can be specified to allow an input file name so that the data can be obtained by fetching the contents of the file during the simulation run. See the GUI Control Data Representation section in the SansGUI Reference Manual for more details.
String: specifies an arbitrary string field.
URL/File: specifies a file name, file path, or URL address field.
The definitions in the quantity group specify the attribute with a numerical type, limits, and its unit of measurement. A cell attribute may also contain a vector or a matrix. See the GUI Control Data Representation section in the SansGUI Reference Manual for details on the syntax and semantics of quantity definitions. It should be noted that the Integer, Real-Single Float, and Real-Double Float definitions are mutually exclusive.
For quantity attributes, the following can be specified:
Integer: specifies an integer quantity field.
Real-Single Float: specifies a real number field implemented as a single precision floating point number.
Real-Double Float: specifies a real number field implemented as a double precision floating point number.
Non-Zero Value: checked, if the user cannot enter the zero value, after converting to the internal unit specified below.
Currency Format: checked, if the value should be displayed in a currency format. SansGUI currently supports the format that shows dollars and cents (1/100 of a collar). When an integer value is specified with the currency format, the internal value will be a whole number in cents.
Unit Reference: specifies the unit dimension, using the name of the unit object selected.
Unit Internal: specifies the internal unit the simulator expects from SansGUI. All values are converted to the internal unit before sending to the simulator.
Vector OK: specifies the field can also be a vector (1-dimensional matrix). This is an option for cell attributes only. For array attributes, both Vector OK and Matrix OK fields are checked and cannot be turned off.
Monotonic Increasing: indicates the vector, if specified, shall have any of its elements be greater than or equal to the previous element except for the first element.
Monotonic Decreasing: indicates the vector, if specified, shall have any of its elements be less than or equal to the previous element except for the first element.
Strictly Increasing/Decreasing: used in conjunction with Monotonic Increasing or Decreasing. This definition takes away the equality relation in those definitions, meaning that any of the elements cannot be equal.
Matrix OK: specifies that the field can also be a 2-dimensional matrix. This includes vectors as a special case. However, SansGUI does not allow monotonicity checking for matrices.
Check Sum: indicates the sum of all of the elements in a vector or a matrix shall be equal to the value specified in the Sum or Default Value field, described next. If not checked, the value entered in the next field is the default value.
Sum or Default Value: specifies the sum (if the Check Sum field is checked) or default value of the attribute. The value is specified in the internal unit, specified earlier. This field is also used as the value of the neutral point, if a qualitative definition described below is given.
Minimum Value: specifies the lower bound of the value range, in the internal unit. This field is also used as the value of the low threshold, if a qualitative definition is given.
Maximum Value: specifies the upper bound of the value range, in the internal unit. This field is also used as the value of the high threshold, if a qualitative definition is given.
The definition of a qualitative attribute contains an adjective and a noun phrase for three critical points: 1) a low threshold, 2) a neutral point, and 3) a high threshold. With these three points, four additional ranks can be defined, which are: 1) below low threshold, 2) somewhat low, 3) somewhat high, and 4) beyond high threshold. The adjectives and the noun phrases are used to construct a linguistic expression for a qualitative value. For example, in the seven selectable ranks in the Quality Input Assistant, the adjective and the noun phrase for a critical point can be in the format of "as <Adjective> as <Noun Phrase>." A sample qualitative value for a temperature attribute is "as hot as the boiling point."
Low Threshold Adjective: specifies the adjective associated with the low threshold.
Low Threshold Noun Phrase: specifies the noun phrase associated with the low threshold.
Neutral Point Adjective: specifies the adjective associated with the neutral point.
Neutral Point Noun Phrase: specifies the noun phrase associated with the neutral point.
High Threshold Adjective: specifies the adjective associated with the high threshold.
High Threshold Noun Phrase: specifies the noun phrase associated with the high threshold.
When a mapping between the quantity and quality space is desired, you need to specify a Certainty Level and an Allowance Factor for each defined critical point. When they are properly specified, each point in the quantity space will have an associated qualitative rank and a confidence factor, ranged between 0.0 and 1.0. The certainty level determines the hedge, or how wide the confidence factor distribution curve should be around the critical point. SansGUI uses certainty level 1 for normal blending between two ranks. For each increasing certainty level, SansGUI simply condenses the curve of the previous level by taking the square value of each point in the curve. The certainty level can be from 1 to 7, as depicted in the following figure. The horizontal axis U represents a normalized quantity space.
The allowance factor determines a cut-off line from 1.0. When the user enters a confidence factor that is beyond (1.0 - AllowanceFactor), the (1.0 - AllowanceFactor) will be used to calculate the selection range in the quantity space. If the confidence factor is on or below (1.0 - AllowanceFactor), the confidence factor is used directly to obtain the selection range. You can use this factor to set a minimum selection range of a rank.
The fields for Quantity/Quality Map definitions are:
Low Threshold Certainty Level: specifies the certainty level of the low threshold.
Low Threshold Allowance Factor: specifies the allowance factor of the low threshold.
Neutral Point Certainty Level: specifies the certainty level of the neutral point.
Neutral Point Allowance Factor: specifies the allowance factor of the neutral point.
High Threshold Certainty Level: specifies the certainty level of the high threshold.
High Threshold Allowance Factor: specifies the allowance factor of the high threshold.
Except Object Reference, the following special types are static, meaning that the types cannot coexist with other types when it is defined. They use special GUI controls; therefore, the type is fixed. The Object Reference type can coexist, however, with the a URL/File type and/or a quantity type. The actual type of such an attribute is determined when the user actually enters its value in the GUI control, which becomes fixed during simulation run-time. See the GUI Control Data Representation section in the SansGUI Reference Manual for more details.
Date Format: specifies the attribute is represented by a date field.
Time Format: specifies the attribute is represented by a time field.
On/Off Switch: specifies the attribute is an on/off switch.
Tri-State Switch: specifies the attribute is a tri-state switch.
Encrypted String: specifies a string field whose value is to be encrypted.
Input Mask: specifies a string field with a input mask. The masking literals can be found in the GUI Control Data Representation section in the SansGUI Reference Manual.
Enumerated Items: specifies an integer field with a list of items predefined for user to select. The specification of the Enumerated Items is a string with selection items separated by a vertical bar (|). For example, a list with low, medium, and high selection items is specified with a low|medium|high string with low as the default value (base index 0).
Object Reference: specifies a name field for a reference object. In the specification of the attribute, you enter a string with compatible reference class paths separated by a vertical bar (|). When you enter a class, all the subclasses under the class become compatible. The order of the reference classes is used for finding reference objects.
It is much easier to enter enumerated items and object reference classes in the Attribute Properties dialog, which is discussed in more detail below.
The Attribute Grid View shows a class attribute in each row. The advantage is that you can see all the class attributes in one sheet. However, it is hard to edit the definitions of a particular attribute by scrolling this sheet horizontally. For this purpose, you can use the Attribute Properties dialog to examine and modify a single attribute. To invoke the Attribute Properties dialog:
From the Attribute Grid View, locate the attribute of interest.
Double click on the Sequence Number, Code or Attribute field, or right click on either field and select Properties from the context menu. The Attribute Properties dialog will be displayed.
When you double click on the Code or Attribute field, make sure that the pointer is not on top of any character; otherwise, it will lead you to a field editing mode. Most of the fields are the same as in the Attribute Grid View. The major input enhancements are with the Enumerated Items and Reference Classes.
To add new enumerated items:
Click on the New button next to the Enumerated Items label or press the Insert key while the Enumerated Items field has input focus.
An edit box will be in place for you to enter a string.
Repeat the previous procedures to add more items.
You can arrange the sequence of the items by selecting an item and using the Move Up and Move Down buttons to move it. The Delete button is for deleting a selected item.
To enter a compatible reference class for an object reference field:
Click on the New button next to the Reference Classes label or press the Insert key while the Reference Classes field has input focus.
A button labeled with ... will appear to the right of the editing field.
Click on the button to obtain a Single Item [Select] dialog with a hierarchical list of all reference classes.
Pick a class by clicking on the class name or icon. The selected class is displayed in the protected field on top of the selection list.
Click on the OK button to close the selection dialog. The selected class is entered into the Reference Classes field.
Repeat the previous procedures to add more reference classes.
The order of the reference classes is used for finding reference objects.
If you add a class to the reference class list, all the subclasses will be added in the specification.
 |
 |
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.