SimXpert R3.2 Template Builder Workspace Guide

1

Template Builder Workspace GuideIntroduction

Overview of Template Builder workspace2

Overview of Template Builder workspace The Template Builder workspace in SimXpert is a graphical authoring environment for creating SimXpert Templates. A SimXpert Template, or simply “template,” can automate repetitive tasks, define CAE methods, and perform simulations. Templates can be built using Macro Record to record commands as they are executed. Or, with the use of built-in Action library, the template author can combine SimXpert commands and user-written scripts into a customized procedure. The CAE expert will find Template Builder workspace a useful tool for capturing and sharing knowledge and best practices across the enterprise.

SimXpert Templates can be complex procedures that span multiple workspaces in SimXpert. Batch execution of multiple runs with varying inputs is also supported for DOE and stochastic approaches.

Through the connection to SimManager, SimXpert Templates can be published for enterprise-wide sharing, and subsequently retrieved for execution or editing.

3Overview of Template Builder workspace

Opening Template Builder workspaceFrom the entry screen to SimXpert, select Template Builder to open Template Builder workspace.

Using Template Builder workspaceIn the Template Builder workspace, templates can be created from scratch using the building blocks called actions. Most SimXpert commands are available to the template author as actions in the built-in action library. This reduces the need to write code to call SimXpert commands in a template. Or you can create your own custom actions, which will require some ability to write scripts.

The Macro Record feature of SimXpert can be used to record commands during a SimXpert session as a template. The recorded template can then be edited in the Template Builder Workspace.

In the Template Builder workspace, a set of Toolboxes are provided to quickly assemble a process flow.

Overview of Template Builder workspace4

Properties can be assigned to each object in the Template. The Connection tool is used to establish procedure sequence and data flow. Outputs from one action are connected to inputs of another. Looping, Choice, and custom scripts can also be added.

Tools are provided to create user interfaces to gather inputs from the user during template execution. Inputs can be in many different forms, such as a data file, number or text entry, or picking objects from a SimXpert model.

SimXpert Templates may utilize multiple workspaces in SimXpert and may also utilize published objects (templates and actions) from the SimManager database.

5Types of tools used in a SimXpert template

Types of tools used in a SimXpert templateA few terms are essential for Template Builder workspace users:

ActionAn Action is a black-box entity that performs a specific task from inputs and generates outputs. An Action is typically a script (C++, Python, or RADE) that can be written by the user or supplied by MSC in an Action library. Although it is possible for an action to perform a complex task, actions are not interactive. Inputs are collected prior to executing the action and outputs are passed upon completion.

In Template Builder workspace, the default icon for Action is a “script” icon, although a different icon may be assigned by the author:

There are two types of Actions:

Script Action

A Script Action is a reusable action that is stored as a separate file (*.act) on a local drive or in SimManager. The default location for actions created in Template Builder workspace is C:\ <SimXpert install directory> \Process\Actions. This location may be changed in Template Builder Options.

Actions may be in the SimXpert action library (built-in actions) or they may also be user-written. They are accessible from the toolbox in Template Builder and can be linked into any template.

When a script action is used in a Template, an instance of the action is created, which is linked to the script action file. The main script code remains in the action file and may only be changed by editing the source action. When changes are made to a Script Action file, all Templates containing linked instances of the action can automatically receive the modifications. Versioning of actions is provided to facilitate updating of templates.

Embedded Script

An Embedded Script is a script that is wholly contained in a template and is not available as a reusable action.

SimXpert TemplateA SimXpert Template is a collection of Actions, executed in a defined manner. Each action in the template may receive inputs from a prior action and may pass outputs to a subsequent action. Looping, choice, and branching may be defined between actions to give the template flexibility. A Template may also be nested in another Template.

Types of tools used in a SimXpert template6

When executed, the template may be run interactively, gathering inputs from the user as each action is executed. Some templates can be set up to run in batch mode, in which case, all inputs must be supplied at the start of execution.

In Template Builder workspace, the default icon for SimXpert Template is a “gear” icon with connections:

The file extension *.proc is used to indicate a SimXpert Template (process) file. The default location for Templates created in Template Builder workspace is C:\ <SimXpert install directory> \Process.

Embedded Template

Template Builder allows for creation of a “sub-template” within a template. This is called an embedded template and is saved as part of the parent template, rather than as a separate *.proc file.

VRADE Template

A template that was built using the previous “SimTemplate Builder” (now located on Tools menu in SimXpert Template Builder workspace) is called a VRADE (Visual RADE) Template. Starting with SimXpert R3.2, a VRADE template may not be used as a component in a template built in the Template Builder workspace.

These templates are supported for legacy purposes, and may still be executed from Tools > Templates menu. But new templates should be built using the Template Builder workspace.

7Overview of typical steps used

Overview of typical steps usedThe following is an overview of the typical steps used to create a SimXpert template in the Template Builder workspace:

Step 1: Create a new SimXpert TemplateUse Macro Record to create a template by executing SimXpert commands. (See Recording a Macro.) Open the recorded macro in Template Builder for further editing.

Or start with a blank window to begin editing a new SimXpert Template. From Controls toolbox, select New Template. See Creating a new template for details.

Step 2: Position actions and templates in the workspaceSelect and drop existing actions from the Actions toolbox into the template builder window. Likewise, place existing templates from Templates toolbox into the new template. Published actions and templates can be retrieved from SimManager and placed into the current template using the Published toolbox. See Inserting objects in a template for details.

Overview of typical steps used8

Step 3: Add new script actions Advanced users may wish to create their own script actions. (Python, RADE). A script editor and a Python debugger are provided to aid in the creation of scripts.

The action editing tool provides automatic code generation for input and output parameter declarations. It also provides a wide selection of user interfaces for input parameters, such as text box, drop list, picking from model, option buttons, or direct input from a prior action.

All public classes and methods of the SimXpert API are made available to action authors.

See Creating a new script action for more information.

Step 4: Add user prompts & inputsAdditional tools are provided to add prompts for the user to supply data and files during template execution. The File and Prompt tools on Controls toolbox are used to gather input files and strings, respectively.


Each action in a template may be assigned different prompting behavior for inputs, to control when prompting occurs. Different display icons may be assigned, including an interactive graphics snapshot icon.

In the case of user-written actions, user interface options may be added, such as buttons, sliders, file choosers, etc. See Parameter Interface for details on creating user interfaces.

Step 5: Add connections, branching, and loopingConnections are created using the Connection tool to control the sequence of execution and to pass data between actions. When a connection is made, outputs parameters of one action are automatically provided as inputs to a downstream action. Edit each connection to select the parameters to be passed.

Use the Choice tool to create branching, where the template execution proceeds in different directions, depending on the value of the choice.

Three Loop tools are provided to repeat a group of actions until some condition is satisfied.

See Controls toolbox for details.

Step 6: Check and set Properties for all template objectsDouble-clicking on any template object will open the Properties dialog box for that object. It is recommended to check the Properties for each object in the template (actions, sub-templates, and connections) before testing.


The Properties of an action instance that can be changed in the dialog box include: Prompting behavior, display icon, input parameter default values, etc.

Connection properties should also be checked to make sure the desired parameters are being passed from one action to another.

See Action Properties dialog box and Connection tool for details.

The properties for the template itself should also be checked and modified, as needed. See Template Properties dialog box.

Step 7: Save & Execute the SimXpert TemplateWhile creating a SimXpert template, it can be tested using the Template Execution window. Once completed and saved, the template becomes available in the appropriate workspace(s). The Template Execution window can be opened from any SimXpert workspace. See Testing a Template for details.


Step 8: Publish the SimXpert Template to SimManagerTemplates can be published to SimManager from the Properties dialog box. This allows other users throughout an organization to run the published Template. User-written Actions may also be published as Resources.

See Publishing from SimXpert to SimManager for details.


13

Creating Templates

Template Builder Workspace window14

Template Builder Workspace window

Open Template BuilderFrom the entry screen to SimXpert, select Template Builder workspace to open Template Builder.M

If SimXpert is already opened in a different workspace, use the Workspace selector and select Template Builder from the list.

Getting around in Template BuilderThe main areas of the Template Builder workspace are shown in the image:

15Template Builder Workspace window

Menus and Toolbars

The Template Builder workspace has a limited set of SimXpert commands and toolbars, containing only those that might be needed during template building and testing. Refer to the Quick Reference Guide for help on menu commands. (Help > Quick Reference > Template Builder .)

Toolboxes

A unique set of Toolboxes exists for the workspace. The tools allow for quick access to Actions and Templates and stored on the user’s machine. The ability to browse and retrieve items from SimManager is also available on the workspace toolbox. A full set of controls and editing tools are provided for the assembly of new templates.

Note: All toolboxes and sub-menus are detachable by clicking on the dashed line at the top of the tool list. The detached toolbox can be parked anywhere in the SimXpert workspace.


Toolboxes may also be viewed in tree form by right-clicking in toolbox area and checking Tree Display.

Context menus

Right-clicking on any object will bring up a context menu for that item. See also: Context menus

Model Browser

The Model Browser shows the contents of all templates and actions that are currently opened for editing. Several templates can be open for editing at the same time. Use the Model Browser to view the open

17Template Builder Workspace window

templates and the contents of each. Clicking on the template’s name or icon in the Model Browser will change the template displayed in the graphics window and the selected template will become “current.”

The same is true for script actions. Multiple actions can be opened for editing and the Model Browser is also used to display and switch between actions.

Getting Help

Context Help

Click the “?” at the upper right corner of any dialog box, or simply click F1 key to open context-sensitive help for the current command or dialog.

BalloonTips

Hovering the mouse over any item in a toolbox or the graphics window will cause a “balloon” window to appear. Information in the balloon tip includes the name and description of the object, as well as descriptions of input and output parameters. User-written actions will also display a balloon tip, showing the documentation provided by the action author.


Search Tools

A search utility can be opened by right-clicking in toolbox area and selecting Search.

Just type a string into the text box and all tools containing the string are immediately displayed, along with their parent folder organization.

19Editing an existing template

Editing an existing template Upon initial opening of the Template Builder workspace, you have the option to create a new template or action, or to open an existing one. If a template file is already existing, such as a recorded macro, use the following steps to open and edit the template file.

Step 1: From the entry screen select Open... Browse. (Or if the template has recently been accessed, it may appear on the list just below the Browse command.)

Step 2: Use file open dialog to locate the existing template, which has a *.proc file extension, and Open.

For now, ignore any file type of *.act, since these are actions, not templates. (See Creating an Action section of User Guide)

Step 3: Upon selecting the template file, it is opened and is visible in flowchart form in the graphics window, and in tree view in the Model Browser.

Step 4: You may see a warning message or red circle icon indicating that one or more actions in the template are invalid or missing. This is caused by a mismatch in the version, or by the action not being found in the expected location.

Editing an existing template20

Double-click on any action instance marked in this way to open its Properties. Use Update button to locate and replace with the latest version of the action, or re-establish the correct file path using a file browse dialog.

Step 5: Refer to other sections of this User Guide for modifying and adding objects to the template.

21Creating a new template

Creating a new template

Using Macro RecordAn easy way to get started with creating templates is to “record” all or part of a template using Macro, Record (on Tools menu in other workspaces). This is a good option when the template will consist primarily of standard SimXpert commands and tools. Macro recording creates a template file format (*.proc) which can then be edited in Template Builder. See Recording a Macro section of this User Guide for details on recording a macro.

Using Template BuilderA new template can be started from the entry screen of the Template Builder workspace, or at any time once working inside the workspace.

Step 1: From the entry screen select New, Template.

If Template Builder is already open and another template is being edited, it is possible to start a new template without closing the current one. From Controls toolbox, choose New Template. (Or, right-click in a blank area of the template builder graphics window to access the Controls toolbox.)

Creating a new template22

Step 2: The new Template is automatically given a name such as Template1, and appears in the Model Browser. The small blue “clock” over the Template icon indicates that it has not yet been saved.

Step 3: Double-click on the icon to open up a Properties dialog box. Enter a display Label for the template, if desired. Otherwise the Name will be used as the display label.

Step 4: Type in a new Name, which will be used as the file name for the template, and need not be the same as the label.

Step 5: Enter a brief Summary for the Template. Enter a detailed Description in the large text box, and Apply. The Model Browser updates the template label.

Step 6: Version is automatically set to 1.000 and normally should not be changed for a new template.

Step 7: Indicate whether you want to “Save current unit system” in the template. If checked, current user Units will be checked against the saved Unit system upon execution. The user will be prompted if mismatch of units occurs.

Step 8: Revisit the Properties dialog box later, once the template actions, inputs, and outputs have been established. For now, close the Properties panel by clicking Ok.

Step 9: Proceed to insert actions into the template, as described in Inserting objects in a template.

23Recording a Macro

Recording a MacroThe Macro Record feature can be used to capture the code associated with the SimXpert commands executed in one of the SimXpert analysis workspaces. (Structures, Crash, etc.) A template file format (*.proc) is created, which can later be edited in Template Builder.

Step 1: To turn on Macro Record, go to Tools menu, then Macro, Record New Macro.

Step 2: A dialog appears in which to specify the Name and code format, (Currently, only neutral format is supported.) and Location for the macro.

Step 3: If it is desired to always execute the template in the current unit system, check the Record current unit system box. Otherwise MKS (meters- kilograms- seconds) is assumed. Upon playback, the current model units settings will be changed to MKS.

Step 4: Click Ok to begin recording.

Step 5: A small control button toolbar appears. Use the Pause control button (right button) to temporarily stop recording at any time without ending the session. Click again to resume.

Step 6: Execute the SimXpert commands to be recorded. During recording, the record-able commands in menus, toolbars and toolboxes are marked with a small red dot and/or the label “(Rec.)”

Recording a Macro24

The recording may include the execution of templates, macros, and scripts. Their execution will be recorded as part of the macro. For Template execution, only the full, successful, execution of the template is recorded (i.e., stepping through Actions is not recorded).

Script execution from the Script editor (or Macros dialog) is also recorded as an embedded Script Action in the macro. If an unmodified script file is opened and executed, then a reference to the file will be recorded. Otherwise, the script code itself will be copied into the recording.

Everything that is recorded to a macro is also recorded to the session file.

Step 7: Click Stop button when done. A macro file will be saved as a template (*.proc) file format. The saved macro file may later be refined and edited in Template Builder.

Recorded macros may be replayed as a “macro” using the Tools, Macro, Macros menu. In this case the Unit System will automatically change to the recorded unit system. Or a recorded macro can be treated as a template, and can be edited in Template Builder or executed in the Template Execution window.

Gesture recordingWhen picking of objects is done during macro recording, the pick gesture is saved in detail. This goes beyond simply recording object i.d.’s. The saved information includes the scene (model objects displayed, viewing angle, and zoom) and the screen location of the picks.

When replaying a macro / template using saved inputs, the pick gesture is recreated, resulting in the same view, scene, and the saved screen locations (area or single pick). Even if their object ID's are not the same as those during record, object in the same location of the model will be picked. See Running a Template for more information on running templates with recorded inputs.

Limitations on recording

Certain commands and picking options are not yet fully supported for gesture recording and playback. Objects may need to be manually selected during playback if any of the following are done during macro recording:

• Undo/redo

• Pre-selection of objects

• Reverse Selection (from Pick Filters toolbar)

• Picking of contact bodies

• Picking from Model Browser

• Picking from input dialog drop-lists (Object selection fields have a drop-list to the right of the selection field containing candidate objects that satisfy the input filters.)

• Picking using the legacy Pick Dialog. This dialog appears when you right-click in Menu area and select Pick from the list. (The Pick Filters toolbar is supported, except as noted above.)

25Inserting objects in a template

Inserting objects in a template

Inserting

There are several different executable object types that can be placed into a template. Most commonly, a template consists of actions, but it may also contain other SimXpert templates, embedded scripts and embedded templates. In some cases the objects are present on the author’s local machine, and in other cases they may be published templates and actions in SimManager.

The Template Builder toolboxes are used to locate the particular object type to insert in the template. Use Search Tools feature to locate any template, action, or tool that exists in the default search paths of SimXpert.

Once the item has been located and selected, click on the location in the graphics window to place the object.

Arranging

Inserted objects may be moved around using click-and-drag. Multiple objects may be selected using window selection or by holding the Ctrl key. Then click and drag the selection to move multiple objects together.

Deleting

To delete an object, right-click on it and select Delete from context menu. Multiple objects may be deleted by selecting while holding Ctrl key, then right-click on one of the selected items and Delete.

The detailed procedure for inserting each type of object into a template are discussed in the following sections.

Using existing actionsStep 1: To link existing script actions from the action library into the new template, click on the Actions toolbox icon to display the actions stored on the local machine. Action files (file extension *.act) currently on user’s machine in certain default directories will be shown as tools or folders in the Actions toolbox.

Step 2: Select an Action from the toolbox or use Search tool to locate an action.

Inserting objects in a template26

A user-written action may be located outside the default locations, and thus will not be found using Search. In this case, use the Browse... tool in the Actions toolbox to initiate a file browser dialog box. Navigate to the directory where the script action file is stored, and select Open.

Once an action is selected, the mouse pointer temporarily changes to an action icon outline.

Step 3: Drop the action into the graphics window by clicking at the desired location within the new template.

The action icon is now seen at the selected location. It is given the name of the core action, with a sequence number appended. It is a linked action (i.e., an instance of the script action) and as such, there are limitations on which of its properties can be changed.

Hint: • To automatically create a Connection, place the action on top of the preceding action in the template.


See Also:

See Action Library for a listing of built-in actions in SimXpert.

Using a template within a templateAn existing template may be used as a component within another template.

Step 1: Select Templates toolbox to display all the Templates stored in certain default directories. Select a Template from the list.

The Search tool can also be used to locate a template using a text string search. Or use the Browse tool in the Templates toolbox to initiate a file browser dialog box. Navigate to the directory where the template files (*.proc) are stored, and select Open.

Once a Template is selected, the mouse pointer temporarily changes to a template icon.

Step 2: Drop the Template into the builder window by clicking at the desired location within the current template.

Step 3: An instance of the template appears and the template icon is seen at the selected location. This represents a link to the original template. It is given the name of the original template, with a sequence number appended.

This is similar to a linked action. Note that any changes to the original template will result in change to all instances of that template.

Hint: To automatically create a Connection, place the selected template on top of the preceding action in the template.

Inserting objects in a template28

Using embedded templatesThe Embedded Template control creates a new (blank) template within a template. This is similar to an embedded script, but may incorporate additional complexity that is not possible in an action.

When the parent template is saved, by default the embedded template is not saved as a separate file, but instead is wholly contained in the parent template. (However, the option to save the embedded template as a separate file is available in the Properties dialog, Publish page.) An embedded template may not be published to SimManager, except as part of its parent.

Step 1: From Controls toolbox, select Embedded Template to create a new template that will be embedded in the current (parent) template.

Step 2: Click in the graphics window on the task that will precede the embedded template, or anywhere in the window where the new embedded template is desired.

The new embedded (child) template is automatically given a name, such as Process1. A blank template editing window is opened in the graphics area.

Step 3: From this point, the procedure for adding content to the embedded template is identical to that for creating a new template.

Step 4: Open the template Properties dialog box by double-clicking on the embedded template in the Model Browser. From Properties panel, the name, summary, and description may be changed.

It is also possible to create an embedded template using existing objects in the template. See Creating an embedded template from existing actions for details.

Using published objects from SimManagerIf SimManager is configured, published templates and actions may be retrieved and re-used in other templates.

Step 1: Click on the Published toolbox, then Retrieve Template... (or Retrieve Resource...) to connect to SimManager.


Step 2: A logon screen may appear, depending on the configuration. Enter the appropriate user name and password.

Step 3: Navigate to the SimManager Project where the action or template is stored and select it. Click Ok to confirm and close the Object Selection Dialog.

Step 4: Place the copy of the action or template into the current template by clicking at the desired location. This creates a linked action (or template) that is an instance of the published object.

See Retrieving from SimManager for details on the SimManager interface.

Using tools from controls toolboxAdditional template objects may be added from the Controls toolbox. These include tools to add choice (branching), loops, prompts, and file-open dialogs. The Search feature can be used to find the desired tool using a text string match. See Controls toolbox.

Hint: • If you use Refresh tool first, then all available templates and actions will be shown in the Published toolbox and it will not be necessary to use the Object Selection dialog to navigate the SimManager database.

Creating an Action30

Creating an ActionTemplate authors who are comfortable writing Python scripts may wish to create their own actions. These may be embedded in a template or saved as a separate re-usable action file.

Embedded ScriptAdvanced users may wish to create a script that is saved as part of a Template. It will not appear separately as an action in the Action toolbox when saved. An embedded script is written in cases where re-use of the script is not anticipated.

The steps to create an embedded script action are briefly described below.

Step 1: From Controls toolbox, select Embedded Script tool to insert a script into the current template being edited.

Step 2: Click at the desired location in the graphics window to drop the embedded script icon into the current template. It is given a default name, such as “Script01.”

Step 3: Double-click on the script icon to open Properties dialog box. Refer to Action Properties Dialog box, Properties page section for details on filling out this dialog box.

Step 5: Click the Edit button to open an action editing dialog box. Define Inputs and Outputs on the Data tab, and add the Python script on the Code tab. Click Ok to close action editing.

Step 6: The Properties panel will still be open. Save the code from the Publish page of Properties and click Ok to close the window.

See Also:

For full details, see the section in the Actions chapter of this User Guide: Creating Actions, Creating an embedded script.

31Creating an Action

New Script ActionA new script action may be created, which can then be inserted into the current template being edited. The steps to create a new script action are briefly described below. Full details are found in Creating a new script action.

Step 1: From Controls toolbox, select New Script Action.

Step 2: A Create New Action dialog box opens for the new script action. Enter the Label, Name, Type (Python or RADE) and destination directory, then Ok.

Step 3: The Editing panel for the script action is opened automatically. There are three tabs along the bottom. Starting with the Data tab, add new Input parameters using + button. Add Output Parameters in the same way.


Step 4: On the Code tab, click Update to add specified inputs and outputs to code.

Step 5: On the Code tab, add Python or RADE code to the script action.

Step 6: Use the Layout tab to create or import a custom input dialog box.

Step 7: Select the Advanced tab at the bottom of the Action editor to modify the Action Options, add Meta Data, or add detailed documentation.

Step 8: Return to the Data tab to Save and optionally Publish the new script action.

Step 9: Once the new script action is saved or published, it is available to place into a Template as described in Inserting objects in a template, above.

See Also:

For a more detailed explanation of each step, see the section: Creating Actions, Creating a new script action

33Creating an embedded template from existing actions

Creating an embedded template from existing actionsAn embedded template (or “sub-template”) can be created from two or more existing actions in a template. This is usually done to reduce the complexity of the display in a large template.

Step 1: Select the first action in the new embedded template.

Step 2: Holding the Ctrl key, select the last action in the sub-template.

Step 3: Right-click on one of the selected actions and select Create Embedded Template.

Step 4: The selected actions are replaced with an embedded template, which is given a default name, such as Process01.

Step 5: Double-click on the new embedded template to open its Properties panel. From there you can change the name, display icon, etc.

Step 6: Or click on the embedded template name in the Model Browser to edit it, such as adding or removing actions or modifying connections.

Notes:

1) When creating the embedded template, select two actions only: the first and last action. If more than two actions are selected, or if any connections are selected, the Create Embedded Template command will not be available on the context menu.

2) Sub-template creation is not allowed if the first and last actions are on different levels of the template hierarchy. For example, if the first action is before a Choice control and the last action is after the Choice, the embedded template creation will fail and an error message will be shown.

Controls toolbox34

Controls toolboxIn addition to tools for Creating an Action, the Controls toolbox has several tools for establishing template process flow and gathering user inputs.

Template sequence and data flow are established using the Connection tool. Connection tool defines the order of actions in the template. In addition, outputs from one action are assigned as inputs to another with the use of this tool.

From Controls toolbox, interactive features can be added to a Template with the use of the File, Choice, and Prompt tools. These tools provide a template author the means to gather user inputs and choices during template execution. These might include instructions to enter numerical and string data, to supply a data file, or to make a choice between several options.

Iterative portions of templates can be set up using the three Loop tools provided. An action or a group of actions may be specified to repeat until some condition is satisfied.

These tools are covered in turn in each of the following sections.

35Connection tool

Connection toolThe actions in a Template are chained together with the Connection tool. Use it to define both Control Path (sequence of actions) and Data connector (outputs of one action connected to inputs of another).

Step 1: On the Controls toolbox, select Connection.

Step 2: Click on the action to be executed first (source) and the connection icon becomes attached to the mouse pointer.

Step 3: Then click on the subsequent action (destination). An arrow between two actions indicates the connection has been created. A bold blue arrow indicates the control path, and perhaps a data connector as well. A black arrow indicates a data connector only.

A connection icon also is shown in the Model Browser for the template.

Step 4: To open up the property page for a connection right-click on it and select Properties. All available outputs from the previous actions are listed on the left. All inputs for the downstream action are

Connection tool36

shown on the right. Click the dot by an output, on left, then select an input, on right, to make the data connection.

Three check boxes on the upper right allow user to specify the following properties of the Connection:

• Visible - On by default. Un-check to hide a connection.

• Splines - When activated, connections appear as curved lines. When un-checked, connections are displayed as orthogonal lines.

• Control Path - When checked, indicates that the connection is part of the process flow. If un-checked, connection is a data path only. You may check this box if it is desired to make the connection a control path.

The following buttons are found on the right side of the dialog:

• Auto Connect - When pressed, Template Builder attempts to make automatic connections by matching parameter names and/or data types between the left side (prior action’s outputs) and the right side (downstream action’s input parameters).

• Reset - Remove all connections and start over.

37Choice tool

Choice toolThe Choice tool is used to provide user with a choice of actions during template execution and to provide branching in the control path.

Step 1: Select Choice tool in the Controls toolbox.

Step 2: Click on the action that will precede the Choice. The choice action (diamond icon) is placed after the selected action and automatically connected.

Step 3: The choice block should be connected to all possible downstream actions. Create Connections between the choice block and each of the actions representing the choice options. (See Connection tool section.)

Step 4: Open the Properties panel for the Choice action by double-clicking on it in the Model Browser (or right-click in the builder window and select Properties). Type a Name and brief Summary for the choice action in the text boxes, if desired.

Step 5: In the Value column of the table, enter the following items:

prompt - enter the message that will appear to the user.

numOptions - enter the number of choices.

Choice tool38

option1, option2, etc. - type in the name of each option as it will appear to the user.

Step 6: Select options for the choice tool at upper right: Prompt for Inputs, Display, and Execution.

See Action Properties dialog box, Properties page for details on these options.

Step 7: An action should be linked to each choice. Select an option, then go to the Link drop-down list and select the appropriate action for that choice. Repeat for all choice options.

Step 8: Click Ok to apply changes and close the Properties dialog box.

39Simple Loop tool

Simple Loop toolA Simple Loop repeats a portion of a template until a certain integer “count” is reached. The number of iterations is an Input to the simple loop action. It may come from a prior action’s output, or a prompt will be made to input this value.

Step 1: From Controls toolbox, select Simple Loop tool.

Step 2: Click again in the graphics window on the action that precedes the loop. A Connection is made automatically.

Step 3: Then create a Connection between the loop icon and the first action in the loop (loopAction).

Step 4: Make another connection from the Loop to the action that takes place after the loop is completed (breakAction). See Connection tool section for help with connections.

Step 5: Add actions and make connections to form the Loop. Make one more Connection from the last action inside the loop back to the Loop icon. This completes the loop.

Simple Loop tool40

Step 6: Right-click on the Loop icon and select Properties. Enter a Name and Summary at the top of the Properties dialog box.

Step 7: Select options for the loop tool at upper right: Prompt for Inputs, Display, Execution, and Show Connected Inputs. (See Action Properties dialog box, Properties page for details on these options.)

Step 8: Select the breakAction row in the table, then select a Link from the drop-down list to identify the connected action that takes place when the iterations of the loop are finished.

Step 9: Select loopAction in the table and then select an action in the drop-down list that identifies the connected action that is at the start of the loop.

Click Apply to save changes.

Step 10: Go to the Inputs page and double-click in Value field of the input parameter: count to set the default value. (number of times to execute the loop). Check the Hidden box to hide the input and suppress prompting.

Step 11: Click Ok to close the Properties dialog box.

Step 12: Finally check each Connection to be sure the outputs from each action in the loop are being passed to the appropriate inputs of another action. (Right-click on a connection and select Properties.) If the count input comes from a preceding action, make sure to establish the data connector.

41For-Each Loop tool

For-Each Loop toolThe “For-Each” Loop tool is very similar to the Simple Loop. In this case the input to the loop is a List. The loop is repeated for each item in the list. The output of the loop is the current item.

Step 1: From Controls toolbox, select For-Each Loop tool.

Step 2: Follow the same procedure as Simple Loop tool to place the For-Each Loop icon into the template and establish Connections. Add and connect all loop actions.

Step 3: Double-click on the icon to open the Properties dialog box, which is nearly identical to the Simple Loop. Enter a Name and Summary at the top. Select options for the loop tool: Prompt for Inputs, Display, Execution, and Show Connected Inputs.

Step 4: Follow the same procedure as the Simple Loop tool to specify the links for Break Action and Loop Action. Check the parallel box (future capability) to have the loop actions processed simultaneously for each list item. (e.g., to run parallel on different CPU’s)

Step 5: Go to the Inputs page of the Properties dialog box and, if appropriate, set the default values for the input parameter named list. Separate the list items with a semi-colon. (Usually the list will come from a user selection or a prior action.) Check the Hidden box to hide the input and suppress prompting.

Step 6: Click Ok to save and close the Properties dialog box.

For-Each Loop tool42

Step 7: Check all Connections and parameters being passed from one loop action to another. Check that the input list is connected, if coming from a prior action.

43While Loop

While LoopThe “While” Loop tool is very similar to the Simple Loop. In this case, there must be two inputs to the loop. Each time the While Loop is executed, an expression involving a comparison of the two inputs is evaluated. The loop is repeated as long as the expression remains true.

One of the inputs must be modified during the loop such that the expression eventually becomes false. At that time, the template exits the loop and goes to the break action.

Step 1: From Controls toolbox, select While Loop tool.

Step 2: Follow the same procedure as Simple Loop tool to place the loop icon into the template and establish Connections.

Step 3: Double-click on the icon to open the Properties dialog box. The Properties dialog is nearly identical to the Simple Loop. Enter a Name and Summary at the top.

Select options for the loop tool at upper right: Prompt for Inputs, Display, Execution, and Show Connected Inputs:

While Loop44

Step 4: Follow the same procedure as Simple Loop tool to specify the links for breakAction and loopAction.

Step 5: Select an operation for comparing the two input parameters, using an expression of the form operand1 (operation) operand2.

For example, operand1 equals operand2.

Operations include:

• equals

• does not equal

• less than

• greater than

• less than or equal

• greater than or equal.

Step 6: Go to the Inputs page of Properties dialog box and, if appropriate, set the default values for the two input parameters, operand1 and operand2.

For example, both operands might initially be set to “Yes.” Inside the loop, a prompt to user allows for selection of “Yes” or “No.” The operation “operand1 equals operand2” would become false when “No” is selected and the template would exit the loop.


Step 8: Check all Connections, and parameters being passed from one loop action to another. Note that one of the Loop inputs, operand1 or operand2, must be connected from an action inside the loop to the While Loop action.

45File tool

File toolThe File tool allows for prompting user to select a file (or files) to be opened or saved during template execution.

Step 1: From Controls toolbox, select File icon to place a file prompt into the current template.

Step 2: Click in the graphics window at the location where the file prompt is desired to place it into the Template.

Step 3: Double-click on the new FilePrompt action to open Properties page.

Step 4: On Properties page, enter a Name and Summary at the top.

Select options for the loop tool at upper right: Prompt for Inputs, Display, and Execution.

Step 5: In Value column, enter the appropriate values for each Property. For text entries, double-click in the text box to edit.

• prompt - Message given to user during Template execution

• isReadonly - Check the box if the text box is read-only during template execution. User can review, but not change the contents. For example, to force use of file Browse instead of allowing user to type in the file name.

• Mode - Select from these possible modes:

Open - the specified file is to be opened

File tool46

Save - when a file is to be saved to the specified file name.

Open Many - when multiple files are to be selected for opening

Folder - when a directory is to be input

• filter - Enter one or more strings to restrict file name to certain extensions, e.g. “*.xmt.”

Step 6: Select Inputs on left. Double-click in Value text box and enter a default file or folder name, if any.

Step 7: Select Publish at left to review the Publish page. Although the File Prompt action is not normally saved as a separate action when a template is saved, it is possible to save a File Prompt action from the Publish page of Properties panel so that you can quickly create a File prompt with the same options.


47Prompt tool

Prompt toolThe Prompt tool is an action that prompts the user to supply a data string during template execution.

Step 1: Select the Prompt tool from Controls toolbox to add a prompt action to the current template.

Step 2: Click again in the graphics window at the location in the current template where the prompt action is desired.

Step 3: Double-click on the new prompt action to open the Properties dialog box. Enter a Name and Summary at the top.

Select options for the Prompt tool at upper right: Prompt for Inputs, Display, and Execution.

Step 4: Type in the message that will be displayed to the user in the Value field.

Step 5: Select Inputs on the left side. Double-click in the Value text box and enter a default response, if any.

Step 6: Select Publish on the left side. Although the Prompt action is not normally saved as a separate action when a template is saved, it is possible to Save a Prompt action from the Publish page of Properties panel.


Message tool48

Message toolThe Message tool displays a dialog box with a prompting message to the user upon execution and asks user to confirm or reject the displayed message.

Step 1: Select the Message tool from Controls toolbox to add a message action to the current template.

Step 2: Click again in the graphics window at the desired location in the current template.

Step 3: Double-click on the new Message action to open the Properties dialog box.

Step 4: Type in the Name of the message action and a brief Summary in the text boxes.

Step 5: Select msgType in the property table. Click the drop-list arrow and select one of the following message types: Ok, Ok/Cancel, Yes/No, Yes/No/Cancel.

Note: If Cancel is selected by the user, the template execution will be aborted.

Step 6: Select prompt and double-click in Value text box. Enter the message that will be displayed to the user.

Step 7: Select Inputs on left. Double-click in Value text box and enter a default response, if any.

Step 8: Select Publish at left to review Publish page. Although the Message action is not normally saved as a separate action when a template is saved, it is possible to Save a Message action from the Publish page of Properties panel. Click Ok to close the Properties dialog box.

49Template Properties dialog box

Template Properties dialog boxThe Template Properties dialog box is used to display and modify the attributes of the current template. Double-click on a Template in the Model Browser to open the Properties window. Or Right-click and select Properties from context menu. The Properties dialog box has four pages, indicated at the left side of the panel.

PropertiesTo display or edit the general properties of the Template. Note that the Properties panel for an embedded template does not have all the options shown here:

Enter a Label, which will be used to identify the template in the graphics window and bubble tips.

Provide a Name, which is used as the file name. By modifying the Name or Location of an existing template, copying of a template is allowed. (See Publish, below.)

Enter a brief Summary and a detailed Description for the template.

The Version consists of a major version number (e.g. 1.000 vs. 2.000) and a minor version number (e.g. 1.001 vs. 1.002). The minor version number is incremented each time the template is saved. The + button

Template Properties dialog box50

is used to increment the major version number and should only be done when its behavior has changed to make it incompatible with “parent” Templates that may be using it. (This is relevant when the template is nested within another template.)

The default Icon may also be changed here. Click the file browse button to locate an icon for the template.

An option button is present to Hide Actions in a template. This might be done in the case of a sub-template, or when user does not need to see the constituent actions.

Check the box to Show only unused outputs if it is desired to limit Outputs page to display only output parameters that are not connected to inputs.

Check the box to Save current unit system if it is desired to always execute the template in the current unit system. If attempted to execute in a different unit system, the user will be asked to change the units.

Click Apply button to make changes immediately without closing the Properties dialog. Click Ok to save changes and close the dialog. Click Cancel to close the Properties dialog without saving changes.

InputsThe Inputs page shows all inputs for actions that are not yet connected to outputs, i.e. undefined inputs for the entire template. These inputs will be supplied by the user during template execution.

Input parameters are not created in this dialog, but rather in the Action Editing dialog boxes for the individual actions in the template.

Default values for inputs can be specified in the Value column. Double-click in any text box to edit, or in some cases, select from a drop-down list. This is especially important if Input prompting for any of the actions is set to “Use Defaults.” Default values set here, at the template level, will override the default values set in each script action file.


If an Input is connected to a prior Output, or if a Default Value has been specified, you can check the Hidden box to suppress prompting for that input. ‘

OutputsThe Outputs page shows all the outputs of the Template. When “Show only unused Outputs” is selected on the Properties page, only the outputs that are not connected to any inputs of a subsequent action are shown. This page is for review only; no editing is possible. Outputs are defined in the Action editor for each individual action in the template.

Publish

The Publish page of template Properties enables you to Save locally or Publish to SimManager, after designating the file location, user interface, and applicable workspaces. Note that the Publish page for an embedded template does not have all the same options as a stand-alone template.

Location

Set the folder where the Template will be stored.

Filename

The Filename will be automatically generated, based on the Location, above, plus the Name provided on Properties page.

Note: If a real input parameter type is defined with a Unit Value user interface, the action Inputs property page will show the units expected, e.g. 10 (mm). Values are stored internally in MKS (internal model units), rather than user-selected model units.


Workspace

Designate the workspace(s) for which the Template is applicable by clicking the button to the right of the Workspace(s) text box. Make multiple selections if the template can run in more than one workspace.

Create CSV

Click the Create CSV button to create a comma-separated values file that contains all inputs and default values for the template. It enables you to specify multiple sets of inputs for running iterations automatically. See Template Execution, Batch execution of templates for more details. All inputs for the template must be included in the *.csv file (or valid defaults set), as it is not possible to have a mixture of supplied inputs from *.csv and input prompting dialogs. Prior to creating the *.csv file, the prompting for each action should be set to Include with Parent. Otherwise, Template Builder considers all inputs as being resolved internally and no prompting required.


Right-click on the Batch Input Data object in Model Browser to open the *.csv file in a spreadsheet editor.

Create Layout

Click the Create Layout button to create a form for Template inputs. Any existing layouts will be replaced. If a dialog box with a separate tab for each action is desired, place a check in the “Create layout with each Action on a tab” button.

The input layout is saved as part of the template file. Right-click on it in Model Browser to open it in a text editor.

It may be saved as a *.ui file, which you can then edit in Qt Designer (www.trolltech.com) or a text editor. Editing this file will allow for changing the size, shape, and order of text boxes and choices in the template inputs dialog box.

Save

Saves the template to the local file Location. The file name is established from the Name field on the Properties page.


For embedded templates, this causes a copy of the embedded template to be saved as a separate template file, but does not change the status of the current template as embedded. Nor will the newly created template file be linked in any way to the current embedded template.

Publish

Saves the template to a local drive and also to SimManager. The template is then available to other users to retrieve or to run in a managed execution mode. (SimManager can manage the execution of template and results files.)

Publish as Resource

Saves the template to a local drive and also to SimManager. This option is used when author wishes to make the template file available to other users. The template can be retrieved and run locally, but cannot be run using managed execution in SimManager.

See Also:

Refer to Publishing from SimXpert to SimManager in this User’s Guide for more details.

Preview

Click the Preview Button to open a window that displays the template contents in a hierarchical list, similar to the tree view in Model Browser.

55Action Properties dialog box

Action Properties dialog box

Checking Action PropertiesBefore testing a template, the Properties for each object (actions, controls, etc.) should be reviewed and modified as needed. Double-click on a linked action in Model Browser or graphics window to open the Action Properties dialog box. (Or, right-click on the linked action, and select Properties.)

The Properties dialog box opens on the Properties page by default.

The properties that can be edited include: Prompting behavior, Display icon, Execution (optional or automatic), and Default values for inputs. For controls and linked actions, these properties are applied only to the selected instance of the action. The source script file (*.act ) is not affected by any changes made here. For an Embedded script, the changes are immediately applied.

The Properties page for Embedded Script (shown in the image below) is significantly different from the Properties page for a linked action because the embedded script is fully editable. For an Embedded

Hint: To keep open a Properties box at all times that refreshes according to the object selected, go to Tools, Options, Template Builder options. Select Use dynamic window button on General tab.

Action Properties dialog box56

Script, there are four pages in this dialog box: Properties, Inputs, Outputs, and Publish. Each page is accessed by clicking the icons on the left side. .

For Linked Script Action, there are only three sheets in the Properties dialog box. Publish sheet is not present. The Properties sheet is slightly different, and is limited in the items that may be changed..

For a linked action instance there are three pages: Properties, Inputs, and Outputs.

Each page is discussed in the sections that follow.

Properties pageAll displayed fields can be changed from the Properties page for an Embedded script. These include Name, Summary, Script type, Prompt for Inputs mode, Display icon, and Execution mode.


For a linked action, only the Label, Input mode, Display icon, Execution mode, Show Connected Inputs, and Required Version may be modified from Properties page.

Any other changes must be made to the script Action file using the Edit button, which opens the Action editor for the script action. (Built-in MSC actions may not be edited.).

Label

Only present for linked action. A unique label may be assigned to each instance of a script action.

Name

Name of the action (file name). Not editable for linked action. For embedded script the Name field is used as the label since there is not a separate file saved.

Version

Linked action only. Not editable. Shows the version of the core action that was in effect when the template was last saved. See also: Required Version

Summary


Enter a summary of the action. Not editable for linked action.

Prompt for Inputs

Different Prompting behavior may be selected:

• At execution of Parent - select if all undefined inputs are to be gathered at the start of template execution. This might be desirable if the template is to be run in a batch mode.

• At execution of Action - Wait until just before the action is executed to prompt for inputs. A dialog box appears prior to executing the action. This makes the template more interactive, and may be necessary if an input is not available at the start of template execution.

• Never - To skip prompting and use default values. Default values, as specified on the Inputs page of the Action properties dialog box are to be used for input parameters. and no prompting is necessary.

Display

Select the type of icon that will be seen in the Template Builder and Execution windows:

• Icon - to show the assigned icon (graphic symbol) for the action.

• Graphics Snapshot - to display a small SimXpert graphics window. The graphics snapshot window is interactive and the SimXpert display commands (rotate, zoom, etc.) can be used. It may also be re-sized.

• Bitmap Snapshot - a non-interactive re-sizable snapshot of the SimXpert graphics window.

• Block View - For templates and embedded templates only. Displays a small re-sizable SimXpert Template Builder graphics window, with actions and connections shown in block view.

Execution

An action can be made optional at runtime by selecting one of the “manual” execution settings.


• Automatic - The action is always executed. The option to skip the action will not be available at runtime.

• Manual-On - The action will be run by default, but user can toggle the action to skip it during template execution. This can be done prior to template execution, or during a pause in execution.

• Manual-Off- The action will be skipped by default, but user can toggle the action to run it during template execution.

Show Connected Inputs

By default, an input parameter is hidden in the input dialog box during execution if it is connected to an output parameter from a prior action. If, however, you wish to show the input and allow the user to modify it, the Show Connected Inputs checkbox must be checked. (This is only available when Prompt for Inputs is set to “At execution of Action.”)

In the following examples, “input1” and “input2” are connected to outputs from a prior action:

Required Version


For a linked action, this setting allows you to specify the version of the script action to use. If Any is selected, the latest version will be located and used whenever the template is opened for editing or execution.

If a Specific version of the action is selected, the current major version number for the linked action is stored in the template. Whenever the template is opened for editing or execution, the core action is checked to make sure its version number has not been changed. If it has changed, a warning is issued to the user indicating that the action instance is incompatible and should be updated to match the latest version of the core action. See Update, below, and also: Action Data page - Identification

Link

Applicable for certain actions, like Choice, that link possible choices to different actions.

Script Type

For an embedded action, specify the language: Python, RADE, or Existing File.

If Existing File is selected, another line appears in the Property table for scriptFile. Click the file navigation button on the right side of the Value column, and locate the existing file. (Python, RADE, or XML)

Edit

Click Edit to open the Action editor for the embedded script. In the case of a linked action, this opens the Action editing dialog for the script action. Any other instances of the script action are therefore affected by the changes made.

SimXpert built-in actions cannot be edited and the button will be disabled in that case.

Update

Linked action only. Updates the version of the action to the latest. If Required Version is set to a Specific version, that field is also updated to the latest.

Reset

Embedded script only. Resets the Properties page to the default values.


Inputs pageThe Inputs page displays a table of all the input parameters. The Input Name, Type, default Value, and Hidden attribute are shown. Input parameter names and types may be reviewed, but not modified from this page. To modify an input parameter name, type, or to add or delete parameters, click Edit... on Properties page to open the Action editor.

Default Values

The Default input parameter Values for the action instance may be modified on the Action Properties dialog, Inputs page. Note that these are synchronized with any default values set on the Inputs page of the Template Properties dialog box. Values can be changed from either location. Setting input values for the linked action in a template does not affect the default values stored in the source script action (*.act file).

For Real parameters that are associated with a model unit (length, time, mass, etc.), values are shown in the currently selected user units. (e.g., mm, sec, kg, etc.)

Hiding inputs

If a default Value is set for an input parameter, you can then select the Hidden checkbox. This will hide the parameter in the input dialog box during execution of the script. Do this only if you wish to always use the default value specified. In the following example, “input2” is hidden and cannot be changed.


Outputs pageClick Outputs on left side of Properties panel. Outputs may be reviewed, but not modified from this page. To modify outputs, click Edit... on Properties page to open the Action editor.

Publish page Click Publish on left side of Properties panel. (Embedded script only. Not present for Linked actions.)

Normally when a template containing an embedded script is saved, a separate action file is not created. However, from the Publish page of Properties panel, the file location can be set using the Browse icon. Then click Save to create a separate action file.

The new *.act file is a snapshot copy of the embedded script and can be modified and reused in templates, just like any script action. The new action is not linked to the original embedded script, which remains as-is, internal to its parent template.

63Testing a Template

Testing a TemplateSave the template prior to testing. Right-click on a template in the Model Browser tree and select Test to open the Template Execution window.

Execution of the template is managed here. Click Run button to begin execution.

As each action is executed, it is highlighted in Template Execution window. Tree view will show Status of each action.

For best results, it is recommend to open and run a template from the workspace in which it is intended to run. See Running a Template for details.

Context menus64

Context menus

Template context menuRight-click on a Template in the Model Browser or graphics window to access the template context menu.

Create .csv file

Creates a *.csv file containing input parameters and default values. Used to set up Batch execution.

Delete

Removes the selected Template from the Model Browser, but does not delete any files. Any unsaved changes will be discarded.

Properties

Opens the Template Properties dialog box.

Save

Save the current Template to its default file location. Any unsaved actions in the current template are also saved at this time. Note the blue “clock” icon is removed from the template and all of its actions, indicating that it has been saved.

65Context menus

Publish

Initiates a publish dialog with SimManager to publish the template. Also saves to the local directory at the same time. Same as using Publish button in the template Properties dialog box. The published template can be run in managed execution mode when SimManager Enterprise edition is also installed.

Publish as Resource

Same as using Publish as Resource button in template Properties dialog box. The template File is stored in SimManager and can be retrieved by other users for local execution or for insertion into another template. A template published as a resource cannot be run in managed execution mode.

Help

Opens a text window displaying the Template Name, Label, Summary, and Detailed description. The text may not be edited (Go to Template Properties panel to edit), but may be copied. This is the same information that is shown in the Tool Tip for the template.

Context menus66

What’s Wrong

Shown only if the selected template has errors, as indicated with red circle icon. Prints a summary of findings to the Messages window.

Update Report

Checks all action and template instances in the selected template for version compatibility with the latest version. Prints a summary of findings to the Messages window.

Test

Open Template Execution window for running the template.

Expand all / Collapse all

Expands any templates and actions that are currently collapsed. If the selected template is expanded, then it is collapsed down to the template name.

Action context menuRight-click on an action instance in the Templates portion of Model Browser or the graphics window to access the action context menu.

The context menu for user-written actions is different than the menu for SimXpert built-in actions.

67Context menus

Delete

Removes the selected action from the template or Model Browser, but does not delete any files. Any unsaved changes to the action will be discarded.

Multiple items may be selected by holding Ctrl key while selecting. Then right-click on one of the selected items and Delete.

Properties

Opens the Action Properties dialog box.

Save

Saves the selected action.

Publish as Resource

Initiates a connection to SimManager to publish the Action. See Publish an Action from Template Builder for details.

Update

Using Update command resets the input parameter defaults for this instance of the action to the default values saved in the source action (*.act) file. It will also update the Version of the action used and the Required Version (if Specific) to be the latest.

Edit Code...

Opens the Action editor.

Help

For built-in SimXpert actions, it opens a standard SimXpert Help window. For user-written actions, a text window is displayed containing the Action Name, Action Label, Action Summary, Action Details, and a list of input and output parameters and their summaries.

Tool context menuRight-click on an instance of any of the tools from Controls toolbox (File, Prompt, etc.) in the Model Browser or graphics window to access a context menu.

Delete

Removes the selected tool from the template.

Context menus68

Multiple items may be selected by holding Ctrl key while selecting. Then right-click on one of the selected items and Delete.

Properties

Opens the Properties dialog box for the particular tool.

Help

Opens a standard SimXpert Help window.

Workspace Toolbox context menuRight-click in a blank area of the graphics window to access the workspace toolbox context menu. This is a convenient way to access the toolbox from anywhere in the template window. .

69Template Builder Options

Template Builder OptionsTo specify options for the Template Builder workspace, select Tools, Options from the menu bar.

This opens the User Options dialog box. Scroll down to Workspaces and expand Template Builder Options.

The Template Builder Options consist of three pages:

General

On the General options page, you can select defaults and display options:

• Show Action balloon tips - The action and toolbox tips can be enabled or disabled using the check box. When enabled, a balloon containing tips about an item will appear whenever the mouse hovers over the item.

• Input mode for new actions - If Action’s default settings is selected, the prompting behavior for action instances will be the same as defined in the script action file. If Prompt for Inputs is checked, the default behavior for prompting will be to prompt just before each action.

Template Builder Options70

• Version reference for new Actions - Select whether to “Use Latest” (always update to the latest version of actions) or to “Always use the current version,” which was the version when inserted (or later modified).

• Display Settings - Select large or small icon size and graphics window background color.

• Property Window - If Use dynamic window is selected, a floating property editor is displayed that always show the properties of the selected item(s). Otherwise a dedicated dialog will appear only when user double-clicks on an item, or selects Properties from a context menu (right-click).

71Template Builder Options

Connector

The Connector page in Template Builder Options allows you to specify default settings for connectors.

• Visibility - Using drop-list, the organization of connections in the Model Browser may be changed so that connections appear under source, destination, in a separate Connections folder, or hidden altogether.

• Default Connector Style - Spline or orthogonal connector style may be selected.

• Auto-connect Data - The behavior of automatic data connections may be changed. If Match data type is selected, template builder will attempt to make automatic connection if output parameter and input parameter types match. If Match parameter name is selected, automatic connection is made when the parameter names match.

Location

The default path for browsing and storing templates and actions may be specified on Location page. Multiple paths can be created using Add button so that more than one destination can be searched. One must be designated as default by selecting a check box in the Default column.

Action Library72

Action LibrarySimXpert has a library of built-in actions corresponding to commands and tools in the SimXpert user interface. The built-in actions may be used in templates as described above, in Using existing actions. They may not, however, be edited.

Structures workspace tool:

Actions toolbox:

Hint: • During macro record, the “recordable” commands are indicated with a red dot. These recordable commands have a corresponding action in the Actions toolbox.

73Action Library

The following tables may be helpful in locating the action corresponding to a specific SimXpert command or tool. This not a complete list, but provides some examples of where to look in the Actions toolbox. The left side (Level 1, etc.) shows the menu or toolbox navigation to execute the command in the Structures workspace. The right column shows the folder navigation in the Actions toolbox of Template Builder to locate the corresponding action.

File menu:

Level1 Level2 Level3 Actions toolbox navigation

File New AppFrame / File / New

File Open AppFrame/ File/ Open

File Save AppFrame/ File/ Save

File Save As AppFrame/ File/ Save As

File Import SimXpertDatabase, Sofy database, Patran

AppFrame/ File/ Import Database

File Import Import as Parasolid AppFrame/ File/ Import as Parasolid

File Import Parasolid, CATIA, Pro/Engineer, UG NX

AppFrame/ File/ Import Geometry

File Import Nastran AppFrame/ File/ Import Solver

File Import MCF, MWF, MWF-ANSA, MWF-UG

AppFrame / File / Import Connections

File Import SimXpertAssembly AppFrame/ File/ Import Database

File Export Parasolid, Iges Model AppFrame/ File/ Export Geometry

File Export Nastran Multiple AppFrame/ File/ Export Multiple

File Export Nastran Scene AppFrame / File / Export Solver

File Export User Scenes AppFrame / File / Export Solver

File Export MCF AppFrame / File / Export MCF

File Export MWF, MWF-ANSA, MWF-UG

AppFrame / File / Export Connections

File Attach Results Results Entities, Model Data, Both, Detach

Results / ResultFileTools /

File Print AppFrame / Misc / Print

Action Library74

Edit menu:

View menu

Tools menu


Edit Delete AppFrame / Edit / Delete

Edit Visibility Show, Hide, etc. AppFrame / Edit / Set Object Visibility

Edit Move to Current Selection

AppFrame / Edit / Manage Entity Container

Edit Manage Group AppFrame / Edit / Manage Entity Container

Edit Manage SubAssembly

AppFrame / Edit / Manage Entity Container

Edit Properties AppFrame / Edit / Properties

Edit Update Model AppFrame / Edit / Update Model


View Display Fill, Zoom, Pan, Rotate AppFrame/View /Set View

View Render Geom Shaded w/ Edges

AppFrame/View / Render Modes

View Render FE... various AppFrame/View / Render Modes

View Render Edge color, etc. AppFrame/View / Render Modes

View Model Views (various) AppFrame/View / Set Named View

View Custom Views Create AppFrame/View / Add Named View

View Entity Display Geom, Elem’s, etc. AppFrame/View / Entity Display

View Clear Labels AppFrame/ Tools / Clear Labels


Tools Part Rename Duplicates Actions / PartActions/ Rename Dups.

Tools Statistics AppFrame/ Tools

Tools Transform Rotate AppFrame/ Tools

Tools Scene Properties

Combined Mass AppFrame/ Tools / Scene Properties

Tools Options AppFrame/ Tools /Set Options

75Action Library

Geometry tool ribbon / toolbox:

Meshing tool ribbon / toolbox

Quality tool ribbon / toolbox


Coordinate System

Cartesian Actions\LCSActions

Coordinate System

Cylindrical Actions\LCSActions

Coordinate System

Spherical Actions\LCSActions

Curve all tools Actions\GeometryActions

Surface all tools Actions\GeometryActions

MidSurface all tools Actions\MidSurface

Solid all tools Actions\GeometryActions and Actions\SGMActions

Cleanup all tools Actions\GeometryActions


Automesh all tools Actions\MeshActions

FEM based all tools Actions\MeshActions

Features all tools Actions\MeshActions and Actions\BoltModel

Edit all tools Actions\MeshActions

Misc most tools Actions\MeshActions

Misc Control Actions\GeometryActions


Plots all tools Actions\ElementActions

Checks all tools Actions\ElementActions

Edit / Fix Elements

all tools Actions\ElementActions

Action Library76

Nodes / Elements tool ribbon / toolbox

Materials and Properties tool ribbon / toolbox

LBC’s tool ribbon / toolbox


Create Node, SPoint Actions\NodeActions

Modify all tools Actions\NodeActions

Elements all tools Actions\ElementCreateActions or Actions\ElementActions

1D Elements all tools Actions\ElementCreateActions or Actions\ElementActions


Material Modeling/StructMat or Modeling/ThermMat

0D Properties Modeling/StructProp





Constraints all tools Modeling\StructureLBC

Loads all tools Modeling\StructureLBC

Pressure all tools Modeling\StructureLBC

Heat Transfer all tools Modeling\StructureLBC

Initial Conditions

all tools Modeling\StructureLBC

Global all tools Modeling\StructureLBC

LBC Set LBC Set Modeling\StructureLBC

Contact all tools Modeling\StructureLBC

77Action Library

Fields / Tables tool ribbon / toolbox

Results tool ribbon / toolbox

Model Browser context menus (right-click)


Fields all tools Modeling/Tables

Tables all tools Modeling/Fields


Results most tools Results\StatePlotTools

Results Chart Results\Chart Tools


Statistics AppFrame\Tools

Custom Attributes

AppFrame\Edit

Properties AppFrame\Edit

Action Library78

79

Creating Actions

What is an Action?80

What is an Action?An Action is the lowest level building block of a template. It is a black-box entity that performs a specific task from inputs and generates outputs. An Action is typically a script containing code (Python or RADE), and input / output parameter definitions. An action can be user-written or supplied by MSC in the Action library.

Although it is possible for an action to perform a complex task, actions are not interactive. Inputs are collected prior to executing the action and outputs are passed upon completion. Inputs may come from other actions, or may be supplied by the user. Likewise, outputs may be assigned as inputs to another action or may be provided to the user.

81Types of Actions

Types of ActionsThere are different types of actions that can be created and used in Template Builder. The following will help users decide which type is appropriate for each situation.

New Script ActionA New Script Action can be created to add some new functionality that is not already covered by an existing Action. It will be saved as an action file (*.act) and is intended to be re-used. A script action is made available as a tool in the Actions toolbox. Many actions are installed as part of SimXpert and others are user-written. A new script action can be written in Python or RADE or scripting language. Once saved, it can be dropped into any Template. It may be shared across the enterprise by publishing to SimManager.

Linked action instance

When a Script Action is utilized in a Template, an instance of the script action is created in the template. This instance is linked to the original script action and is not editable on its own, although labels and default values of input parameters can be changed.

Embedded ScriptAn embedded script is saved as part of the Template, not as a separate action file. It does not appear separately as an action in the Action toolbox when the Template is saved. An embedded script is used in cases where re-use of the script is not anticipated. It can be written in Python, RADE, or can utilize an existing script file.


Creating an Action

Select the Template Builder workspace

From the entry screen to SimXpert, Click Template Builder from the list of workspaces.M

If SimXpert is already opened in a different workspace, use the Open Workspace icon at upper right, and select Template Builder from the list box.

The Template Builder window presents a list of choices for creating and editing Templates.

For creating an Action, select New..., Script Action. This will create a new *.act file which will be added to the Action library. This new action will be reusable in other templates.

83Creating an Action

From inside Template Builder

Once in the template editing mode, then use Controls toolbox to create a new action:

Embedded Script - To create a script that will be saved as part of the current template. See Creating an embedded script, for details.

New Script Action - To create a new action which will be saved as a separate action file, and will be reusable in other templates. (Same as New..., Script Action, above.) See Creating a new script action, for details.

Once a selection is made, an editing window appears.

Creating a new script action84

Creating a new script actionAdvanced users may wish to create their own customized script actions. Knowledge of scripting in Python language (or RADE) is required for creating scripts.The script consists of input and output definitions in XML format, and script code, such as Python. After creating the new script action, it is saved as a *.act file that will be available to insert into any Template.

Create New Action dialog boxStep 1: From Controls toolbox, select New Script Action tool to create a script action. A Create New Action dialog box appears.

Step 2: Type in a Label which will identify the action in the template builder and execution windows.

Step 3: Enter a unique Name for the new script action, which is the file name for the action when saved. The *.act extension is added by template builder and identifies the file as an action.

Note:

If Name begins with a numeral, an underscore character will be added in front of the name. For example, if Name is entered as “1MyAction,” it becomes “_1MyAction.act” when the file is saved.

Step 4: Select the Type: defaults to Python code.

Step 5: Use Browse icon to navigate to the Location where the new action will be stored. The Filename field is populated automatically, based on Name and Location selections.

Step 6: Click Ok to open the Action editor.

85Creating a linked action

Creating a linked actionA linked action instance is created when an existing script action is used in a template.

Step 1: Select and drop an action from the Actions toolbox, (or Browse on Actions toolbox) into a Template that is currently being edited. (See Using existing actions.)

This creates an instance of the script action which has an integer number appended to the name to identify the instance. (For example, “Force_1”)

A small “shortcut” arrow is seen over the action icon in the graphics window and Model Browser. This identifies the action as linked to another.

Step 2: Double-click on the linked action in the Model Browser tree or flow chart to open the Properties dialog box.

Step 3: Since the linked action is an instance of a script action, only a few properties may be changed. On the Properties page, you can change the label, prompting behavior for inputs, display icon style, and execution mode (auto, manual-on, or manual-off). See Action Properties dialog box.

Step 4: Click Inputs page to set or modify the values of input parameters for this instance of the action.

Creating a linked action86

Step 5: Click Ok to apply changes and close the dialog.

Note:

To open the script action for editing, click the Edit button on the Properties page. This will open the Action editor. (The Edit button is disabled for Actions that are delivered with SimXpert as part of the action library; they may not be edited.) If changes are made to the core script action, all instances of the action in templates can receive the modifications.

87Creating an embedded script

Creating an embedded scriptA template may contain an embedded script, which is saved as part of the Template and will not appear separately as an action in the Actions toolbox when the template is saved. Knowledge of scripting in Python or RADE language is required for creating scripts. The script consists of input and output parameter definitions and script code, such as Python. An embedded script is written in cases where re-use of the script is not anticipated.

Insert Embedded Script into TemplateFrom Controls toolbox, select Embedded Script tool to insert a script into the current Template being edited.

Click at the desired location in the Template Builder window to drop the new script icon into the template.

Define Embedded Script PropertiesOpen the Properties dialog box by double-clicking on script in the Model Browser. The script properties panel opens.

Select Properties page (default) from left side. Provide Name and Summary for the new script action. Select scriptType from drop-list in Value column (Python, RADE, or Existing file.)

By default, when the template containing the embedded script is saved, the embedded script is saved as part of the template and not as a separate file. The option to save the embedded script as a separate action file is available, however, and is found on the Publish page of the Properties panel.

See also: Action Properties dialog box

Creating an embedded script88

Open embedded script editorClick Edit button to open the embedded script editor. (This can also be opened at any time by double-clicking on the embedded script icon in the Template Builder graphics window.) This dialog box consists of a Data page, an Advanced page, and a Code page, selected using the tabs at the lower left corner.

The Embedded Script Editor is a limited version of the Action editor for script actions. Differences include:

• No Layout page

• Identification and Publish sections are not present on Data page. Instead use the Properties panel to change the embedded action’s name, description, and file location. (e.g., double-click on the embedded script icon in the template.)

The Data page is devoted to Parameters. The procedure for creating parameters in the Embedded Script Editor is the same as in the Action Editor. See Action Data page - Parameters for details on creating input and output parameters.

The Advanced page is identical to the Action Editor window. See Action editor - Advanced page for details.

The Code page is identical to the Action Editor window. See Action editor - Code page for details.

89Action editor

Action editorAfter completing the Create New Action dialog box (or anytime the Edit button is selected in Action properties), the Action Editor opens. It occupies the entire Template Builder graphics window.

This editor can be opened at any time by one of the following methods:

• From the entry screen to Template Builder, select Open, Browse... Actions have a file extension of *.act. Navigate to the file and Open.

• Use the File, Open command from the SimXpert menu. A file browse dialog will assist in navigating to the file location. Actions have a file extension of *.act. Select the file and Open.

• Click the Controls toolbox and select Browse... tool. Actions have a file extension of *.act.

• If a template containing an instance of the script action is already open, right-click, Edit.

• If the action has already been edited in the current session, it will appear under the Actions folder in Model Browser tree. Select the action to display the action editor.

Action editor90

The Action Editor consists of four pages which are accessed by selecting a tab at the bottom of the window.

For details, refer to the section on each page:

• Action editor - Data page

• Action editor - Advanced page

• Action editor - Layout page

• Action editor - Code page

91Action editor - Data page

Action editor - Data pageThe Data page of the Action editor can be accessed by selecting the Data tab at the bottom of the page.

It consists of three sections:

• Identification data about the action, such as name, and summary. See Action Data page - Identification

• Publish section, where the local file path for saving the action is defined. The option to Publish a script action to SimManager is also available. See Action Data page - Publish

• Parameters section for adding and removing input & output parameters. The user interfaces for gathering inputs during template execution are also defined here. See Action Data page - Parameters

Portions of the Data page may be hidden when not in use by clicking the double-arrow buttons, as shown.

Action editor - Data page92

Action Data page - IdentificationThe Identification portion of the Data page allows for modifying the name, label, and other information about the action.

Label: Identifies the action in the graphics window and Model Browser. This is populated from the Create New Action dialog box, but may be modified, if desired.

Name: Identifies the file name of the action (*.act extension will be added). This is populated from the Create New Action dialog box, but may be modified, if desired. Modification of the Name field will result in a new action file being created upon Save.

Summary: Add a brief summary of the action. This will be particularly useful if the action is to be published and/or used by others.

Icon: Select a new icon to represent the action in the template builder and execution windows, if desired. Use the Browse icon to navigate to the location of a locally stored image file.

Version: The version will be set to 1.000 for a new script action. Increment the version only if you are modifying an existing action and only when its behavior has changed to make it incompatible with Templates that may be using it. This is done by clicking the + button and will result in a major version number increment (e.g. from 1.000 to 2.000). A dialog will confirm that you wish to increment the version and to enter version comments.


Action Data page - PublishThe Publish section of the Action editor is at the upper right on the Data page.

Location - This box is populated based on the entry in the Create New Action dialog box, when the action was first created, but may be changed at any time. Use the Browse icon to specify a new folder location.

Filename - Based on Location, above, and the Name in the Action Data page - Identification section a complete file path is established, with a *.act extension. This field may not be edited.

Notes: 1) The minor version number will be incremented automatically each time the Action is saved. (e.g. from 1.000 to 1.001)

2) When using a linked action in a template, the version number of the action is stored in the template. This facilitates updating templates when an action is modified.

3) The Label and Summary of the action are part of the Tool Tip help that is displayed when user is browsing actions in Template Builder.


Save - Saves the action to the Location specified. The minor version number will also be incremented (e.g., from 2.001 to 2.002).

Publish as Resource... - Initiates a connection to SimManager to publish the Action. See Publish an Action from Template Builder for details.

Action Data page - ParametersThe Parameters portion of the Data page is used to create and edit inputs and outputs for the action.

There are three possible views for the Parameters section, selected from the View drop-down list at the top of the Parameters section:

Input Table view

The Input Table view presents the input parameters in a simple tabular view. Each row displays an input parameter and its attributes. The following attributes are displayed by column: Name, Label, Type,


Default Value, Required, and Description. See Creating an Input Parameter for details on each attribute shown in the Input Table.

These values can be edited directly by typing in the table fields. Click in any field and begin typing to overwrite the entire contents. Or double-click in a field and place the cursor at the edit point to make changes without overwriting. Or highlight portions of the contents to be replaced.

A new input parameter can be added by clicking the “+” button. A selected parameter can be removed by clicking the “X” button.

Inputs can be reordered using Ctrl+Drag, selecting the sequence number at the left.

Or to move a selected parameter up or down, click on the Move Up or Move Down button.

To specify additional details (such as the user interface, or limiting selections to discrete values or a range) you must switch to the Parameter Details view - Input view, below.

Output Table view

The Output Table view is similar to the Input Table view, but “List” and “Report” attributes are added, whereas “Default Value” and “Required” attributes are not present for outputs. Otherwise refer to Input Table view for details on creating, moving, and editing parameters in the table.

Also see Creating an Output Parameter.


Parameter Details view - Input

When the Parameter Details view is selected, all the details of an input parameter (selected on the left side) are displayed on right side of the page.

For an input parameter this view contains two or three tabs. For details on entering data on the Input, Advanced, and Object tabs, which are summarized below. Please see Creating an Input Parameter for more details.

Input tab:

On the Input tab, you enter the name, type, constraint, user interface, etc. for the input parameter. See Creating an Input Parameter for more information.

Advanced tab:

On the Advanced tab, you can add meta data to the parameter. See Creating an Input Parameter, Advanced tab


Object tab:

This tab is only displayed for parameters of type Object. It allows you to select the allowable sub-types that can be picked from a model during execution, the prompt message displayed to the user, and to establish a minimum and/or maximum number of objects to be picked. You can also set the option to allow the user to create new objects during execution.

Parameter Details view - Output

When an output parameter is selected, the Parameter Details view is displayed as follows:


For details on the entries on this page, please see Creating an Output Parameter.

99Creating an Input Parameter

Creating an Input ParameterAn input parameter is created on the Data tab of the Action editing window.

The following instructions are shown in the Parameter Details view. Please note that some, but not all, of the described steps can also be done in the Input Table view.

Step 1: To create an Input parameter, click the green “+” button in the Parameters section of the Data page. Or select the arrow next to the “+” and select Add Input from the drop-down list.

When a parameter is added it is given a default Name, for example: “input1” and a default type of “String” and you will see it in the parameter list.

Step 2: Click on any parameter to specify its attributes. A form will appear for defining the parameter. The form has tabs at the top: Input, Advanced, and (sometimes) Object. First select the Input tab.

Input tab

Identification

Step 3: In the Identification section, enter a Label which is the display label that will appear in the user interface when the action is run.

Creating an Input Parameter100

Step 4: Enter the parameter’s Name. This will be the name used in the action’s Python code to refer to this parameter.

Step 5: Enter the parameter’s Summary. This is a brief description of the parameter and becomes part of the Tool Tip help that is displayed to users when selecting the action in Template Builder, so it is important to properly describe each parameter.

Behavior

Step 6: In the Behavior section select the Optional button only if the parameter is not always required. (By default the Required option is selected.)

Step 7: Select a different “Reset on Apply” behavior, as applicable. (for resetting action input defaults upon clicking the Apply button in Action Properties panel.) The possible values are:

• Default: Inherit the behavior from the Action. If the Action has ResetOnApply set to “Reset value to original default value” then the Parameter will be reset on Apply and not stored. If the Action has ResetOnApply set to “Store previously used values” (default), then the Parameter will not be reset on Apply and will be stored for later use. This is the default behavior when the meta data is missing on most Parameters.

• Always: The Parameter will always be reset when Apply is clicked and never stored for later use. Overrides the Action-level setting.

• Never: The Parameter will not be reset when Apply is clicked and will be stored for later use (subject to the Object/Point rule above). Overrides the Action-level setting.

Note:

The reset behavior for an action and its parameters described above is only utilized when the action is run as a tool (on tool ribbon). When run in a template, the defaults set at the template level will be applied. However stored values from a previous template execution can be run by loading a saved execution file or importing input values.


Also see Action editor - Advanced page for selecting the Reset behavior at the Action level.

Definition

Step 8: In the Definition section, select the Type of parameter from the drop-down list. All the valid parameter types are shown in the image below.

Step 9: Enter a Default value in the text box, as applicable.

Step 10: Check the List box if the parameter is a list of values or objects.

Step 11: If the Type is Object, Point, Managed Object, CAD Object, or Enterprise Object, these have sub-types, therefore you should also select the Object type.


Constraint

Step 12: In the Constraint section of the form, a Constraint can be added to restrict the input to a Range or Discrete values. By default there is no constraint on the input values, aside from being consistent with the parameter type.

If a Range constraint is selected, then a lower and upper bound need to be entered.

For a Discrete constraint, you must specify all possible valid Options for the parameter. Use plus (+) button to add valid options to the discrete options list. Enter a value in the Option column for each. To remove an option, select it from the list, and click the “X” button.

The Discrete constraint can also be used when creating a “parent” input parameter for the purpose of creating input Groups. (See also: Group)

Interface

Step 13: Pick an Interface for the parameter from the list box at the bottom of the Parameter Details window. The user interface options vary according to parameter type. These built-in user Interface choices allow you to provide the appropriate interface for each input parameter.


For example, if parameter type is String with a File Chooser interface, it will automatically present the user with a file browse dialog box during template execution.

With Discrete constraint, choose a User Interface of List, Drop List or Radio Group. For a Range constraint, Spinner and Slider interfaces are available.

Step 14: Select the Properties for the chosen User Interface from the table to the right of the user interface list box. The properties vary according to the parameter type and user interface selected.

For example, with parameter type of String, and user interface of File Chooser, one of the available Properties is a filter, which is used to limit a file selection to only certain file extensions.

Review the section on Parameter Interface for details.

Note: Steps 1-6, and 8-9 can be done in the Input Table view, shown below, but the remaining steps must be done in the Parameter Details view - Input.

Advanced tabStep 15: Optionally, select the Advanced tab, as appropriate, for the new Input parameter.

If you have entered a value for the “group” Property in the Interface section on the Input tab, it will appear in the Meta Data table automatically. (See Group.)

In case a desired attribute is not present in the defaults on the Input tab, you can add more Name - Value pairs in the Meta Data table by clicking the “+” button. Type in the Name and Value into the table.


Object tabStep 16: Optionally, select the Object tab, as appropriate. It is only visible when an Input Parameter’s type is Object or Point.

Allowable Pick Types

Step 17: If an Object Type was selected in Step 11, it will be pre-selected. To allow multiple Object types, check the box for each valid object type in the Allowable Pick Types table.

A second check box will appear to the left of each checked box. Check the left box if you wish picking of that object type to be activated by default during execution.

Click Allow All button to activate all Object types and place checks in each selection box.

Click Clear button to clear all check boxes and start over. Then re-select the allowable pick types.


Message

Step 18: Type in the prompt message that the user sees when picking this parameter during template execution.

Sub-filter

Step 19: If picking is to be restricted to a sub-type of the allowable pick type, enter the sub-type in the Sub-filter box.

Enable Contiguous pick mode

Step 20: If applicable, check the box for Enable Contiguous Pick mode, which will automatically turn on contiguous picking for this parameter during action execution. This is useful for selecting adjacent objects in a region or along an edge. For example, selecting all the nodes around a hole by picking only one node.

Multi-Object Picking

Step 21: Check the Multiple-Entity Picking box, as applicable, to specify the number of objects that may be picked. Use the spin boxes to set the “Minimum entities required” and “Maximum entities required.”

Allow user to create new objects

Step 22: Check the “Allow user to create new objects” box if an action or template exists to create the new object. Use the file Browse icon to locate the action (*.act) or template (*.proc) file in which the new object is defined.

Creating an Output Parameter106

Creating an Output ParameterAn output parameter is created on the Data tab of the Action editing window.

It can be done in either the Parameter Details view or the Output Table view. The following instructions are shown in the Parameter Details view, unless otherwise noted.

Step 1: When the Parameter Details view is selected, select the arrow next to the “+” and select Add output from the drop-down list.

When the Output Table view is selected you only need to click the“+” button.

An output parameter of type “String” is created and given a default name, such as “output1.” It is added to the parameters in the table.

Identification

Step 2: Select the new output parameter in the table on the left side to view the details for the parameter.

Step 3: In the Identification section, enter a Label which is the display label that will appear in the Execution summary report when the action is run.

Step 4: Enter the parameter’s Name. This will be the name used in the action’s Python code to refer to this parameter.

Step 5: Enter the parameter’s Summary. This is a brief description of the parameter and becomes part of the Tool Tip help that is displayed to users when selecting the action in Template Builder.

107Creating an Output Parameter

Behavior

Step 6: In the Behavior section, check the “Save and Report” box if the output parameter is to be written to the Execution summary report.

Definition

Step 7: In the Definition section, select the Type of parameter from the drop-down list.

Step 8: In Select “true” for the List attribute, if the output is a list of values or objects.

Step 9: If the Type is Object, Point, Managed Object, CAD Object, or Enterprise Object, these have sub-types, therefore you should also select the Object type.

Creating an Output Parameter108

Steps 1-8 can be done in the Output Table view. (Summary is shown as “Description” in this view.)

109Parameter Interface

Parameter InterfaceInterface choices allow you to provide a custom user interface for each Input parameter. When an action is executed as part of a template, the Interface defined by the template author is presented to the user for gathering input parameters.

The following sections briefly describe the Interfaces available for each parameter type. The user interface is specified on the Data page of the Action editor. The Parameter Details view - Input must be selected.

Selecting an InterfaceClick on a Parameter in the table on the left side, then select an Interface for that parameter at the bottom of the page. Once a user Interface is chosen, each interface has different Properties that may be set. These properties are listed on the right side of Interface section.

Common Interface Properties

List

A List property is shown for most user interfaces, and is selected when the parameter is a list of values or objects. When the action is using Python code, checking the List box will result in creation of a native Python list. (When using RADE, you will get the SimXpert API object list functions.) To force use of SimXpert API object list functions, this can be done on the Advanced tab at the bottom of the dialog. See Action editor - Advanced page.)

Parameter Interface110

Note that the List option is the same as found in the Definition section of the parameter details.

isReadOnly

Another common property, “isReadOnly”, is selected when the input selection cannot be edited, for example a file name.

Group

The “group” property is used to identify a parameter as being part of a group or to create a tabbed interface.

Use the following format: “parent:GroupName” where “parent” is the Name of the parent parameter, and “GroupName” corresponds with a discrete value of the parent parameter. This is used when some input parameters and their user interfaces depend on the choice made for another parameter (the parent parameter). The parent parameter must have the Discrete constraint selected. (See Constraint in “Creating an Input Parameter.”)

For example let’s say we have “type:RGB” as the value for the “group” property. In the following image, selection of “RGB” for the parameter “type” results in a different user interface than when “Color” is selected. The parameters R, G, and B are only shown when the parameter Type is set to “RGB.”


To group parameters under a tab, use the keyword: tab for the group property, in the following format: “tab:Name” where the Name corresponds with a group of input parameters to be displayed in a tab labelled “Name.” Use the same value of the group property for several parameters in order to collect related parameters under the same tab. In the above example the two tabs “Named” and “Web” were created in this way.

In another variation of using groups, the parent parameter can have its group property set to a tab. In the example below, the parameter “Type” is using a Radio Group user interface and its group property is set as: “tab:custom”

Other Properties are specific to the interface and are mentioned in the following sections for each parameter type and user interface.

String ParameterA string parameter is used when an alpha-numeric value is expected. It may be Unconstrained, or may be constrained to Discrete values.


Several different User Interface choices are available for a string parameter. The Interfaces for an Unconstrained String parameter are shown:

The choices are different if a Constraint is selected. Expand each type, below, for a description and example of each user interface.

Hidden

Use if an interface is not visible to the user, such as when a default value is to be used during execution.

Line Edit

This is the default interface for an unconstrained String. A dialog box is presented to user with a text box for entering the parameter value.

Properties that can be set for a Line Edit user interface include the typical List and IsReadOnly options. Another property that can be set is alignment. This property defines the justification of the typed value within the text box, with settings of AlignLeft, AlignHCenter, and AlignRight. For example the AlignLeft and AlignRight settings are shown below:

Text Editor


Opens a larger text edit box for entering the string parameter. Used when a long string is expected.

Color Chooser

Opens a chart with color samples from which to select a color.\

Line Style / Line Weight

Graphical chooser for line style and thickness.

Symbol Chooser


Presents a list of symbols for selection.

Font Chooser

Presents a dialog box with available fonts, styles and sizes for formatting text.

File Chooser

Opens a file selection dialog box. In addition to the List and ReadOnly properties, there is also a Mode (Open or Save) property and a Filter property. Use the filter to limit valid file extensions.

Folder Chooser

Opens a folder selection dialog box. Used to specify a storage location, for instance. Similar to File Chooser.

Date Chooser


Opens a date chooser dialog. Used to select an input or output parameter that contains a date. Date may be typed in, or scrolling arrows can be used to increase / decrease value for month, day, and year separately.

Time Chooser

Opens a time chooser dialog. Used to select an input or output parameter that contains a time.

Date & Time Chooser

Opens a dialog containing Date Chooser (above), and Time Chooser (above). Used to select an input parameter that contains a date and time.

Drop List

This Interface is only available when Constraint is set to Discrete and is the default interface for discrete constraint. The user clicks the down arrow to display a list of choices.

List

This Interface is only available when Constraint is set to Discrete. Valid Options are presented to the user in a list.

Radio Group


This Interface is only available when Constraint is set to Discrete. Valid Options are presented to the user in a group of option buttons.

Integer ParameterAn Integer parameter is used when a whole number value is expected. An integer parameter may be Unconstrained, or may be constrained to Discrete values or a Range of values.

User Interface choices for an integer parameter are fewer than a string parameter. Expand each type, below, for a description and example of each user interface.

Hidden

Use if interface is not visible to user, such as when default value is to be used during execution.

Line Edit

Default for an unconstrained Integer. A dialog box is presented to user with a text box for entering the integer value.

See String Parameter for additional details.

Drop List

This user interface is only available when Constraint is set to Discrete, and is the default. Valid Options are presented to the user in a drop-down list, as shown in String Parameter.

List

This user interface is only available when Constraint is set to Discrete. Valid Options are presented to the user in a list, as shown in String Parameter.

Spinner


This user interface is only available when Constraint is set to Range. A spin box is presented to the user with up and down arrows to increase or decrease the value. The user may also type in a value.

Properties for a Spinner user interface include the typical List option, and a Step property, which defines the increment for the up/down arrows.

Slider

This user interface is only available when Constraint is set to Range. A slider appears with minimum value at the left and maximum value on the right, corresponding to the upper and lower bounds specified in the Constraint. The current value is shown to the right of the slider.

A Step property, which defines the increment for the slider tick marks can be specified.

Real ParameterA real parameter may be Unconstrained, or may be constrained to Discrete values or a Range of values.

The Interface options for Real parameters are similar to those for integers.

Hidden

Select if interface is not visible to user, such as when default value is to be used during execution.

Line Edit

Default for real, unconstrained parameter. A dialog box is presented to user with a text box for entering parameter. See String Parameter, above.

Unit Value


Use when the real parameter is associated with a particular unit, such as length, mass, time, etc. A dialog box is presented to user with a text box for entering the parameter, and the appropriate unit (in the current model units) is shown.

Set the unit type in the Property section, selecting from the list of available unit Types (Mass, Time, Length, etc.). The specific unit shown depends on the current user units selected (in Tools, Options, Units Manager.)

Measured Value

Allows you to measure a distance or angle from the model during execution. The input value is set equal to the measurement.

Spinner / Slider

These user interfaces are only available when Constraint is set to Range. Same as described in Integer Parameter, above.

Drop List / List

These user interfaces are only available when Constraint is set to Discrete. Same as described in String Parameter, above.

Boolean ParameterSince only two choices are possible (true or false), user interface choices are similar to other parameter types with Discrete constraint.

Hidden

Use if interface is not visible to user, such as when default value is to be used during execution.

Check Box


Default user interface for boolean type. True / False option is presented to the user in a check box, using the label defined in parameter table.

Radio Group

True / False options are presented as option buttons.

Drop List / List

These user interfaces are same as shown in String Parameter. A true/ false option is presented in a drop list or list.

Enumeration ParameterWhen a parameter is assigned the type Enumeration, the Constraint is set to Discrete and cannot be changed. Valid enumeration Options must then be specified.

User interface choices are as follows:

Hidden

Use if the Interface is not visible to user, such as when default value is to be used during execution.

Drop List / List

These user interfaces are same as described in String Parameter.

Radio Group

Valid options are presented to the user in a group of option buttons, as described in String Parameter.

Object parameterAn object parameter is used when a model object, such as Part, Node, or Element is used as input or output parameter. Object input parameters do not have a constraint option and can only be Unconstrained. Two user interfaces are available for an object input parameter:

Hidden

Hidden user interface is selected when user selection of object(s) is not desired during execution, such as when object is passed from a prior action.


Object Picker

The Object Picker user interface initiates a Pick dialog during template execution. Selected objects are displayed in a Line Edit text box.

Properties of the Object Picker user interface include the typical List, Group, and isReadOnly options. See Common Interface Properties.

Point ParameterA parameter type of Point is a special type of Object, and has similar user interface options.

Hidden

Hidden user interface is selected when user selection of point(s) is not desired during execution, such as when point is passed from a prior action.

Point Picker

Point Picker user interface is a limited version of the Object Picker. Properties of the Point Picker user interface include the typical List, Group, and isReadOnly options.

Managed ObjectA Managed Object parameter type is an object within a “managed” SimXpert file, that is stored in SimManager.

The User Interface for a Managed Object is predefined and thus is not selectable. You only have the option to select a Hidden interface.

Hidden

Hidden user interface is selected when user selection of the Managed Object(s) is not desired during execution, such as when the object is passed from a prior action.

The Hidden interface include the typical List and Group Properties.

CAD ObjectA CAD Object parameter type is a special object type that is limited to CAD geometry objects in SimDesigner, CATIA, or Pro-E files.

The User Interface for a CAD Object is predefined and thus is not selectable. You only have the option to select a Hidden interface. See Managed Object, above.


Enterprise ObjectAn Enterprise Object parameter type is a special object type that is limited to objects found in a SimManager database.

The User Interface for an Enterprise Object is predefined and thus is not selectable. You only have the option to select a Hidden interface. See Managed Object, above. To execute an action that has an Enterprise Object input parameter, a SimManager connection is required.

Action editor - Advanced page122

Action editor - Advanced pageSelect the Advanced tab at the bottom of the Action editor to modify the Action Options, add Meta Data, or add detailed documentation.

Meta DataThe Meta Data table allows you to change action options or add meta-data that is not included in the default properties of an action. If any of the options on the Action Options area of the page are changed to a non-default state, they will be shown in the Meta Data table. The table is displayed in alphabetical order by meta data Name.

A list of pre-defined meta-data is accessed using the double-left arrow button. Select a Name from the drop-down list to add it to the Meta Data table. You may need to enter a Value in the table.

• Author Information - add Author, Created date and Modified date to the table.

• Descriptive Label - adds a descriptive label to the Meta Data table.

• IsModifyingGeometry - Identifies the Action as modifying geometry.

• Shutdown History - Purges the undo history before execution of the Action

123Action editor - Advanced page

• Turn Off History - Disables undo history for this Action.

You can create additional Meta Data by clicking the “+” button, and populating the Name and Value columns accordingly. To remove meta data, select a row in the table and click the “X” button. Removal of a non-default

Action OptionsThe Action Options area of the Advanced page lists several options, which are initially populated with defaults. Changing any of the options to a non-default state will result in the option being listed in the Meta Data table.

The available options are as follows:

• Allow dynamic inputs - Turns on and off dynamic inputs. When on, allows simple undefined inputs to be set at run time. (Outputs from other actions can be connected arbitrarily to the Action.) The implementation must handle the getting and setting of the extra inputs.

• AutoExecute - When on, the action will automatically execute when preselection satisfies all inputs.

• Reset on Apply - Controls ability to re-use the action’s inputs or to reset to default values. (Note: only for actions executed as a tool (on tool ribbon); when executed in a template, the template default values are used.)

Action editor - Advanced page124

This option can be set at the individual parameter level if desired. (on Data page) It has two possible values:

• False: Store previously used values - This is the default if the meta data is absent. The Action's parameters are unchanged by the framework when the Apply button is clicked AND the Action's inputs will be saved and used again the next time. Note: Object and Point input parameters are never stored for later use, except polymorphic object inputs that currently have a numeric value.

• True: Reset values to the original default values --The Action's parameters will be reset to the default values when the Apply button is clicked and the Action's inputs will NOT be saved. Group input parameters are not reset.

• Macro Recording - specifies how to handle multiple sequential instances of an action during macro recording:

• Unique instance for each execution - to keep sequential instances of this Action as separate instances when recorded in a macro.

• Aggregate sequential executions into a single instance - combine sequential instances of this Action to one when recorded in a macro.

• Recording Pick Gestures - specifies whether or not to record the view and screen location of picks:

• Record Pick Gesture data in a macro

• Record object ids - requires valid id’s for playback

• List Variables - Specifies how list variables are to be handles.

• Use native python lists (default) - List variables will be created as native Python lists

• Use SimXpert Object Lists - Uses the various XXXList classes from the SimXpert API. (e.g., NodeList, ElementList, etc.) May provide better performance for very large lists.

• Units (Python only) - Controls the use of system units or user units for dimensioned values:

• Use system units for dimensioned input values

• Use current session units for dimensioned input values

125Action editor - Advanced page

DocumentationDisplays the action’s Summary, which is populated based on Data page entries.

If changed here on Advanced page, the modified Summary will be shown on the Data page as well. In addition, a Description box is available here to add details about the action.

Action editor - Layout page126

Action editor - Layout pageSelect the Layout tab at bottom of the Action editor.

The Layout page allows you to customize the appearance of the User Interface for each parameter. It also provides for you to add documentation and meta-data to the action. It is organized into five sections: Layout, Preview, Documentation, Meta Data, and Categories.

Layout

The Layout section allows you to specify features of the user interface.

Embedded - Check box to create the layout as part of the action (*.act) file instead of a separate file. Un-check box to save as a *.ui file for further editing in Qt Designer or text editor, if desired.

Create - Click Create button to create a custom form for Template inputs. It is saved as a *.ui file for further editing in Qt Designer or text editor, if desired.

Add... - Add a layout file to the list, using a file browse dialog box.

Remove - Select a layout from the list and click the Remove button to delete it from the list.

Preview - Select to Preview the saved layout. Close when finished with preview.

127Action editor - Layout page

Edit... - Opens a text editor or other program associated with the *.ui file. Knowledge of the xml formatting codes is needed.

Import... - Import a layout file to the list, using a file browse dialog box.

Preview

This area of the Layout page shows a preview of how the action input dialog will appear to the user upon execution.

Action editor - Code page128

Action editor - Code page

Entering CodeKnowledge of Python or RADE scripting is needed to create code. See Python Scripting Language and RADE Scripting Language for details on each code and syntax.

Step 1: It is recommended to complete the Data page first, including Input and Output parameters. Then select the Code tab at bottom of Action Properties dialog box.

Step 2: Click Update button to automatically add the input and output parameter statements to the script editor window.

The auto-generated code in Python looks as follows, with parameters and other declarations at the top and output parameter calls at the bottom:

# # CODE FENCE BEGIN: Declarationsimport RIDLRIDL.loadModule("rgen_ridl")

context = SX.ScriptDelegate.current()if (not context): SX.showErrorMsg("The script must be executed in a Process.") raise "Error"inputs = context.getInputs()outputs = context.getOutputs()NumBolts = int(inputs.getInt("NumBolts")) # () Number of BoltsAttachLocs = SX.ActionUtilities.getObject(inputs.getString("AttachLocs"), "")AttStyle = inputs.getString("AttStyle") # () Style of AttachmentMass = inputs.getDouble("Mass") # () Mass of accessoryCG_Loc = SX.ActionUtilities.getObject(inputs.getString("CG_Loc"), "")# # CODE FENCE END Declarations

# Enter your code here

# # CODE FENCE BEGIN: Outputs# # CODE FENCE END Outputs

Step 3: Notice the “Enter your code here” comment. This is where your python code is placed. Type or copy / paste directly onto the Code page.

129Action editor - Code page

Or click Edit button to open Script Editor.

Begin adding script code into the window.

Step 4: Type or copy / paste the code (e.g. Python) into the script editor window, just after the line:

# # CODE FENCE END: Declarations

and before the statement:

# # CODE FENCE BEGIN: Outputs

Use the editing toolbars as needed: Cut / Copy / Paste, Un-do and Re-do. (Note: The script type cannot be changed, as this was set when action was first created.)

Step 5: Click Save icon at upper left to Save the code. Close the Script Editor window.

If Script Editor was not used, save the action by right-clicking on it in Model Browser and Save.

Testing an actionScript Actions must be tested as part of a template.

Action editor - Code page130

Insert the action into a template and make any necessary connections. Right-click on a template in Model Browser and select Test.

The Template Execution window is opened. See Running a Template for details.

131Editing an existing Action

Editing an existing Action

Template Builder entry screenWhen Template Builder is opened, the editing window has a list of options.

To open an existing action, look under Open... to locate the desired action. Recently used actions may appear in the Open menu. Hovering the mouse over each icon will bring up the file name. Actions have a file extension of *.act. If the action is not seen on the list, use Browse... command to locate the action file.

Editing in Template Builder

Embedded Script

In Template Builder, open the template containing the embedded script action. (File, Open). The selected template opens in Template Builder and is seen in the graphics window and Model Browser.

• Locate the script to be edited in the graphics window or Model Browser, and double-click on the script icon to open the Properties dialog box for the embedded script. From there, click Edit... to open the Action editor.

• Or, right-click the embedded script action icon in Model Browser and select Edit... from the context menu.

Script Actions

Editing is disabled for certain built-in actions that are packaged with SimXpert. User-written actions may be edited. There are several ways to open an action for editing:

• Script actions may be opened from the entry screen to Template Builder: Open, Browse... Actions have a file extension of *.act. Navigate to the file and Open.

• If a template containing an instance of the script action is already open, double-clicking on any instance of the script action in a template will open the Properties dialog box for the script action. From there, click Edit... to open the Action editor.

Editing an existing Action132

• Use the File, Open command from the SimXpert menu to locate the script action. A file browse dialog will assist in navigating to the file location. Actions have a file extension of *.act. Select the file and Open.

• Click the Controls toolbox and select Browse... tool. Actions have a file extension of *.act. Navigate to the file and Open.

• Click on an action in the Actions folder of Model Browser tree to open the Action editor (available only if action has been opened in the current session.)

The editing dialog panel opens up in the graphics window. There are three tabs across the bottom. Make the desired changes to Data, Layout, or Code pages. Use the procedure described in Action editor section to modify the action. Make sure to Save the action when complete. (from Data tab)

A copy of a script action can be made by opening it for editing then giving it a different Name. To avoid confusion, it should be given a new Label also. Click Ok to save under the new name.

Details on editing script actions are found in the Action editor section of this User’s Guide.

Caution: Note that if any script action is modified, all instances of the action will also receive the modifications. Make sure this is intended before modifying any script actions.

133Converting a script to an action

Converting a script to an actionA Python or RADE script can be converted to a SimXpert Action. Python scripts typically have a file extension of *.py.

Use existing script file as an embedded scriptStep 1: Open the template for editing that will contain the embedded script.

Step 2: Select Controls toolbox, then Embedded Script.

Step 3: Double-click the embedded script icon to open Properties. Select scriptType as Existing File.

Step 4: Another line appears in the Property table for scriptFile. Click the file navigation button on the right side of the Value column, and navigate to the existing file. Valid file types are *.py, *.rdl, and *.xml

Step 5: Go to Publish page and Save.

Create an action by modifying existing scriptThis is preferred because it takes advantage of the new features of the Template Builder workspace, including the new input user interfaces and data connections from one action to another.

Step 1: Open the existing script in a the Script Editor and keep the window open.

Step 2: Create a new Embedded Script or a New Script Action. Open Properties panel. Enter the file Name and Label for the action.

Step 3: Examine the code in the text editor window and identify the input variable names that you wish to be supplied by the user or connected from a prior action. (In RADE, these may use OH / VH statements).

Step 4: Go to Data tab of Properties dialog and select Input Parameters from drop-list. Click Plus (+) to add Inputs that match name and type of the inputs identified in Step 3.

Step 5: Repeat for Outputs.

Step 6: Select the Code tab at bottom, and click Update button to add “Code Fence” sections for Inputs and Outputs.

Step 7: Click Edit button. Copy / Paste the RADE code from another window into the Script editor after the Code Fence (input) statements.

Step 8: Delete extra parameter initializing statements, if existing. Delete OH / VH sections, which have been replaced by User Interface definitions.

Using Script Editor134

Using Script Editor

Script Editor windowThe Script Editor tool is available in SimXpert for convenience of editing and running Python (*.py) and RADE (*.rdl) scripts. To open Script Editor in any SimXpert workspace, click Tools menu, then Macro, and Script Editor.

In addition to the menus and toolbars at the top of the window, the Script Editor window consists of three regions:

1. Directory tree view - It shows the list of files in the selected directory and selected filter. Select File > Open Directory Tree to show this. Right-click in the tree to access context menu & set filter.

2. Script Edit window - By default only this Script Edit window is shown initially. Each opened file is displayed on a tab at the top. Select a tab to view and edit the contents of the file.

3. Debug Windows - Tabs to view and query information from the Python debugger. The Debug windows are hidden by default but can be shown by right-clicking in the menu bar and selecting Debug Windows. Not available for RADE scripts. See also: Debug windows.

1

3

2

135Using Script Editor

Right-click on an object or region of the Script Editor window to show a context menu. The menu will vary according to the object selected.

Script edit window context menu:

Directory tree context menu:

Script Editor Menus and Toolbars

File menu

The Script Editor has a set of file management and editing tools for scripts. The File menu has typical New, Open, Close, Save and Save As commands for managing your script files. (*.py and *.rdl)

In addition, the Open Directory Tree command opens the Directory Tree view at the left side of the window.


Publish and Retrieve commands are also seen on the File menu for RADE scripts only and are used to publish a script to SimManager or to retrieve an existing script from SimManager.

Edit menu

The Edit menu has Cut / Copy / Paste, as well as Un-do and Re-do commands for editing script text in the script edit window. You can increase or decrease the font size and turn on / off the line numbers. You can also create and find Bookmarks in the script.

For RADE scripts only, there is an Inputs and Outputs... command on the Edit menu to create parameters.


Select Inputs or Outputs tab, then click New to create a new parameter.

Specify the Input name, Data Type, Object Type (if applicable), and Description. (Note that once the Inputs and Outputs command has been used to create parameters, it is assumed that the script is an action and can then only be executed as part of a template.)

Debug menu

The Python Debugger commands can be accessed from the Debug menu in Script Editor.

These are discussed in Using the Python Debugger


Toolbars

The toolbars contain icons for quick access to script editing tools. Move the mouse over each icon to get a popup description of each.

Toolbars and the Debug Window may be hidden / shown by right-clicking in the toolbar area to bring up the toolbar context menu and checking the toolbars you wish to show:

The “Tools” toolbar has the most common commands from the File and Edit menus, and an additional icon to Run a script. Publish, Retrieve are visible on this toolbar only when Code type is Rade.

The “Debug Tools” toolbar contains several commands related to the Python debugger tool. These are discussed in Using the Python Debugger .

The “Language” toolbar consists of a drop-down list to select the scripting language. This is done for new files before adding script.

Using the Python DebuggerThe Script Editor window has a built-in Python debugger, which is available only when the language selected is Python. The debugger allows you to set breakpoints, pause, continue, step into functions, and to monitor the value of variables during execution.

The Debugger and Script Editor can also be invoked from the Template Execution window for user-written actions. Use the “Step Into” control button to activate the Debugger. See Template Execution Control buttons, in this guide.


Debug commands

Use the Debug menu or the Toolbars in Script Editor to access the following debugger commands. Initially only the “Start Debugging” and “Toggle Breakpoint” commands are enabled. Once debugging is started the rest of the commands become available:

- Start Debugging - Only visible when the debugger is not running. Start executing the script in debug mode. The execution will continue to the end or until it encounters any breakpoint.

- Stop Debugging - Only visible when the debugger is running. Stop the debugging and further execution.

- Restart - Stop the debugging and restart from beginning the same script.

- Toggle Breakpoint - Add or Remove a breakpoint. It is also available in non-debug mode. Usually you will want to add breakpoints prior to starting the debugger.

- Pause - Pauses the debugging. This is effective only when the current execution is in the python language.

- Continue - Continue running the script till end or it encounters any breakpoint.

- Step Over - Step over the function. Start debugging the script from beginning if not already in debug mode.

- Step In - Step into the function. You will be able to view and run the function in debug mode, even if contained in a different file or module.

- Step Out - Step out of the function. Returns to the execution point of the file in script editor.

- Run To Cursor - It applies a temporary breakpoint at the cursor position and continues the execution till it encounters it or any other breakpoint.

- Jump To Cursor - Set the execution point at the cursor position. It must be only in current stack frame.

- Show Next Statement - Show the current execution point.


Debugging in script edit window

The script edit window shows Breakpoints in red highlights. The current execution point is highlighted in yellow color. Bookmarks are indicated by shaded line numbers.

When the debugger is running you can click on any variable or function and navigate its attributes in a menu tree. Upon selecting an attribute, it will be printed in the Output tab of the Debug window.

The values of a variable can be read and set by hovering the mouse over the variable in the editor.

Reading a specific variable can be exactly captured by manually selecting it in the editor.

Caution:

Note that the manually selected text is executed to return the results which, in some cases, might change the state of the debugged program (e.g., through function call).

The attributes of the variable (dir()) is available in the pop-up menu which, after clicking, gives its value in the Output tab of Debug windows. The breakpoint and execution point information will come if the mouse pointer is beyond the right-most end of the available text in editor.

The current script must be saved before debugging. In the debug mode the editor will be read-only.


Debug windows

The Debug window, when activated, is shown at the bottom of the Script Editor window. If hidden, use the toolbar context menu to activate it: check Debug Windows, as discussed in Toolbars.

There are four tabs that can be shown or hidden by selecting Debug menu > Debug Windows, then checking /unchecking the windows as desired.

Any of the tabs can be docked as a separate window. Right-click on the tab to open a context menu and select Dock. Note: you can also show or hide windows from this menu.

In the example below the Watch window is docked. You can detach and move any docked tabs or the main Debug window using click-and-drag on the left side bar:

The tabs in the Debug window display the following information:

Output

All the outputs are redirected to this window including stdout, stderr, debugger output and errors.


The filters can be applied to enable/disable these outputs. Right-click in the Debug window to access the context menu of this window. Select Output Filter, then check the desired output types.

You can also Select All the text from the window and Copy it. Then you can paste it into any application for saving.

Breakpoint

Lists all the added breakpoints from different files. It can be navigated by double-clicking on it. A particular breakpoint can be disabled by deselecting its active check box.

Breakpoints can be removed by selecting them (using Ctrl or Shift key for multiple breakpoint selection), then right-click on the selection, and Delete Breakpoint.


Stack

It shows the stackframes. The current stackframe can be set up/down by double-clicking on it. Each stackfame's associated global and local variable are shown in the child node of the tree view.

Watch

Variables can be watched by typing their names into the Name column. Their values will update dynamically while debugging. Their values can also be set by changing the corresponding Value column. Watches can be removed by selecting them (using Ctrl or Shift key for multiple watch selection), then right-click on the selection, and Delete Watch.


Run button

At the bottom of the Debug window you can enter one or more native python commands then click the Run button. Any python command can be executed in the current context. The result, if any, is printed to the Output tab.

The multiple commands can be separated by a semi-colon “;”or through a multi-line editor. (Multi-line editing can be toggled on / off by clicking the button “...” to the right of the Run text box.)

The Run button is also used for other purposes by giving prefixes as below.

“?” or “HELP” for reading the debugger help.

“=” or “EVAL:” for evaluating any expression.

“!” or “DEBUG:” for executing debug commands similar to pdb debugger commands set.

The history of the commands can be accessed using up/down keys. For an empty command, the previously executed command will be run if available.

Script Editor inside Action EditorA limited Script Editor can be opened in Template Builder from Action editor by clicking Code tab, then Edit button.

The menus (File, Edit, and Debug) and the directory tree are not present. File management capabilities are accessed from the Action Editor. Debug windows are not shown in this limited form of the script editor, as it is intended only as a code editing tool for the current action. Debugging of an action is accessed in the Template Execution window.

Tools for editing text, such as cut, copy, paste, undo, and redo are available from this window.

145Python (and RADE) Scripting Tools

Python (and RADE) Scripting ToolsDepending on the preference and skill of the template author, there are different options for writing Python (and RADE) scripts.

Scripting in Template BuilderThe Template Builder workspace can be used to create actions consisting of Python or RADE code. In this case, the Action editor has many tools to assist the author. This is the recommended tool for new scripts.

The creation of input and output parameters is facilitated using the Parameters section of the action editing dialog. Using this tool, the name, type (string, real, etc.), and default values of parameters can be specified. A flexible User Interface tool also allows the author to customize the UI for gathering inputs from the user upon execution of the action. Creating parameters and their user interfaces does not require any knowledge of Python or RADE. (See Action Data page - Parameters.)

The Code page provides access to the Script Editor tool. Python or RADE code can be typed directly into Script Editor, or copied and pasted from another window. (See Action editor - Code page). Some knowledge of Python or RADE is required to create scripts, either as actions or as stand-alone scripts. See RADE Scripting Language or Python Scripting Language for scripting language details.

Scripting in other SimXpert workspaces

Script Editor

The Script Editor can be opened in any SimXpert workspace to create, edit, and test scripts in Python or RADE code. (Go to Tools menu, Macros, Script Editor) However, actions may not be run stand-alone, but must be part of a template. See Using Script Editor for more details.

Macro Record

The Macro Record feature can be used to capture the code associated with the SimXpert commands executed during Macro Recording. Macro Record creates a *.proc (template) file, which can then be edited in Template Builder workspace. See Recording a Macro in Templates section of this User Guide for details.

SimXpert APIScript /action authors have access to most of SimXpert’s Application Programmer Interface (API). See the SimXpert API Documentation for the complete library of available SimXpert classes and functions. (Go to Help, SimTemplate Help, Template Reference. Select either Structures/ Thermal / Crash or Motion workspace.)

Python (and RADE) Scripting Tools146

Actions

Many GUI commands and tools have corresponding Actions, which are available from the Actions toolbox in Template Builder workspace. For a novice template author, using the built-in actions is best, before attempting to write your own scripts. See Inserting objects in a template for details on using built-in actions.

API calls

In addition to the actions provided, a large library of objects and functions (mostly RADE & C++, and some Python) are available in from SimXpert’s API. These range from high-level complex tasks to simple functions, which can be invoked in a Python (or RADE) script. The availability of this library will minimize the need for the action author to write extensive code.

Invoking Scripts in SimXpertThere are several ways to invoke scripts in SimXpert.

• Saved scripts and Macros can be run from the Script Editor window. Go to Tools, Macro, Script Editor to open the Script Editor.

Select script type (Python or RADE) from drop list. Use File, Open in Script Editor window to locate and open the desired *.rdl, *.py or *.xml file containing the script.

Click the Run icon (green arrow) to begin execution. However a RADE script that was built in Template Builder, as part of an action, may only be run in Template Execution window.

• In SimXpert a saved script can be invoked from the Tools menu, Macro, then Macros. (or by using the Ctrl-F8 button) This opens a selection dialog box to locate the saved script file. Recorded macros (*.proc), RADE scripts (*.rdl), and Python scripts (*.py) are valid file types.

g

147Python (and RADE) Scripting Tools

• Scripts that are contained within Actions can only be run as part of a template. Place the action into a template. It may be a temporary template for testing purposes. Save. Open the Template Execution window. Click on the desired action containing the script. Click the Run Selection Action button.

• To invoke a RADE script using a command line during a SimXpert session, simply type the following command in the Expression or ID’s text box, located on the Pick menu:

process_file full-path-name

• To invoke a RADE script during start-up is possible, but is for advanced users, as it requires an understanding of SimXpert’s directory structure and environment variables. For example, you could modify the startup shortcut by adding a script to it:

C:\MSC.Software\SimXpert\R4\WINNT\bin\simxpert32.bat -ridl C:\my_script.rdl

Python Scripting Language148

Python Scripting Language

What is Python?Python is a popular object-oriented programming language. It is a public-domain language and as such, manuals and examples are readily available. The Python interpreter and standard library are freely available in source or binary form for all major platforms from the Python Web site: www.python.org. The web site should also be consulted for the most recent Python language reference material.

Python is a high-level interpreted language, and thus no compilation and linking is necessary. It has high-level data types built in, such as flexible arrays and dictionaries. Python allows you to split your program into modules that can be reused in other Python programs. It comes with a large collection of standard modules. Python is extensible, making it possible to link Python scripts to the SimXpert API.

Overview of Python SyntaxThis is not a comprehensive documentation of Python syntax. Consult the Python Web site: www.python.org, for complete documentation.

Python code statements to be executed are typically contained inside functions. A function may require input values or objects. After a function has been called upon to be executed, it returns outputs to the caller.

Use of SimX API & RADE functions

All API available to RADE programmers via *.pkg files are also available to Python programmers. RADE based global variables are not available explicitly to python. All RADE extensions of classes (RADE-only methods) are not available explicitly to python.

Use import statement at the top of the action code to call the appropriate RADE *.pkg file.

Function Declaration

A function declaration defines a function and is of the form:

def functname(argument1, argument2):python code statementanother code statement

Contained within the parenthesis are the arguments, or parameters for the function, and can be either inputs or outputs. The suite of statements following the colon must be indented the same amount. Optionally, a series of short statements on one line may be separated by a semi-colon.

Class Definition

Data with similar attributes can be grouped into a “class.” A class is a data type which can contain “members” (attributes) and “methods” (member functions). A base class may contain other derived

149Python Scripting Language

classes, which inherit all the properties of the base class. A derived class can have additional unique properties of its own.

In the following example, a new derived class, Class_xyz is created. It inherits the attributes of the base class, BaseClassName.

The class declaration is followed by definition of the variables x and y, then the member function, func_do_something. Additional member functions can follow (as in func2, shown).

SimXpert's Object (Class) Hierarchy

See Overview of RADE Syntax.

Data Types

Some of the Python Data Types are as follows:

Number

Integer (plain, long and booleans)

Floating point (double-precision)

Complex

Sequence

Immutable types:

string - Characters

unicode - Unicode code units

tuples - comma-separated lists of items

Mutable types:

List - comma-separated list of expressions in square brackets. See also: Lists, in Python Syntax Details.

Mappings

dictionary - an unordered set of key: value pairs, with each key being unique

Python Scripting Language150

Set - an unordered grouping of immutable values, without duplicates

See www.python.org for more discussion of data types.

Variables

Variables do not have to be declared. The equal sign (=) is used to assign a value to a variable. The value may contain an arithmetic operation.

width = 20height = 5*9

A value can be assigned to several variables simultaneously:

x = y = z = 0 # Zero x, y and za, b = 0, 1 #a=0, b=1

Commenting

Python comments begin with a hash character, “#” which may appear at the start of a line or after a code statement.

Reserved Keywords

The reserved keywords cannot be used as names for variables, functions, or classes.

and else in try

as except is while

assert exec lambda with

break finally not yield

class for or

continue from pass

def global print

del if raise

elif import return

151Python Syntax Details

Python Syntax Details

Importing Files

A script file, or module, containing python code can be imported.

import filename

Once imported, the functions contained in the imported file can be called:

filename.funct1(param1,param2)

To import only certain functions from a module:

from filename import funct1, funct2

Code Blocks

Code blocks are defined by using the same indentation for each line in the block of code. The tab character is usually interpreted as a fixed number of space characters. It is advisable not to mix space characters and tabs when indenting code.

Control Blocks

See www.python.org for details on Python control blocks.

Memory Management

Memory management in Python is automatic. There is no need to manually allocate and free memory.

Numeric Operators

= Assignment

+ Addition

- Subtraction

* Multiplication

/ Division

// Floored Division

% Remainder (x % y gives remainder of x/y)

** Power (x**y is x to the power of y)

pow(x, y) Power (x to the power of y)

More at www.python.org...

Logical Operators

Python Syntax Details152

== Check Equality Condition: works with numbers and Strings

!= Not Equal Condition Checker

<= Less than or Equal to Condition Checker

>= Greater than or Equal to Condition Checker

< Less than condition checker

> Greater than condition checker

is [not] Object identity (with not, negated object identity)

[not] in Membership test / negated membership test (Sequences only)

Unary Operators

- Reverse sign / negate (numeric)

+ Unchanged value (numeric)

~ Bitwise inversion (Integers only)

Lists

A list is a compound data type used to group values together. The list items are contained in square brackets, comma-separated. List items need not all have the same type.

The expressions in the list are assigned consecutive numerical indices, starting with 0. For example:

a = ['red', 'blue', 100, 1234] #results in:#a[0]=red, a[1]=blue, a[2]=100, a[3]=1234

Notes on lists:

1. Native Python lists --

Starting with version R3.1, all list inputs and outputs for Python-implemented Script Actions are native python lists. This replaces the use of CLex-based lists.

If you have existing Python-implemented actions that were created in R3.0 or prior, please note the following:

• When you update the code of an existing Action, the input & output parameter declarations for list parameters are changed to the Python list format. (This refers to the use of Update button on the Code page of Action editor.)

• The user code will need to be updated to use the native python list API rather than the CLex-API. A warning message will be shown in the message window to alert you to this situation.

• If you wish to suppress this updating and retain the “CLex” list objects (e.g., NodeList, StringList, etc.) please add the “NativeLists=false” meta tag to your Action. (Layout page) This will cause it to retain / revert to the CLex-based lists.

153Python Syntax Details

• In connection with this, a new Python module has been added: SimXUtil.py. This has some API's that will make it easy to convert between a native Python list and a CLex-based list.

• RADE-implemented Script Actions are not affected by this change.

• User code that declares lists outside of the “CODE FENCE” declarations area is not affected. (In other words, lists that were created in the script without the use of + button on Parameters section of Data page in Action editor.)

2. Python lists vs. SimXpert API “XXXLists”

One potential area of confusion is the distinction between native python lists and those created using a constructor of one of the XXXList classes in the SimXpert API. (NodeList, for example) An instance of a XXXList object created using a constructor in the SimXpert XXXList class is not recognized by the Python interpreter as a List. If a “list” object is created in this way, then you have the choice to:

• Convert it to a Python list. Then you can use all the standard list functions and operations in Python. An example code snippet to make a Python list from a CLex XXXList is as follows:

python_list_out=[]for n in range( int(myXXXList.length() ) ): python_list_out.append(myXXXList.at(n))

• Use the member functions of the API class, rather than Python list operations. (These include functions such as “at, insert, remove, index,” etc.) Refer to the Template Reference in the SimTemplate help menu. Some additional conversion utilities are available in the new Python module SimXUtil.py

3. List Copying --

Copying of a list cannot be done by simply assigning variables, as in

py_list_out = py_ list_in;

It is necessary to loop through the list and copy each item in the list, as shown in the example below:

import RIDLpy_list_in=['red', 'blue', 100, 1234]py_list_out=[]# Do not simply assign list variables...# py_list_out = py_ list_in <-- invalid

# The correct way to copy one python list to another#for i in range(len(py_list_in)): py_list_out.append(py_list_in[i])SX.ShowMsg('The output list copy is ' + str(py_list_out))

The above example shows copying of one native python list to another. The following shows the copying of a SimXpert list class to a native python list.

# Do not simply assign list variables...# outstrlist = strlist;

Python Syntax Details154

# outobjlist = objlist;

# The correct way: do a copylen = strlist.length()i=0while i<len: outstrlist.insert(strlist.at(i)) i = i + 1

# For ObjectList, use the AddLists APISX.AddLists(objlist, outobjlist);

Built-in Functions

There are hundreds of built-in functions to perform mathematical functions, string operations, list operations, file handling, error handling, etc. There are many more functions contained in standard modules, which can easily be accessed using the import command to import a module and all of its member functions.

Many custom modules are available from the Python user community. See www.python.org for information on built-in functions, standard modules, and custom modules.

155Python Tutorials

Python TutorialsA few examples are provided to demonstrate how actions and scripts written in python can be used in SimXpert. In particular, it is necessary to know how to call the various functions in the SimXpert API that are needed to perform many tasks in SimXpert. (for example, sending a string to the Message window). These tutorials cover the following:

• Create a simple template with an embedded script using Python

• Incorporate RADE API calls to operate on model objects

• Create a new script action and use it in a template to query a model for the node count.

These tutorials are intended to be executed in the Template Builder workspace.

Python Tutorial 1 - Dog Years

In this tutorial you will create a small template containing an embedded Python script. The script calculates your age in dog-years. It also calls a function from the SimXpert API.

Step 1: Open Template Builder workspace and select New Template from entry screen.

Step 2: Double-click on the new template in Model Browser (It will be auto-assigned a name, such as Template1.) In Properties panel, rename the template as DogYears. Close Properties.

Step 3: On Controls toolbox, select Embedded Script. Click anywhere in the graphics window to place the script. Double-click on it to open Properties panel.

Step 4: In the dialog, type in dog_years_py as the Name, and select Python from the drop list for scriptType. Click Edit to open an editor tool.

Step 5: The action editing dialog now opens. Select Data tab at bottom. Click + button to add a new input parameter.

Step 6: Double-click in Name column of table and rename Input1 as YourAge. Enter Your current age in the Label field.

Step 7: Change Parameter type to Integer. Put in a default value, if desired, say 25.

Step 8: Switch to Output Parameters in drop-list. Click + to add an output. Change Name to DogYears and Type to Real.

Step 9: Select Code tab at bottom. Click Update button and note that some Code Fence statements are added automatically.

Step 10: You can enter code directly to the Code page or alternatively, click Edit button to open the Script Editor window.

Step 11: After the definitions of inputs there is a statement:

# # CODE FENCE END: Declarations

followed by:

# # CODE FENCE BEGIN: Outputs

Python Tutorials156

It is between the two above statements that the Python code will be placed. Type or copy / paste the following between the two code fence statements above:

### do some range checking, then print resultif YourAge < 0:

SX.ShowMsg ("Negative age?!? I don't think so.")elif YourAge < 3 or YourAge > 110:

SX.ShowMsg ("Frankly, I don't believe you.")else:

DogYears = YourAge*7.0dy_string = str(DogYears)dy_string2 = "That's " + dy_string + " in dog years."SX.ShowMsg(dy_string2)

You may have to add the indentations as shown above using Space characters.

Completed Script:

The entire completed script should look like this, with some sections having been automatically created. One important note is that SimXpert function calls are preceded by “SX.”

## # CODE FENCE BEGIN: Declarationsimport RIDL RIDL.loadModule("rgen_ridl");

context = SX.ScriptDelegate.current();if (not context):

SX.showErrorMsg("The script must be executed in a Process."); raise "Error";

inputs = context.getInputs();outputs = context.getOutputs();YourAge = inputs.getInt("YourAge"); # () Your current ageDogYears = 0; # () Age in dog years# # CODE FENCE END: Declarations

### do some range checking, then print resultif YourAge < 0:

SX.ShowMsg("Negative age?!? I don't think so.")elif YourAge < 3 or YourAge > 110:

SX.ShowMsg("Frankly, I don't believe you.")else:

DogYears = YourAge*7.0dy_string = str(DogYears)dy_string2 = "That's " + dy_string + " in dog years."SX.ShowMsg(dy_string2)

# # CODE FENCE BEGIN: Outputsoutputs.setDouble("DogYears", DogYears);# # CODE FENCE END: Outputs

Step 12: Make sure indentations are present to mark code blocks. Click Ok to save and close Script Editor. Click Ok to save and close action edit dialog.

157Python Tutorials

Step 13: Select the template in Model Browser, and then click Save icon on toolbar.

Step 14: Right-click on the template in Model Browser and select Test to open the Template Execution window. Click Run button to run the template.

You should get a prompting dialog box asking for your age, then the computed age in dog-years should appear in the Message window, and again in the Execution Report.

Python Tutorial 2 - Model name and node count

In this tutorial you will create a small template that includes a new script action, in Python code, that gets the current model and node count, using RADE calls from API. The new script action is saved as a separate action file (*.act) which is then used in a template.

Step 1: Open Template Builder workspace and select New Template from entry screen.

Step 2: Double-click on the new template in Model Browser (It will be auto-assigned a name, such as Template2.) In Properties panel, rename the template as Model_Nodes.

Step 3: Go to Publish page and select a Workspace for which the template will be applicable, such as Structures. Change file location, if desired. Close Properties.

Step 4: On Controls toolbox, select New Script Action. In the dialog, type in model_and_nodecount as the Name, and select Python from the drop list for code Type. Click Ok.

Step 5: The action editing dialog now opens across the entire graphics window. Select Data tab at bottom. There are no input parameters.

Step 6: Switch to Output Parameters in drop-list. Click + to add an output. Change Name to NodeCount and Type to Real.

Step 7: Select Code tab at bottom. Click Update button and note that some “Code Fence” statements are added automatically.

Step 8: Code can be typed directly in the window, or click Edit button to open Script Editor. After the definitions of inputs there is a statement:

# CODE FENCE END: Declarations

followed by:

# CODE FENCE BEGIN: Outputs

It is between the two above statements that the Python code will be placed. Type or copy / paste the following between the two code fence statements above:

model1 = CLexSofyEnv.getCurrentModel(); # same as RADE,everything in pkg filesdbname = model1.getDbName(); SX.ShowMsg ("Database Name - " + dbname); nodelist1 = model1.getNodeList();NodeCount = nodelist1.length(); #get the Node count

Completed script:

Python Tutorials158

The completed script should look like this:

# CODE FENCE BEGIN: Declarationscontext = SX.ScriptDelegate.current();if (not context): SX.showErrorMsg("The script must be executed in a Process."); raise "Error";inputs = context.getInputs();outputs = context.getOutputs();NodeCount = 0; # () NodeCount# CODE FENCE END: Declarationsmodel1 = SX.CLexSofyEnv.getCurrentModel(); # same as RADE,everything in pkg filesdbname = model1.getDbName(); SX.ShowMsg ("Database Name - " + dbname); nodelist1 = model1.getNodeList();NodeCount = nodelist1.length(); #get the Node count

# CODE FENCE BEGIN: Outputsoutputs.setDouble("NodeCount", NodeCount);# CODE FENCE END: Outputs

Step 9: Close Script Editor (if open).

Step 10: Return to Data page and click Save button to save the Action.

Step 11: Return to the Model_Nodes template where you started. It is still empty.

Step 12: Click Actions toolbox and Browse to the location of the model_and_nodecount.act file just created. Select it and click anywhere in the window to create an instance of it.

Step 13: Select the Model_Nodes template in Model Browser and click Save icon.

Step 14: Switch to another workspace, e.g. Structures, and open any model that contains nodes.

Step 15: From Templates toolbox, select Browse... and locate the saved template, Model_Nodes.proc and select it to open Template Execution window.

Step 16: Click Run button to execute the template. You should see a message stating the current model name in the Messages window. The node count value should be shown in an Execution Report window that opens upon completion of the template.

159RADE Scripting Language

RADE Scripting Language

What is RADE?Rapid Application Development Environment (RADE) is a powerful tool embedded in SimXpert to:

Add and Customize SimXpert's Functions

Integrate other commercial applications to SimXpert

Allow users to use SimXpert as a Pre/Post tool for their internal applications and technologies

Automate tasks and procedures

RADE is an interpretive environment. RADE is an Object Oriented (OO) Language, whose syntax is very similar to C++. Additionally, C/C++ shared libraries (objects and members) can be easily wrapped into RADE, thus making RADE an extendable Language.

Unlike Python, RADE is a proprietary code used by SimXpert.

Overview of RADE SyntaxThe syntax of RADE is similar to that of C++. Code statements to be executed may be contained inside functions. A function may require input values or objects. After a function has been called upon to be executed, it returns outputs to the caller.

Function Declaration

A function declaration defines a function and is of the form:

function classname:functionname(argument1, argument2){rade code statement;more rade code;}

If the function is not a member of a class, then the classname: is omitted. Contained within the parenthesis are the arguments, or parameters for the function, and can be either inputs or outputs.

The curly brackets contain the statements to be executed. Each statement is terminated with a semi-colon.

Commenting

RADE uses C++ like syntax for commenting your RADE Programs.

// comment here

Class Definition

Data with similar attributes can be grouped into a “class.” A class is a data type which can contain “members” (attributes) and “methods” (functions). A base class may contain other derived classes, which

RADE Scripting Language160

inherit all the properties of the base class. A derived class can have additional unique properties of its own.

In the following example, the global variables var1 and var2 for the new class, ClassXX are defined, followed by the class declaration, then the member function, func_do_something. Additional member functions can follow.

global ClassXX = {var1 = NULL,var2 = "Blue"};

class(ClassXX);function ClassXX:func_do_something(arg1, arg2)

{some code statement;}

SimXpert's Object (Class) Hierarchy

SimXpert's core API deals with Objects (e.g. A node object). There are various Base Classes defined in SimXpert. Each of these Base classes may have “child” members and functions which inherit the characteristics of the base class. For example, CLexFemObject is a child of CLexObject. The Inheritance Diagram of the CLexFemObject is shown for reference.

Some of the SimXpert base classes are mentioned below:

CLexGraphicsObject

CLexSolverCard

161RADE Scripting Language

CLexStatusLog

CLexField

CLexQualityEnhancer

CLexShapeFun

CLexGUITriad

CLexPostUtils

CLexObject

CLexFieldMeshSurface

CLexBox

CLexScene

CLexSofyStream

CLexMeshElement

CLexSofyEnv

CLexMorphControl

CLexColorBar

Data Types

RADE has dynamic type checking: As soon as a value is assigned to a variable, it gets a type. RADE has 5 Data Types:

function

number

char * (string)

table: can have numeric as well as non-numeric fields

void * (pointer): used to store C/C++ values.

Reserved Keywords

and for or

break function return

case global switch

continue if then

default local while

do NULL

else not

RADE Scripting Language162

The reserved keywords cannot be used as names for variables, functions, or classes.

163RADE Syntax Details

RADE Syntax Details

Pre Processor Controls

All preprocessor pragmas start with # symbol

#debug: turns debugging on

#nodebug: turns debugging off

#ifdef: condition starts a conditional ifdef pragma - if cond is false this part is skipped

#ifndef: condition starts a conditional ifdef pragma. If cond is true this part is skipped

#else: starts a conditional else pragma

#endif: ends a conditional else pragma

#endinput: ends the lexical parsing of the file

The condition may be:

0 - always false

1 - always true

Including (Processing) Files

Specifying including or processing (executing) a file is exactly the same:

include("path/filename")

process_file("path/filename")

Search path rules for the “include files”:

#path name: inserts a directory into path for file searched during execution of process file commands.

clearpaths(): Clears the search path stack.

path("Path_Name"): Rade Function to add a path where "Path_Name" is a string variable or a string constant.

Control Blocks

Syntax for the various RADE control blocks are as follows:

function func_name() { blocks }

if (condition expressions) { block }

if (condition expression)

{ block } else (or elseif) { block } end

while (condition) { block }

RADE Syntax Details164

do { block } // can be used for local scoping

repeat { block } until (condition)

for(exp1; exp2; exp3) { block }

switch(condition) case const1 : { . . break; } . . default : { . . break; } }

The for, while, do and do-while support continue statement, continue statements are not allowed in a switch statement

Variables

Variables must explicitly be declared as local or global.

For consistency and stability, the use of Global variables should be kept to a minimum to reduce conflicts with SimXpert and other supplier provided software.

Variables do not have types. Types are dictated by the values they hold. Evaluation is done at run time.

local a = "astring"; // type of variable a is string

a = 1.0; // type of variable a is number

C-style escapes are allowed with a '\'.

Strings are represented by "astring" or 'astring'

Similarly multiple initialized variable can be assigned as follows:

i, v = 0, 1; // i = 0 v = 1

i,j += 1, 3; // adds 1 to i and 3 to j

m,n ++; // increments m and n by 1

Memory Management

Memory management in RADE is automatic. All memory for 'local' variables is automatically managed.

Exception: when a user uses “new”

Nodes = NodeList:new(10000)

then the memory management is under programmer's control. In this case the statement

Nodes:delete()

would delete the allocated memory.

Arithmetic Operators


+ Addition or String Concatenation

- Subtraction

* Multiplication

/ Division

^ Power

= Assignment

++ Increment Operator (As Suffix Only)

-- Decrement Operator (As Suffix Only)

+= Adds the right hand side to the left hand side

-= Subtracts the right hand side from the left hand side

*= Multiplies the right hand side to the left hand side

/= Divides the left hand side by the right hand side

Logical Operators

== Check Equality Condition: works with Real, Integer and Strings

!= Not Equal Condition Checker

<= Less than or Equal to Condition Checker

=> Greater than or Equal to Condition Checker

< Less than condition checker

> Greater than condition checker

&& Logical And || Logical Or

Unary Operators

- Reverse sign (negate)

! Logical not

Tables

Table constructors are expressions that create tables. Every time a constructor is evaluated, a new table is created. Constructors can be used to create empty tables, or to create a table and initialize some fields.

The expressions in the list are assigned consecutive numerical indices, starting with 1. For example:

local a = {"v1", "v2", 34} is same as:


local a = {}; a[1] = "v1"; a[2] = "v2"; a[3] = 34

local a = {[f(k)]=g(y), x=1, y=3, [0] = b+c} is same as:

local a = {}; a[f(k)] = g(y); a["x"] = 1; a["y"] = 3; a[0] = b+c

TABLE Functions

looptable(table, function) - calls function for each field of table

looptablei(table, function) - calls function for each numeric field of table

loopvar(function)

next(table, index) - traverses a table (initially index should be NULL)

nextvar(name)

Built-in Functions

assert(v, [msg]) - similar to C function

clock() - returns the approximate cpu time in seconds

collectgarbage() - force a garbage collection cycle

date([format]) - follows the same rules as C function strftime

exit([code]) - executes the C exit function

getenv("varname") - gets the value of the environment variable

print(v1, v2, ...) - prints any number of arguments to stdout

process_file (" file_name ") - execute a file within this RADE environment

process_string (" ... ") - execute a string within this RADE environment

tostring(e) - converts the given argument to a string representation

tonumber(e) - **tries** to convert argument to number

type(variable) - returns the variable type

seterrormethod(method) - sets the error handler and returns the old handler

system("command") - executes a system command

length(table) - returns the length of numeric indices of table

insert(table, [, pos], value - inserts a value in a table optionally at a position which by default is at the end

remove(table, [, pos] - removes a value from a table optionally from a position which by default is at the end


sorttable(table [,function]) - sorts the numerical fields of a table optionally with the help of a sorting

Mathematical Functions

sin(x) - x in degrees, cos(x), tan(x)

asin(y), acos(y), atan(y), atan2(number, number)

deg(number) - converts radians to degrees

rad(number) - converts degrees to radians

PI - has the value of PI

abs(val) - returns absolute value

min (val1, val2, ..., valx) - returns min value

max (val1, val2, ..., valx) - returns max value

ceil (val) - returns the next higher integer

floor (val) - returns the next lower integer

log(number), log10(number)

mod (val2,val1) - returns the remainder of the expression (val2/val1)

sqrt(number)

NULL - Null Value

rand([integer n]) - when called with no arguments returns a random real number in the range [0,1] ; when called with a number n, Random returns a random integer in the range [1,n]

srand(number) - reset the random-number generator to a random starting point

Binary Operations

band(int n1, int n2) - returns n1 & n2

bor(int n1, int n2) - returns n1 | n2

beor(int n1, int n2) - returns n1 ^ n2

lshift(int v, int i) - returns v << i

rshift(int v, int i) - returns v >> i

String Functions

strlen(str) - returns the length of the string

substr (str,i,[j]) - returns a substring starting at the ith location and ending at the jth location.


strstr(str,pattern[,init]) - returns the index where the pattern match was found.

e.g: print(strfind("Hello There","There")) - this will print - 7.

tolower(str) - returns a copy of str with all characters changed to lower case.

toupper(str) - returns a copy of str with all characters changed to upper case.

strdupn (s, n) - Returns a string that is the concatenation of n copies of the string s.

tochar(number) - converts an ascii number to a character

ascii(char) - converts an character to ascii number

sprintf(format_string, e1, e2, ...) - returns a string specified by the format string.

Same as the printf family of standard C functions.

The options/modifiers *, l, L, n, p, h are not supported

There is an extra option, q - this option formats a string in a form suitable to be safely read back by the RADE interpreter; that is, the string is written between double quotes, and all double quotes, returns and backslashes in the string are correctly escaped when written. e.g.,

sprintf('%q', 'a string with "quotes" and \n new line') - will produce the string: "a string with \"quotes\" and \ new line"

strrepl (s, pattern, replacement [, n]) - Returns a copy of s, where all occurrences of the pattern have been replaced by a replacement string. This function also returns, as a second value, the total number of substitutions made.

PATTERN RECOGNITION

RADE uses 'Regular Expressions' for Pattern Recognition. The following combinations are allowed in describing a character class:

. (a dot) - represents all characters

%a - represents all letters

%c - represents all control characters

%d - represents all digits

%l - represents all lower case letters

%p - represents all punctuation characters

%s - represents all space characters

%u - represents all upper case letters

%w - represents all alphanumeric characters


%x - represents all hexa-decimal digits

%x - (where x is any non alphanumeric character) - represents the character x.

Escaping the magic characters ()%.[]*-?. - should be preceded by a %.

Example: read vertex 1 from an STL file

If line = "vertex 708.546021 -975.411987 720.219971"

b, e, v1, v2, v3 = strstr(line,"^%s*vertex%s+(%S+)%s+(%S+)%s+(%S+)");

will return b as non-null and vertices in v1, v2, v3

File IO Functions

All input and output operations are done, over two file handles. These are called:

_INPUT(reading)

_OUTPUT(writing).

The available global variables are:

_STDIN

_STDOUT

_STDERR

File handle is a user data containing the file stream FILE*, a distinctive tag is created by the I/O library.

Available functions:

openfile(filename, mode)

closefile (handle)

readfrom (filename)

writeto (filename)

appendto (filename)

remove (filename)

rename (name1, name2)

flush (filehandle)

seek (filehandle [, whence] [, offset])

tmpname ()

write ([filehandle, ] value1, ...)

RADE Tutorials170

RADE Tutorials

RADE TutorialsSeveral scripts are provided to demonstrate how RADE is used to perform certain actions in SimXpert. Please review the previous section on RADE syntax for more information on the RADE scripting language. The following topics are included in the RADE Tutorials.

• Creation/Modification/Deletion of entities (Nodes & Elements)

• GUI (menus, spreadsheets, etc.)

• Entity Picking

• Enquiring the SimXpert database (e.g. give me all warped elements)

• Vector usage (cross, dot, etc.)

• Nearest neighbors (find nearest entity to location)

• File IO for parsing files

• Geometry

• Spline creation

• Projection of a location on a curve

• etc.

These tutorials can be done in the Script Editor window, which is accessible from Tools menu, then Macro, and Script Editor. Each tutorial can be run by copying and pasting the indicated text into Script Editor window and clicking Run button. The tutorials are also available as a set of *.rdl files and if you have access to these files, the File Open command may be used in Script Editor to run each tutorial. Comments in each tutorial are marked by “//” or multi-line comments may appear as “/* ... */”

RADE Tutorial 1 - Hello World

1.) Hello World - This script sends the message “Hello World” to the Message window in the SimXpert session (at bottom of screen) in three different colors.

Type or Copy / Paste the text below into the Script Editor window:

#debug

/* * Legendary HelloWorld program */

ShowMsg("Hello World");ShowMsg("Hello World", "red");ShowMsg("Hello World", "blue");

Click the Run icon.

To save the file, click the File Save icon in the Script Editor window and name the file 01-hello.rdl

171RADE Tutorials

RADE Tutorial 2 - Object Oriented Programming Concepts

2.) OOP - Shows some features of object oriented programming


/* * Object Oriented Programming concepts * - Data storage in objects * - Giving messages to objects to do something * - Default parameters handled by messages */

#debug

global CMessage = {msg_ = NULL,color_ = "blue"

};// msg_ and color_ are global variables for the class/class(CMessage);// new defines constructor to create an instance of a class;// can be called with one or two parameters: str and (optionally) clrfunction CMessage:new(str){

local lm = {msg_ = str,}instance(lm, CMessage);return lm;

}

function CMessage:new(str, clr){

//ShowMsg("New Called ..."); local lm = {msg_ = str,color_ = clr,}instance(lm, CMessage);return lm;

}function CMessage:delete(){

//ShowMsg("Delete Called");//this.node_:delete();

}function CMessage:setMsg(str){

// "this" gets the handle on the current class // (in this case CMessage)this.msg_ = str;

}

RADE Tutorials172

function CMessage:getMsg(str){

return this.msg_;}

// handles default parameterfunction CMessage:show(color){

ShowMsg(this.msg_, color);}

function Demonstrate_OOP(){

local my_msg = CMessage:new("Hello MSC");my_msg:show();my_msg.msg_ = "xxxxxxxxx";my_msg:show("red");my_msg:delete();

local obj2 = CMessage:new("Hello World !!!!!");obj2:show();obj2:delete();

my_msg:show("red");}

Demonstrate_OOP();

Run the script by clicking the Run icon in the Script Editor window. If desired, this file can be saved as 02-oop.rdl.

RADE Tutorial 3 - List Handling

3.) List Handling - This tutorial shows how to use the various SimXpert XXXList classes, using IntList as an example. It also shows the general RADE Table data type, which can contain mixed data types.


/* * List handling in RADE. LIST is the ARRAY equivalent in most of the * other programming languages */

function ListBasics_CB(){

local i;

// instantiate a list. Below is a integer list (IntList) // from SimX API. // Similarly you can have ElementList, NodeList, etc.// local list = IntList:new(); mortal(list);

// insert some items in the list

173RADE Tutorials

list:insert(0);list:insert(3);list:insert(5);list:insert(10);// now list(0)=0, list(1)=3, list(2)=5, list(3)=10//// loop through the listfor(i=0; i<list:length(); i++) { // Print each member of the list print(list[i]);ShowMsg( "list [" + i + "] = " + list[i] );}

// Table usage// General RADE tables can contain mixed data types. // Initialize a tablelocal table = { };// The first item is given index of 1, not 0insert(table, "MSC");insert(table, "SimXpert");insert(table, 22/7);// but index of 0 can be assignedtable[0] = "zero";

local len = length(table);for(i=0; i<=len; i++) {print(table[i]);ShowMsg( "table [" + i + "] = " + table[i] );}

}// now execute the function ListBasics_CBListBasics_CB();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 3-list.rdl if desired.

Tip: Note on copying lists: Copying of a list cannot be done by simply assigning variables, as in:

py_list_out = py_ list_in;

It is necessary to loop through the list and copy each item in the list, as shown in the example below:

// Do not simply assign list variables...// outstrlist = strlist;// outobjlist = objlist;

// The correct way: do a copylocal len = strlist:length(); local i=0; for (; i<len; i++) { outstrlist:insert(strlist:at(i)); }

// For ObjectList, use the AddLists APIAddLists(objlist, outobjlist);

RADE Tutorials174

RADE Tutorial 4 - Menus

4.) Creating menus- Create your own menu item in SimXpert and assign to your own function.

Type or Copy / Paste the text below into the Script Editor window. Edit the line beginning with “path” to reflect the actual path where the tutorial files reside, if known:

/* * Adding menus to SimXpert */#debug

*/function ShowMessage_CB(){

ShowMsg("My First Button", "Blue");}function AddMyMenu(){

local my_menu = gui:getTopMenu():findChild("My Menu");if(not my_menu) {// add My Menumy_menu = TopMenuItem:new("My Menu");}

local pb;if(not my_menu:findChild("Show Msg")) {pb = PushButtonItem:new(my_menu, "Show Msg", "ShowMessage_CB"); }

}AddMyMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 4-menu.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Show Msg command from menu.

RADE Tutorial 5 - SimX Entity Creation

5.) Entity - In this tutorial, create some nodes, and then some shell elements.

You will need to switch to Structures workspace first. Type or Copy / Paste the text below into the Script Editor window:

/* * Defines 3 functions* 1. Creates a node grid* 2. Asks the user to pick 4 nodes and creates an element.* 3. Creates a menu with the 2 above functions* Please note that CLexSofyEnv is the basic class in SimXpert from * where you can start digging information about the model

175RADE Tutorials

*/

function CreateNodeGrid_CB(){

local i, j, x, y, z = 0, 0, 0.0, 0.0, 0.0;for(i=0; i<5; i++) {for(j=0; j<5; j++) {// system unit is m. dividing by 1000// If user unit is mm, nodes will be 10mm apart.x = i * 10/1000;y = j * 10/1000;z = 0.0;CLexNode:new(x, y, z);}}

}

function CreateElements_CB(){

// Ask the user to pick nodeslocal nodes = NodeList:new(); mortal(nodes);pickNodes(nodes, NULL, 4, "Pick 4 Nodes");if(nodes:length() < 4) {ShowErrorMsg("Pick at least 4 nodes");return;}

// Element has to go in some part. Try to get the current part.// if there is no current part, create a part "MyPart"local part = CLexSofyEnv:getCurrentPart();if(not part) {local model = CLexSofyEnv:getCurrentModel();part = CreatePart(model, "MyPart");CLexSofyEnv:setCurrentPart(part);}

// Create an element from the picked nodes// Need to Create a Shell element// CLexElement - CLexShellElement - CLexQuad4Element - // Member Function.local elem = CreateQuad4ElementFromSofyName(nodes[0], nodes[1], nodes[2], nodes[3], part);

UpdateCollectionList();drawAllCanvases();

}

function AddEntitiesMenu(){

local my_menu = gui:getTopMenu():findChild("My Menu");if(not my_menu) {my_menu = TopMenuItem:new("My Menu");}

RADE Tutorials176

local pulldown = my_menu:findChild("Create Entities");if(not pulldown) {local pulldown = PullDownMenu:new(my_menu, "Create Entities");PushButtonItem:new(pulldown, "Nodes", "CreateNodeGrid_CB");PushButtonItem:new(pulldown, "Elements", "CreateElements_CB");}

}

AddEntitiesMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 5-entity.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Nodes and Elements commands from menu. It will create a grid pattern of nodes, then one element from four picked nodes.

RADE Tutorial 6 - Picking

6.) Picking - Type or Copy / Paste the text below into the Script Editor window:

/* * Demonstrates simple entity picking * Deletes elements connected to picked node and the node itself */

#debugfunction DeleteElements_CB(){

// Ask the user to pick nodeslocal nodes = NodeList:new(); mortal(nodes);pickNodes(nodes, NULL, 0, "Pick Nodes to delete");if(nodes:isEmpty()) { return; }

local i;for(i=0; i<nodes:length(); i++) {local id = nodes[i]:getAppId();print(id);}

//local nodenn = CLexNodeNN:new(nodes);//local nearest = nodesnn:nn(loc);

// following is a classic example of // getting entities from entities// with getXXXFromYYY functions // you can almost achieve any entity enquirylocal elements = ElementList:new(); mortal(elements);getElementsFromNodeList(nodes, elements);

177RADE Tutorials

// SimXpert's entity deletiondeleteObjects(elements);deleteObjects(nodes);

// update the canvasdrawAllCanvases();

}// Add Picking to My Menu - assign to DeleteElements_CB functionfunction AddPickingMenu(){


if(not my_menu:findChild("Picking")) {local pb = PushButtonItem:new(my_menu, "Picking", "DeleteElements_CB");}

}AddPickingMenu();Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 6-picking.rdl if desired. After running the script, check the SimXpert menu bar for My Menu, then execute Picking command from menu. All elements connected to the picked nodes will be deleted.

RADE Tutorial 7 - Mesh

7.) Mesh - This tutorial is presently not working. Not able to import Iges file in a proper manner. Meshing fails. ???

For this tutorial you will also need the demo file, bracket.igs. Use File, Import to bring the geometry into the Workspace. Type or Copy / Paste the text below into the Script Editor window:

/* * - Load Bracket.igs * - Stitch all * - gets the surfaces from the current scene & meshes them */ function MeshSurfaces_CB(){

// get the current scenelocal scene = CLexSofyEnv:getCurrentScene();

// get the scenes surfaceslocal surfs = SurfaceList:new(); mortal(surfs);scene:getSceneSurfaces(surfs);

// mesh the surfaceslocal i, len = 0, surfs:length();for(i=0; i<len; i++) {surfs[i]:mesh();}

RADE Tutorials178

// detach the mesh from the geometry to do anything on the meshfor(i=0; i<len; i++) {surfs[i]:detachFemEntities();}

drawAllCanvases();}function AddMeshMenu(){


if(not my_menu:findChild("Mesh")) {local pb = PushButtonItem:new(my_menu, "Mesh", "MeshSurfaces_CB");}

}AddMeshMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 7-mesh.rdl if desired. After running the script, check the SimXpert menu bar for My Menu, then execute Mesh command from menu.

RADE Tutorial 8 - Enquiry

8.) Enquiry - In the Structures or Crash Workspace open a model that contains some shell elements. Type or Copy / Paste the text below into the Script Editor window:

/* * - Get all QUADs in the model * - Get a warpage value from the user * - Highlight elements with warpage greater than the above value *//*function CLexShellElement:warpage(){

return 10;}*/

function Enquiry_CB(){

// get the current model (you will usually have only ONE model)// all FE data digging starts at the model (CLexModel)local model = CLexSofyEnv:getCurrentModel();

// get all shell elements in the modellocal shells = ElementList:new(); mortal(shells);model:getElements(shells, __CLEXELEMENT, SHELL, "", True, True);

179RADE Tutorials

// get warpage from the userlocal str = CLexString:new(); mortal(str);GetString("Enter Min. Warpage", str);if (str:data() == "" || str:data() == "CANCEL") {return;}local warpage = tonumber(str:data());

print("-->", warpage);

// now loop through the elements and check their warpageslocal i, len = 0, shells:length();for(i=0; i<len; i++) {local elem = shells[i];cast(elem, "CLexShellElement");// Cast down to a child object to access it functions, // in this case, cast from CLexElement to CLexShellElementif(elem:warpage() > warpage) {HighlightEntity(elem);}//cast(elem, "CLexElement");}

}

function AddEnquiryMenu(){


local pb = my_menu:findChild("Enquiry");if(not pb) {pb = PushButtonItem:new(my_menu, "Enquiry", "Enquiry_CB");}

}AddEnquiryMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 8-enquiry.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Enquiry command from menu.

RADE Tutorial 9 - Spreadsheet

9.) Spreadsheet - This tutorial shows how to create a dialog box table (spreadsheet) and how to populate it with model objects and push-buttons. Note that Template Builder Action editing dialog has capability to create these interfaces automatically for inputs, and therefore should be used whenever possible.

In the Structures or Crash Workspace open a model that contains some parts and shell elements. Type or Copy / Paste the text below into the Script Editor window:

/*

RADE Tutorials180

#debug// Part Info Viewer (& Editor)

function PartInfoApplyCB(ss){

ss.apply = True;//ss.partName = ss:getCell(0, 0);//ss.thickness = ss:getCell(1, 0);ss:exit();

}

function PartInfoExitCB(ss){}

function PartInfoComboCB (){}

function BrowseCB(pb){

ShowMsg("Inside Browse Callback !");

// Get file to be read from userlocal pattern = CLexString:new("{ *.nas *.bdf *.dat }"); mortal(pattern);local workDir = CLexString:new(); mortal(workDir);local fileString = CLexString:new(); mortal(fileString);local selectedFileName = CLexString:new(); mortal(selectedFileName);GetFile(pattern, "Get Some File ?",selectedFileName, workDir,fileString,0);if(selectedFileName:data() == "CANCEL" or selectedFileName:data() == "") {ShowMsg("Cancelled");return;}local ss = pb.ss;ss:setCell(3, 0, selectedFileName:data());// store the selected filess.selectedFile = ss:getCell(3, 0);

}function PartInfoSpreadSheet(part){

local ss = CLexSpreadSheet:new("Part Info Viewer");ss:setNumRows(4);ss:setRowLabels(4, { "Name", "Thickness", "Demo Combo", "Push Button" } );ss:setNumColumns(2);ss:addActionButton("Apply", "PartInfoApplyCB");ss:setExitCB("PartInfoExitCB");ss:createGraphics();

181RADE Tutorials

local cb = ComboBoxItem:new(ss, "PartInfoCombo", "PartInfoComboCB");cb:addItem("A");cb:addItem("B");

local pb = PushButtonItem:new(ss, "Browse...", "BrowseCB");pb.ss = ss;// attaching ss to pb so that it can be accessed from the // BrowseCb callback

ss:setCell(0, 0, part:getName());ss:setCell(1, 0, part:thickness());ss:setCellWidget(2, 0, cb);ss:setCellWidget(3, 1, pb);

ss.selectedFile = "Not Selected Anything";

ss.apply = False;ss:manage();// pops up the spreadsheet

ShowMsg("After Manage");

if(ss.apply == True) {//print("--------");//print(ss:getCell(0, 0));//part:setName(ss:getCell(0, 0));ShowMsg("After Apply Pressed");ShowMsg("Selected File is: " + ss.selectedFile);}

UpdateCollectionList();}function Spreadsheet_CB(){

local parts = PartList:new(); mortal(parts);pickParts(parts, NULL, 1, "Pick A Part"); if(not parts:isEmpty()) {PartInfoSpreadSheet(parts[0]);}

}function AddSpreadsheetMenu(){


if(not my_menu:findChild("Spreadsheet")) {local pb = PushButtonItem:new(my_menu, "Spreadsheet", "Spreadsheet_CB");}

}

RADE Tutorials182

AddSpreadsheetMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 9-spreadsheet.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Spreadsheet command from menu.

RADE Tutorial 10 - Read STL

10.) STL - Open the Structures or Crash Workspace. For this tutorial a demo file named sample.stl is needed. Type or Copy / Paste the text below into the Script Editor window:

/* * - demonstrates how to use the file open dialog box * - reading a file * - parsing (some pattern recognition concepts)* - CLexWCoordinate */function ReadSTL_CB(){

local fname = CLexString:new(); mortal(fname);local pattern = CLexString:new("{ *.stl *.rdl }"); mortal(pattern);local workdir = CLexString:new(); mortal(workdir);local fstring = CLexString:new("unnamed.stl"); mortal(fstring);GetFile(pattern,"STL File Name: ?",fname,workdir,fstring,False);if(fname:data() == "CANCEL" or fname:data() == "") {

ShowWarningMsg("STL Read Attempt Cancelled !!");return;}ReadSTL(fname:data());

}function ReadSTL(file){

local model = CLexSofyEnv:getCurrentModel()local part = CLexSofyEnv:getCurrentPart();if(not part) {part = CreatePart(model, "STL_PART");CLexSofyEnv:setCurrentPart(part);}// parse the stl fileBusyCursor();readfrom(file); // Keywork - opens the file

183RADE Tutorials

local line, b, e, v1, v2, v3, n1, n2, n3;local p1 = CLexWCoordinate:new(); mortal(p1);local p2 = CLexWCoordinate:new(); mortal(p2);local p3 = CLexWCoordinate:new(); mortal(p3);local cnt = 0;while(1) {line = read("*l"); // Returns the whole line,& increment the // file pointer to the next lineif(not line) { break; }b, e = strstr(line, "^%s*outer%s+loop"); //b = found or not; e: column locationif(b != NULL) {//// read vertex 1line = read("*l");b, e, v1, v2, v3 = strstr(line, "^%s*vertex%s+(%S+)%s+(%S+)%s+(%S+)");if(b != NULL) {p1:setValues(v1, v2, v3);p1 = p1 / 1000.0;// mm -> m

// read vertex 2line = read("*l");b, e, v1, v2, v3 = strstr(line, "^%s*vertex%s+(%S+)%s+(%S+)%s+(%S+)");if(b != NULL) {p2:setValues(v1, v2, v3);p2 = p2 / 1000.0;// mm -> m

// read vertex 3line = read("*l");b, e, v1, v2, v3 = strstr(line, "^%s*vertex%s+(%S+)%s+(%S+)%s+(%S+)");if(b != NULL) {p3:setValues(v1, v2, v3);p3 = p3 / 1000.0;// mm -> m

n1 = CLexNode:new(p1);n2 = CLexNode:new(p2);n3 = CLexNode:new(p3);CreateTria3ElementFromSofyName(n1, n2, n3, part);}}}}cnt++;if( (cnt - (floor(cnt/5000) * 5000)) == 0) {ShowMsg("# Elements Created = " + cnt);}}ShowMsg("Done Reading STL File. Cleaning up ...");

RADE Tutorials184

// Merge coincident nodeslocal elems = part:getElementList();local nodes = NodeList:new(); mortal(nodes);getNodesFromElementList(elems, nodes);MergeCoincidentNodes(nodes, False, 0.0000001, True, False);

// delete unreferenced nodesdeleteObjects(nodes);

drawAllCanvases();UpdateCollectionList();FillScreen();IdleCursor();

}

function AddSTLMenu(){

local my_menu = gui:getTopMenu():findChild("My Menu");if(not my_menu) {my_menu = TopMenuItem:new("My Menu");}if(not my_menu:findChild("Read STL")) {local pb = PushButtonItem:new(my_menu, "Read STL", "ReadSTL_CB");}

}AddSTLMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 10-stl.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Read STL command from menu.

RADE Tutorial 11 - Graphics

11.) Graphics- Create temporary graphics objects.

Open the Structures or Crash Workspace. Type or Copy / Paste the text below into the Script Editor window:

/* * Temporary graphics object creation */

#debug

function CreateTempGraphics_CB(){

// Create a temporary linelocal lineGraphics = CLexLineGraphicsObject:new(0, 0, 0, 0.002, 0.002, 0.002);

// Create an axis

185RADE Tutorials

local axisGraphics = CLexArrowGraphicsObject:new(0, 0, 0, 0, 0, 1, 0.001);

local graphicsContainer = CLexSofyEnv:getCurrentScene():getHighlightsGraphicsContainer();graphicsContainer:insert(lineGraphics);graphicsContainer:insert(axisGraphics);

FillScreen();drawAllCanvases();

}

function AddGraphicsMenu(){


if(not my_menu:findChild("Graphics")) {local pb = PushButtonItem:new(my_menu, "Graphics", "CreateTempGraphics_CB");}

}AddGraphicsMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 11-graphics.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Graphics command from menu. A line and axis objects will be displayed temporarily.

RADE Tutorial 12 - Create Spline

12.) Create Spline- Type or Copy / Paste the text below into the Script Editor window:

// use of Parasolidfunction CreateSpline(coords){

delete_all_states(); // Clearing all the marksnote_and_name_state(); // Marks the parasolid at a level

local smooth = True;local body = PS_MakeWireBody(coords, smooth);

note_and_name_state(); // Marks the parasolid at a leveldelete_all_states(); // Clearing all the marksdrawAllCanvases();

}

function CreateSplineCB(){

while(1) {

RADE Tutorials186

local coords = CoordList:new(); mortal(coords);pickLocations(coords, 0, "Pick locations of the spline");if(coords:isEmpty()) { return; }

CreateSpline(coords);}

}

function AddSplineMenu(){


if(not my_menu:findChild("Create Spline")) {local pb = PushButtonItem:new(my_menu, "Create Spline", "CreateSplineCB");}

}AddSplineMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 12-CreateSpline.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Create Spline command from menu.

RADE Tutorial 13 - Grapher

13.) Grapher- Shows how to invoke the SimXpert grapher. Type or Copy / Paste the text below into the Script Editor window:

#debugload("grapher_ridl");function GrapherTestExit(plotter){

plotter:delete();}

function CreateGrapher_CB(){

local plotter = SGView:new(gui);plotter:setExitCB("GrapherTestExit");local canvas = plotter:currentCanvas();canvas:setXLabel("X");canvas:setYLabel("Y");canvas:setTitle("Title");// canvas:resize(width, height); if you want to resize// canvas:setXTickPrecision(2); pixel precision

local x_data = DoubleList:new(2); mortal(x_data);local y_data = DoubleList:new(2); mortal(y_data);

187RADE Tutorials

x_data:insert(0.0); y_data:insert(0.0);x_data:insert(1.0); y_data:insert(1.0);

local curve = canvas:addCurve("Curve 1");curve:addPoints(x_data, y_data);

canvas:scaleToFit();plotter:show();

}function AddGrapherMenu(){


if(not my_menu:findChild("Grapher")) {local pb = PushButtonItem:new(my_menu, "Grapher", "CreateGrapher_CB");}

}AddGrapherMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 13-grapher.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Grapher command from menu. Try adding data points to the above code to change the look of the graph.

RADE Tutorial 14 - Complex Picking

14.) Complex Picking- Demonstrates complex picking and adding options to Pick window.

Open a finite element model in the Structures or Crash Workspace. Type or Copy / Paste the text below into the Script Editor window:

/* * Demonstrates complex picking (pick dialog functionality) * - Deletes elements connected to picked node * - hence shows "how to automatically * - add elements to the pick" when node was picked */#debugfunction DelElemsProcessFunc(pp){

if(pp:isEmpty()) { return; }local node = pp:last();cast(node, "CLexNode")

// Get elements connected to the nodelocal elems = ElementList:new(); mortal(elems);ShowMsg(node:getAppId());node:getConnectedElements(elems);

RADE Tutorials188

if(elems:isEmpty()) {ShowErrorMsg("No Elements Connected to Picked Node !!");CLexPickDialog:resetPickLists();return;}

// Add these elements to pickCLexPickDialog:rejectLast();local i, len = 0, elems:length();for(i=0; i<len; i++) {CLexPickDialog:insertPickedObject(elems[i]);}CLexPickDialog:getNumPickedList():insert(len);//CLexPickDialog:resetPickLists();//deleteObjects(elems);

}function DelElemsDoneFunc(pp){

// Something has to be pickedif(pp:isEmpty()) { ShowErrorMsg("No Elements to Delete !!");CLexPickDialog:resetPickLists();return; }// Get the elementslocal elems = ElementList:new(pp:length()); mortal(elems);local i, len = 0, pp:length();for(i=0; i<len; i++) {local elem = pp[i];cast(elem, "CLexElement");elems:insert(elem);}CLexPickDialog:resetPickLists();// Delete the elements & nodes(if option is enabled)local nodes = NodeList:new(); mortal(nodes);if(CLexPickDialog:isChoiceEnabled()) {getNodesFromElementList(elems, nodes);}deleteObjects(elems);deleteObjects(nodes);//CLexHistory:NoteAndNameState("Delete Elements");drawAllCanvases();

}function AddElemsToPick_CB(pp){

if(pp:isEmpty()) { return; }// Get connected elements & add them to the picklocal elems = ElementList:new(); mortal(elems);local nodes = NodeList:new(); mortal(nodes);cast(pp, "ElementList");getNodesFromElementList(pp, nodes);getElementsFromNodeList(nodes, elems);// Remove already picked elements from the pick dialogCLexPickDialog:resetPickLists();

189RADE Tutorials

// Add these elements to picklocal i, len = 0, elems:length();for(i=0; i<len; i++) {CLexPickDialog:insertPickedObject(elems[i]);}CLexPickDialog:getNumPickedList():insert(len);

}function ComplexPicking_CB(){

CLexPickDialog:reset();// History initialization//CLexPickDialog:TurnPickHistoryOn();CLexPickDialog:setPickTitle("Delete Elements");CLexPickDialog:insertPickItem(__PICK_NODES);CLexPickDialog:setSinglePickStyle();// setMultiPickStyleCLexPickDialog:setProcessingFunction("DelElemsProcessFunc");CLexPickDialog:setDoneFunction("DelElemsDoneFunc");CLexPickDialog:manageChoice(False, "Delete Nodes Also", "Delete Nodes Also");//CLexPickDialog:setExtraRejectLastFunction("CLexPickDialog_GenericHistoryRejectLast");//CLexPickDialog:setExtraExitFunction("CLexPickDialog_GenericHistoryExit");//CLexPickDialog:setExtraExitFunction("");CLexPickDialog:setAnyFunction("AddElemsToPick_CB","+");CLexPickDialog:manageEvents();ShowMsg("Pick a Node whose connected elements will be deleted");

}function AddComplexPickingMenu(){

local my_menu = gui:getTopMenu():findChild("My Menu");if(not my_menu) {my_menu = TopMenuItem:new("My Menu");}if(not my_menu:findChild("Complex Picking")) {local pb = PushButtonItem:new(my_menu, "Complex Picking", "ComplexPicking_CB");}

}AddComplexPickingMenu()

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 14-ComplexPicking.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Complex Picking command from menu. Compare this code to that in Tutorial 6.

RADE Tutorial 15 - Point on Curve

15.) Point on Curve - Creates a point on curve that is nearest to the screen pick.

RADE Tutorials190

Open a geometry file or SimXpert database that contains curves in the Structures workspace. Type or Copy / Paste the text below into the Script Editor window:

/*function CurveExampleCB(){

local curves = CurveList:new(); mortal(curves);pickCurves(curves, 1);if(curves:isEmpty()) { return; }local curve = curves[0];// curve is made up of edgeslocal edges = curve:getEdgeList();local i, len = 0, edges:length();local pos = CLexWCoordinate:new(); mortal(pos);local tangent = CLexWCoordinate:new(); mortal(tangent);local graphicsContainer = CLexSofyEnv:getCurrentScene():getHighlightsGraphicsContainer();for(i=0; i<len; i++) {local edge = edges[i];local ret, start, end = 0, 0.0, 0.0;ret, start, end = edge:getRange(start, end);local param = (start + end) / 2.0;edge:eval_tangent(param, pos, tangent);CLexNode:new(pos);local axisGraphics = CLexArrowGraphicsObject:new(pos:x(), pos:y(), pos:z(), tangent:x(), tangent:y(), tangent:z(), 0.010);graphicsContainer:insert(axisGraphics);}drawAllCanvases();

}function PtOnCurveMenu(){


if(not my_menu:findChild("Pt. on Curve")) {local pb = PushButtonItem:new(my_menu, "Pt. on Curve", "CurveExampleCB");}

}PtOnCurveMenu();

Run the script by clicking the Run icon in the Script Editor window. This file can be saved as 15-PointOnCurve.rdl if desired.

After running the script, check the SimXpert menu bar for My Menu, then execute Pt. on Curve command from menu.

191

Template Execution

Open Template Execution window192

Open Template Execution window

Template Builder workspaceRight-click on a template in Model Browser and select Test.

The Template Execution window opens.

Other workspacesFrom the workspace toolboxes panel, select the Templates tool ribbon / toolbox to browse the available templates for the workspace. Recently accessed templates may appear in the toolbox. Click on a template tool to open the Template Execution window.

If the desired template is not shown in the list, use the Browse tool to locate a template that is stored locally.

193Open Template Execution window

Use Retrieve or Run Published Template... tool to access SimManager and open a published Template from there. In the first case, the template is retrieved and results files are not managed in SimManager. But when using the Run Published Template...tool, the option exists to run remotely and manage results files using SimManager Enterprise edition. When “Managed” execution is selected, a Process object is created in the SimManager database, and the inputs and outputs are captured in SimManager.

Running a Template194

Running a Template

Unit ValidationAs soon as a template is opened in the Execution window, the current model units are checked against the unit system stored in the template. If a mismatch exists, you will be prompted to change the units.

Select Yes to automatically change the current unit system to be consistent with the template. The Messages window will display a confirmation of the change in unit system.

Select No to execute without changing to the template’s unit system.

Select Cancel to abort execution.

Unit Validation is performed only on top-level templates. If a sub-template has a different unit attribute than the parent template, then no additional validation or conversion will occur. In this case, the template author may need to add an action to change the units for the sub-template.

Providing template inputsClick Run button.

Typically an input parameter dialog box will appear to gather undefined input parameters. Those actions designated as “Include with Parent” will prompt for inputs before starting template execution. Those set to “Prompt for Inputs” will not prompt for input parameters until that action is reached in the template execution.

195Running a Template

Enter the appropriate inputs and choices in the text boxes provided, or select objects from the SimXpert model. A Pick button indicates that the object can be picked from the current model. Click the button to initiate a pick panel.

When picking is active, the dialog box will be minimized. Click middle-mouse button in graphics window to finish picking and return to the input dialog box.

Click OK to begin Template execution after providing all inputs. Depending on the prompting behavior assigned to each action, additional dialog boxes may appear prior to each action.

Pick using recorded gesturesWhen a macro is recorded, or a template is executed and saved, the picking of objects is saved in detail. This goes beyond simply recording object i.d.’s. The saved information includes the scene (model objects displayed, viewing angle, and zoom) and the screen location of the picks.

When these saved inputs are later used to run the template, objects will be picked based on the recorded gestures. The view, scene, and screen locations of the original picks are replayed. This allows the use of a model that is similar to the original model, but perhaps with different object i.d.’s. Automatic picking of objects can occur, even if i.d.’s do not match.

Running a Template196

Un-do and Re-doWhile executing a template, it is possible to reverse the previous steps, using Un-do icon. The template must be in a paused state to access this command.

If the Un-do command has been used, then the Re-do icon becomes activated. The Un-do can then be reversed to return to the original state.

Action IconsWhen View Chart is activated, the flowchart of the template is displayed, similar to the view in Template Builder. As each action in the Template is executed it becomes highlighted in the execution window.

A yellow square outlines the current action, indicating the action is being executed or possibly paused, waiting for input.

A real-time graphical view of the model status may also be seen for certain actions, when the icon has been designated as a graphics snapshot. Right-click on a snapshot icon to access SimXpert view manipulation commands (Pan, Zoom, etc.)

Note: When running a recorded macro or template with saved inputs, selection of objects may occur automatically. You should be prepared to check the auto-selections and verify them. If incorrect objects are auto-selected, they must be rejected or cleared before proceeding.

197Running a Template

Click Fit button to resize the icons to fill the window. Use Zoom icon and scroll bars to view any part of the template in detail.

Status messagesA small message area appears on the toolbar of the Template Execution window, giving current status.

In Tree view, the status of the template and each action in the template is displayed.

Watch the SimXpert Messages window for additional status and prompting messages.

Control buttons198

Control buttonsControls to run, pause, stop, and run selective actions are on the toolbar at the top of the Template Execution window. Most of these are also available on a context menu by right-clicking on an action in the tree or flowchart.

Run / continue

Select this button to begin Template execution. If execution is currently paused, select it to continue the execution.

Run selected action

To run only one action at a time, first select an action in the current Template. Click the Run Selected Action button to run only the selected action. Template execution then pauses at the next action.

Step into

Activate the Python debugger and step into the code of the current action. (Only available for user-written actions.) A Script Editor window will open, with a breakpoint exactly on the first line of user written Python script code. You can edit the code and use all of the Debugger features, such as watching variables, monitoring outputs, and stepping in / out / over functions. You can open multiple script files in the Script Editor window and copy / paste code from one to the other. See Using Script Editor in the Creating Actions section of this guide for details on using the Python debugger.

Continue to here

First select an action in the current template. Click the Continue to Here button to run the Template from its current location up to the selected action. Execution will pause at the selected action.

199Control buttons

Pause

While Template is executing, use pause button to temporarily halt execution. To resume execution click run / continue button. Or click Step Into to enter debugging mode.

Stop

While Template is executing, use stop button to halt execution of the Template. Use this button only if you do not intend to continue.

Pause at selected

This button will set a breakpoint at any action in the template. Prior to running a Template, select an action where a pause is desired, then click Pause at selected button to create a pause point. A green square on outside the action icon indicates that a pause has been set there.

While running the template, execution will pause at that location. Use the Run / continue button to resume execution. Or click Step Into to enter debugging mode.

Toggle automatic execution

Select an action, then select the Toggle automatic execution icon from toolbar to make the selected action optional, or to toggle back to automatic mode for the action. This icon is not available when an action was designated as automatic in Action properties by the template author.

Options200

OptionsClick the Options icon at upper left of Template Execution window to access a list of options.

View Tree

Select View Tree to show the tree view of the template execution.

View Chart

Select View Chart to show flowchart view of the template execution.

201Options

Prompt for Inputs

If checked, user will be prompted to supply any inputs needed by the template during execution. If Use Saved Inputs is also checked, input values from a prior run are populated in dialog boxes, but user will confirm each. If un-checked, template runs automatically using saved input parameters from a previous execution.

Use Saved Inputs

Inputs from a previous run can be used to help automate a Template. All or part of the template can be run, using inputs from a previous run. The Process\Executed folder will be searched for a saved execution file with the same name as the current template, and the template will be run using the inputs specified in that file.

Auto Save

Automatically saves a Template file corresponding to the executed template, and containing all the selections and inputs made by the user during the run. The template file is saved after each action in the template is completed.

Template Inputs

Opens a dialog box with all the undefined inputs for the Template. Default values can be changed here, prior to execution.

Options202

Execution Report

Opens a Execution Report dialog box showing all the output parameters for the Template. If the template has already been executed, shows the status of the execution, and the values of output parameters.

Batch execution

Allows the Template to be executed with inputs contained in a comma-separated value (*.csv) file. The CSV file may contain multiple sets of inputs such that the Template can be run several times with different input values.

A *.csv file editor and execution control buttons are provided in a separate window when running a batch execution. The *.csv file can be edited prior to starting the batch execution. See Batch execution of templates, below.

Reset

Resets the status of each action to “Unexecuted.” Also resets counters for any simple or for-each loops. Useful if it is desired to re-start a template execution.

203Batch execution of templates

Batch execution of templates

Opening Batch Execution windowBatch execution option can be selected from Options menu (on toolbar of Template Execution window), or in the Templates tool ribbon.

It opens a dialog box to Select a Comma Separated Value input file containing stored inputs for the current Template.

The *.csv file may have been created in Template Builder when creating the template file. See Template Properties, Publish, Create .csv file for details on creating the CSV input file.

Select the *.csv file that corresponds to the template being executed.

Batch execution of templates204

A separate Batch Execution window appears in which the csv file can be edited, saved, and then the batch execution can be initiated.

Editing the *.csv filePrior to running the batch execution of a template, the *.csv file can be modified in the Batch Execution window. Each row of the table represents one run of the template. Each column represents an input parameter. Rows and columns may be added or deleted. Copy and Paste tools are available to assist with the editing of input values, similar to spreadsheet editing.

Use Save or Save As... commands to save a copy of the modified file.

Running the batch executionClick Run button. The template will be run once for each row in the *.csv input file. Note that all inputs must be included in the *.csv file (or valid defaults set), as it is not possible to have a mixture of supplied inputs from *.csv and input prompting dialogs.

A dialog box will ask if Template should be saved after each row of data. Select Yes to create a template file (*.proc) for each run.

205Batch execution of templates

If necessary, click Stop button to halt template execution.

Note: When running in batch mode, the Unit Validation dialog box will not appear. Units will be changed to the user units stored in the template and template execution will proceed as normal.

Outputs will be written to the *.csv file. Check Outputs tab to view the outputs.

Click Close button to dismiss the Batch Execution window.

Import Input Values206

Import Input ValuesInput parameters can be imported from any saved template execution file (*.proc). Inputs are imported, but template is not executed until Run button is selected.

Click the Import Input Values icon in the template execution toolbar.

A file browse dialog box allows navigation to the location of the saved template file, typically in the Process\Executed folder. Select a *.proc file in Executed folder to open.

Upon selecting the file, the input parameter values are imported. The Template can be run again using the saved input parameters, or they can be modified before executing, using Template Inputs on Options menu.

When used together with Use Saved Inputs in Options menu, clicking Run button causes template to execute using the saved values from the imported file. If Prompt for Inputs is not checked, the template will run without stopping to confirm the input parameters. The saved values are used instead.

207Save

SaveAfter a Template has been executed, the Save button becomes available. Click Save to store a template (*.proc file) containing details about the execution \

A file save dialog opens. The default location is in the SimXpert install directory, Process\Execution folder. If a different location is desired, navigate to the folder location and provide a name for the template.

The file name is by default the original file name with a date stamp appended to the name.

When running a Template in iterative mode, multiple execution files can be stored for each Template. A saved Template execution can be recalled using the Import Input Values command, or by simply navigating the directory structure when Browsing for a template to execute.

Edit208

EditClick on Edit button on the toolbar at upper right of Template Execution window to edit the Template in the Template Builder workspace.

The current Template is opened in the graphics window and in the Model Browser.

See Creating a new template section of this user guide for details on creating & editing templates.

209

SimManager Interface

SimManager Introduction210

SimManager Introduction

IntroductionA complete Simulation Data Management solution is possible when SimXpert is coupled with SimManager. Integrated Best Practices capture in the form of SimXpert Templates are best managed in an enterprise-wide data and knowledge management package such as SimManager. This allows sharing and life-cycle management of templates and all related data files.

An expert analyst can create a SimXpert template for executing an analysis procedure and “publish” it to SimManager. Other analysts and designers throughout the enterprise can “retrieve” the template and use it for their particular design phase or product line. SimManager is used to manage the roles of users as authors or consumers of templates and designate the appropriate access and editing permissions for each. The audit trail of Template modifications is automatically tracked in SimManager and users can obtain pedigree information on published templates.

SimManager also allows direct integration to MSC Patran, Easy5, MD Adams, MSC SimXpert, and MSC SimDesigner. Models, data, and (where enabled) templates that are published to SimManager can be accessed from these applications. Thus an analysis best practice procedure captured as a template by an expert user in SimXpert can be run by other users throughout an organization. In many cases, the user may not need any knowledge of SimXpert to run a template in batch mode from SimXpert or SimManager Web portal. Likewise, design files, models, and results files can be made available to other users enterprise-wide.

There are several commands and tools in SimXpert that interact with SimManager. Most of the analysis workspaces (Structures, Thermal, Crash, etc.) all share common interfaces with SimManager. The Template Builder has some unique interfaces relating to creating and publishing templates. A summary of these interfaces follows:

211SimManager Introduction

ToolbarThe SimManager toolbar allows access to SimManager from the SimXpert session, including ability to login, logoff, and open the SimManager web portal.

The SimManager toolbar is found in all SimXpert workspaces, but the Template Builder toolbar is slightly different from the other workspaces. See SimManager Toolbar section for more details on the SimManager toolbar commands.

Template Builder workspaceIn addition to the SimManager toolbar, there are several ways to interact with SimManager in the Template Builder workspace.

Actions and templates are retrieved from SimManager for insertion into a template or for editing using the Retrieve commands, in the Published toolbox. See Creating a new template for more details.

Publishing of completed templates to SimManager is done from the Template Properties dialog box. or from Model Browser context menu (right-click).

Actions can be published from the Action Editor.

SimManager Introduction212

See Publishing from SimXpert to SimManager for more details on publishing to SimManager.

Other analysis workspacesIn any SimXpert analysis workspace (e.g. Structures, Crash, Thermal, etc.) simulation data may be published to SimManager and subsequently retrieved using the SimManager toolbar. The entire SimManager database can be navigated using Browse. See SimManager Toolbar for details.

To execute a published template, use the Retrieve or Run Published Template tool from the Templates tool ribbon. You can navigate SimManager, select a template, and execute it in the appropriate SimXpert analysis workspace.

The Enterprise Model Browser tab also allows for creating SimManager objects, retrieving, and publishing data directly from Model Browser.

Refer to Help, SimXpert Assistant for Enterprise Model Browser details.

213SimManager Toolbar

SimManager ToolbarThe SimManager toolbar is found in the toolbar area just below the SimXpert main menu. If the SimManager toolbar is not present, right-click in the toolbar area and place a check by SimManager to turn on the toolbar.

The SimManager toolbar allows access to SimManager from the SimXpert session. In Template Builder workspace the toolbar commands include Login, Logoff, Web Client, and Run Published.

In the other analysis workspaces the toolbar is slightly different. The Login, Logoff, and Web Client toolbars are present, as in Template Builder. In addition there are Browse, Publish Data and Retrieve commands.

LogonOpens a logon dialog in which you must supply a valid User Name and Password.

SimManager Toolbar214

LogoffDisconnect from SimManager. A confirmation message will appear. Click Yes to logoff.

Web ClientOpens the SimManager web client in a browser window.

(A login screen may appear first.) Once the SimManager web user interface is open, you may sort the entries by Project or user, for example. A view of all Templates is also available.

There are many capabilities to query and navigate the database. You may copy items to clipboard and save to local directory. It is also possible to find relationships between data such as parent /child relationships, release status, item history, etc. Refer to SimManager R3 User’s Guide for further information on using the web user interface.

215SimManager Toolbar

Run PublishedThis toolbar command is only present in Template Builder workspace. Allows you to select a template from SimManager to open and run locally using the Template Execution window.

A navigation panel provides access to the Projects in SimManager and filters the view according to Template objects stored there. Upon locating a template, it may be saved to disk and executed. See Retrieve and Run a Template for details.

Publish DataThis toolbar command is not present in Template Builder workspace but is present in all other analysis workspaces (Structures, Motion, etc.) Click Publish Data icon on SimManager toolbar to open a publish dialog box.

The current SimXpert model will be published, along with associated data files (analysis decks, results files, images) to SimManager. The items to be published will be associated with an existing Project and design variant in SimManager. See Publish Other Simulation Data, below for details.

Retrieve DataThis toolbar command is not present in Template Builder workspace but is present in all other analysis workspaces (Structures, Motion, etc.) Select Retrieve Data icon to initiate a SimManager retrieve dialog box. This allows navigation in SimManager to locate the Project, Design, and Simulation files of interest.

See Retrieving from SimManager section for details.

SimManager Toolbar216

Browse DatabaseThis toolbar command allows you to navigate SimManager database, to view all types of objects stored there, and to retrieve them.

Browse allows viewing and retrieval of CAD files, design variants, AE scripts, and many other object types. This is somewhat different than the Retrieve Data command, which is limited to analysis models and related data.

217Publishing from SimXpert to SimManager

Publishing from SimXpert to SimManager

Publish a Template from Template BuilderOnce a template has been tested and saved in Template Builder, it can be shared by publishing to SimManager. Open the Properties Dialog box for the template by double-clicking on the template’s icon in the Browser. Select Publish on the left side.

Select Workspace(s) for which the template is valid. Then click Publish to begin.

The template Name and Description are populated automatically. Change Description, if desired. Place a check in the box if the template requires user interaction during execution. Click Ok to proceed.

Publishing from SimXpert to SimManager218

It may be necessary to Login to SimManager first. Upon doing so, a Publish Template dialog box appears.

Select the Project under which the template is to be published: click Browse... button by Project Path. Typically, the Method project is used for templates.

An Object selection dialog appears. Select a Project from the dialog. To obtain more information on any project, click the Details button. Click OK to select a project and close the dialog box.


Returning back to the Publish Template dialog, note at the bottom, the Publish Status of each resource (action or template) within the parent template. If any resource is not yet published, or has been modified since the last publication, it will be published along with the parent template. Built-in actions from the Action library are not published as resources.

Click Ok to proceed with the publishing process. A dialog box indicates the file transfer status.

Finally, an information dialog box will show that publication of the template was successful.

Publish an Action from Template BuilderAn action may be published from the Action Editor. Open the Action editor.

Note: Projects and authorized users for each project are established by an administrator or super-user. This configuration is done from Tools menu in SimXpert, then Options, and SimXpert Enterprise Manager.


After modifying and saving the action, go to the Data sheet and click the Publish as Resource... button to initiate a connection to SimManager.

In the Publish Resource dialog, select a Project by clicking Browse button.

Select a Project. (Dialog is same as shown above in Publish a Template from Template Builder.)


Click Ok to publish the action as a resource.

Publish Other Simulation DataOther simulation data can be published to SimManager, using the Publish Data icon on the SimManager toolbar. (All workspaces except Template Builder) This can be used to publish a SimXpert model, along with input deck, results file, and key result images.

A Publish dialog allows for description of the Analysis Model and association with a specific Project Name and Design Variant. Or if user has the appropriate privileges, a new Project or Design variant may be created.

Click Select Project button to choose the appropriate Project in SimManager.


Use the drop-lists to choose the appropriate Item Name, Design Variant Name, and Analysis Model Name, or type directly in the field.

Additional files can be attached to the Analysis Model, such as Input Deck, Results File, and image files. Use the Add... buttons along the bottom to attach Input deck, Results Files, and/or Key Result Images to the Analysis Model. A Job Name may be added to describe the analysis run.

Click Ok to upload the files to SimManager.

223Retrieving from SimManager

Retrieving from SimManager

Retrieve Data using SimManager ToolbarFrom any SimXpert workspace (except Template Builder), a SimXpert model along with related input deck, results file, and key result images can be retrieved from SimManager. These file types are the same as published using the Publish Data command from the toolbar.

Select the Retrieve Data button in SimManager toolbar.

This brings up a Retrieve Dialog to locate the data in SimManager.

Click Select Project button to specify the project in which the desired files are stored.

Retrieving from SimManager224

Then select the target Storage Directory for retrieved objects. Click Browse... to change the default directory.

Then select the Item and Design Variant of interest. Select an Analysis Model from the drop list.

Any Model objects associated with the chosen Analysis Model will be listed in the bottom area of the dialog. Check the box to also retrieve Input Decks and Results files.

Place a check in the box in Include column for each item to be retrieved. Input Decks, Results, and Key Result image files.

Select Ok to retrieve and place a copy of the selected objects in the specified storage directory.

Retrieve and edit - actions or templatesEditing of an action or template is done in the Template Builder workspace. To retrieve an action or template from SimManager for editing, use the Retrieve Template or Retrieve Resource tool on the Controls toolbox.

A dialog box may appear for logging in to SimManager.

A SimManager Login Dialog may appear. Enter the appropriate User Name and Password.


Upon logging in, an Object Selection Dialog will appear to allow selection of the desired Template. Locate the applicable Project and then select the desired Template. Click on any node in the tree to expand each section as needed.

Select the desired Template and review the description in the dialog box. Click Ok to proceed and close the Object Selection dialog box. The retrieved template or action will appear in the Template Builder window.

Saving a local copy

Optionally, you can save a local copy of a template or resource by doing the following before clicking Ok in above step: In Files section, click on the template file (*.proc or *.xml) listed.

If a Project folder is selected in browser tree, multiple templates may be displayed in a slightly different tabular format. In multiple-object display you can scroll across the Details table to locate the Files column and select a template file.

Select the file(s) and a dialog box may appear to select the particular file desired (*.proc or *.xml extension). Usually you would select the *.proc file, and Ok.

Retrieving from SimManager226

An Open File dialog box is displayed. Select Save to disk option and Ok.

A standard browse dialog prompts for the destination folder. Select a destination directory on the local drive. Click Ok. A confirmation message will indicate successful saving of the file. Click Ok to dismiss.

Retrieve and insert into templateWhile creating a template in Template Builder workspace, published items from SimManager can be retrieved and inserted into the current template.


Use the Published toolbox, and select Retrieve Template or Retrieve Resource to initiate retrieval of actions or templates from the SimManager database.

The selection dialog and procedure is the same as shown above in Retrieve and edit - actions or templates.

Once retrieved, the mouse pointer will change to an outline of the object’s icon, indicating that it can be placed into the template by clicking in the graphics window.

See also: Inserting objects in a template for more details on adding actions to a template.

Retrieve and Run a Template228

Retrieve and Run a Template

In Template Builder workspaceUse Run Published icon from SimManager toolbar.

In other workspaces

Select Templates on Tool ribbon / Toolbox.

Unmanaged execution

To retrieve a Template from SimManager, optionally save a local copy, and run it “unmanaged:” Select Retrieve...

A SimManager Object Selection Dialog box appears. Navigate the browser tree to locate the desired template and select it. Use the procedure described in Retrieve and edit - actions or templates to select the template to retrieve and run.

Click Ok to execute the selected template

229Retrieve and Run a Template

In the case of unmanaged execution, the Template Execution window is opened immediately. Click Run button to begin execution. Upon execution, a Process object is NOT created in the SimManager database. In other words a record of the execution instance is not retained, therefore the inputs and outputs are not captured in the database.

See Running a Template in Template Execution chapter of this User Guide for details.

Managed execution

To run in “managed” mode: Select Run Published... command in Templates tool ribbon.

Retrieve and Run a Template230

Follow the same procedure as for Unmanaged execution to browse the Object Selection Dialog and select a template file.

In the case of Managed execution, there will be an Input Parameter dialog box. First click Project button to choose Project under which to manage the template result data.

Provide the input parameter values and/or objects in the Template Parameters section.

Choose the Managed option. Upon execution, a Process object is created which captures the details of the template execution, including inputs, outputs, user, date / time stamp, etc. in the SimManager database.

Local or Remote execution

If so configured, you may also have the option to Run in Remote Server or Local to Application (default). Click Ok to proceed.

231Retrieve and Run a Template

A Template Execution Display Dialog will keep you informed of the status of the execution. (The Template Execution window may not appear.) Select the Status tab to see execution status and messages. Select Inputs or Outputs tab to see input or output parameters.

SimXpert Enterprise Manager232

SimXpert Enterprise ManagerVarious administrative options are available to configure SimXpert to work with SimManager. These allow you to set up the connection, and establish projects, users, and application helpers. To access these options, select Tools from top menu bar, then SimXpert Enterprise Manager. There are four menu items available as discussed in the following sections.

Note: Projects, users, and their roles are established by an administrator or super-user. Each user is allowed access to certain projects, and can perform only those actions designated by the administrator.

233SimXpert Enterprise Manager

Connection ConfigurationChoose Connection Configuration from the SimXpert Enterprise Manager menu to set up and test the connection from SimXpert to SimManager. Consult your system administrator for the correct settings.

Click Test... to check that the connection is set up correctly. A confirmation message will indicate that the test was successful.

Project ConfigurationUsers with sufficient privileges can create and modify Projects in SimManager using Project Configuration command. Select Tools from top menu bar, then Options, SimXpert Enterprise Manager and Project Configuration.

A login screen will appear. Enter User Name and Password in the fields indicated and click OK.


The Project Editor dialog opens. To modify an existing project, use the drop-down combo boxes for “Selected Project” and “Selected Domain” to select the Project.

The following actions are available from Project Editor dialog:

1. Add User To Project:

Select a User (from Available Users list) and select a Role from the drop-down list. Click right-arrow button (>>>) to add user to the currently selected project/domain. Once added; the user becomes a member of the project with his/her assigned role.

2. Remove User From Project:

Select a User from Authorized Users list. Click left-arrow button (<<<) to remove user from the currently selected project/domain. Once removed; this user becomes a non-project member and therefore will be listed in the 'Available Users' list.

3. Update User Role In Project:

Updates a project user's role in the selected project/domain. This operation consists of two steps: first the user is removed from the project; second the same user (now in the available users list) is added back to the project with a different role.

4. Add User Profile To Project:


Adds a user profile (from available user profiles list) to the project/domain. Once added; the user profile becomes a member of the project with its assigned role.

5. Remove User Profile From Project:

Removes a user profile (from authorized user profiles list) from the project/domain. Once removed; this user profile becomes a non-project member and therefore will be listed in the 'Available User Profiles' list.

6. Update User Profile Role In Project:

Updates a project user profile's role in the selected project/domain. This operation consists of two steps: first the user profile is removed from the project; second the same user profile (now in the available users list) is added back to the project with a different role.

7. Set/Edit Project Description:

Text area labeled as 'Project Description', can be used to set/edit selected project's description. After setting/editing the project description, press OK to commit your changes.

8. Set/Edit Project Remarks:

Text area labeled as 'Project Remarks', can be used to set/edit selected project's remarks. After setting/editing the project remarks, press OK to commit your changes.

9. Create Project:

Create project function is also provided from the Project Editor. This function allows the user to create new project(s) in the SimManager system. To create a new project simply click on the Create Project button positioned at the bottom left corner of the Project Editor. The Create Project dialog comes up:

Enter the Project Name, Short Name, Project Description (required fields) and Project Remarks (optional) for your new project. If the new project is a Sub-Project under an existing Project, click the Select Project button to identify the parent project.


and press OK to create this project.

User ConfigurationSelect Tools from top menu bar, then Options, SimXpert Enterprise Manager and User Configuration to open a dialog for updating users and user roles in SimManager.

Upon opening, all users of the system with default roles will be listed in the initial table. The table may be sorted by any column by clicking the column title. To modify the role for a particular user, click in the field under Default Role column to open a combo box and change user’s role. New users may be added by typing in the user name in the blank line at the bottom under the Users column. Click OK to confirm and apply changes.


Application HelpersSelect Tools from top menu bar, then Options, SimXpert Enterprise Manager and Application Helpers to open a dialog for mapping a file extension to an application used to open or display the file.

Click Add... button to specify additional file extension and associated application. Type the Extension in the field where indicated, and use Browse... button to locate the application to be used to open the given extension.

Select an Extension from the list and Edit... to change the mapping for that extension. Select an Extension and Delete... to remove the Extension from the Application Helper list.


239

Aaction data 91

identification 92parameters 94publish 93

action editor 89code page 128data page

identification 92parameter interface 109parameters 94

data sheet 91layout page 126

action instancerequired version 59

action options 123action properties dialog box 55actions

connecting 35creating 82creating (summary) 30definition 80editing 89, 131embedded script 87entering code 128execution option 58inserting in a template 25instances of 85linked 85new script action 84properties 55saving and publishing 93types of 81version 92

Bballoon tips 17batch execution 203boolean parameter 118branching 37

240

building a templatesteps used 7

CCADobject parameter 120choice tool 37configure SimManager 232connection tool 35controls toolbox

about 34choice 37connection 35file 45for-each loop 41message 48prompt 47simple loop 39while loop 43

create csv 52create layout 53creating a template

steps used 7creating an action 82creating an embedded script 87csv file 52csv input 203Ddefinitions 5discrete constraint 102Eediting

actions 89editing actions 131embedded template 28enterprise object parameter 121enumeration parameter 119Ffile tool 45Iinput and output parameters 94

241

input parameterdiscrete constraint 102range constraint 102

input parametersboolean parameter 118CAD object 120enterprise object 121enumeration parameter 119integer parameter 116interface 109managed object 120object parameter 119point parameter 120real parameter 117string parameter 111

inputsprompting options 58

inserting objects in a template 25integer parameter 116Llayout 53layout properties 126lists

copying 153loop

for-each loop 41simple loop 39while loop 43

Mmacro recording 23managed object parameter 120message tool 48Nnew script action 84Oobject parameter 119options 69

action 123

242

Ppoint parameter 120prompt for confirmation 48prompt for file 45prompt for string 47prompt tool 47properties

action instances 55actions 55template 49template general 49template inputs 50template outputs 51template publish 51

publish a template 217publish an action 219publish simulation data 221published actions

inserting in a template 28published templates

inserting in a template 28publishing to SimManager 217python

running scripts 146syntax details 151syntax overview 148tutorials 155

python scripting language 148RRADE

introduction 159running scripts 146syntax details 163syntax overview 159tutorials 170

range constraint 102real parameter 117recording a macro 23retrieve and edit 224

243

retrieve and run a template 228retrieve data from SimManager 223Sscript editor 134Scripting tools 145scripts

converting to action 133running 146writing 134

search tools 18settings 69SimManager

administrative options 232browse 223introduction 210project configuration 233publishing from SimXpert 217retrieve and run template 228toolbar 213

string parameter 111Ttemplate

batch execution 203controls toolbox 34inserting into another template 27options 69properties 49retrieve and run from SimManager 228testing 63

template builder workspacecontext menus 64creating templates 21editing templates 19introduction 2settings 69tools 5window 14

template execution windowcontrol buttons 198

244

import input values 206opening 192options 200python debugger 198running a template 194saving execution file 207

template properties dialog box 49templates

creating 21editing 19embedded 28executing 192

testing a template 63tool tips 17tutorials

python 155RADE 170

types of actions 81Uuser interfaces 109

boolean parameter 118CAD object 120enumeration parameter 119integer parameter 116managed object 120object parameter 119point parameter 120real parameter 117string parameter 111

Vversion

action 92action, required 59

Documents

SimXpert R3.2 Template Builder Workspace Guide