Chapter 4: Using Tcl to Control the HyperMesh Session

Chapter 4

Using Tcl to Control the

HyperMesh Session
The macros that have been created thus far are very powerful in their automation
of repetitive tasks. However, there are limitations. For example, in the LoadCol
macro which creates a load collector called forces, the name of the load collector
is hard-coded. If the user wanted to create a load collector with a different name,
it would require editing the name in the userpage.mac file.
The Tcl scripting language can be utilized to provide support for more advanced
tasks. Using the previous example, Tcl could be used to request a name for the
load collector from the user and use that information to tell the HyperMesh
session to create a load collector with the user provided name.

HyperMesh Commands vs. Tcl Modify Commands

The HyperMesh commands that were presented in the previous chapter are also
available through their Tcl Modify commands. For the HyperMesh Tcl Modify
commands, the command syntax has changed and does not contain
parentheses and commas; they have been replaced with a blank space. Also the
wrapper commands *beginmacro() and *endmacro() are not used. For
example, lets compare the following HyperMesh command macro and its Tcl
equivalent.

HyperWorks 12.0

Introduction to HM Customization 47
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

Macro in userpage.mac file

*beginmacro("macroJpeg")
*setbackgroundcolor(255,255,255)
*setmeshlinecolor(6)
*jpegfile()
*setbackgroundcolor(0,0,0)
*setmeshlinecolor(0)
*endmacro()

Tcl Script
Not used in Tcl
*setbackgroundcolor 255 255 255
*setmeshlinecolor 6
*jpegfile
*setbackgroundcolor 0 0 0
*setmeshlinecolor 0
Not used in Tcl

Notice that while the parentheses and commas have been removed, each of the
commands still begin with an asterisk (*) and that the command name hasnt
changed. In addition to the syntax change, Tcl core commands can also be used
(these are the commands presented in Chapter 1). The addition of the Tcl
commands provides added functionality to the macros.

Tcl GUI Commands and Tcl Query Commands

In addition to the HyperMesh Tcl Modify Commands, there are HyperMesh Tcl
GUI commands and HyperMesh Tcl Query Commands. As their names suggest,
these commands either make changes/updates in the HyperMesh GUI or they
query the HyperMesh database for information. Also, these commands have the
prefix hm_. We will go over a few basic HyperMesh input widgets and a table
of common commands will be presented.

Basic HyperMesh Input Widgets

One of the most basic things that need to be done in a macro is to enter data or
text to be used in the HyperMesh macro. For example, imagine we are creating
a load collector as we did in the previous chapter. In that example, the name of
the load collector was hard-coded into the macro. Using the hm_getstring
command, a string value is returned by providing the user with a HyperMesh
panel. The syntax is:
hm_getstring ?caption? ?message?
where both the caption and message are optional arguments. The caption is
shown in the panel while the message is shown in the message bar. For
example:
hm_getstring Load collector name Enter a name for the
load collector
produces the following panel and message in HyperMesh
Introduction to HM Customization 48
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

Panel produced by hm_getstring

This command can be used with the set Tcl command to assign the string
entered in the panel to a variable:
set loadname [hm_getstring Load collector name Enter
name for load collector]
In addition to getting a string, the hm_getint and hm_getfloat commands
can be used to get values by posting a panel in the HyperMesh panel area. The
hm_getint command returns a user input integer value while hm_getfloat
returns a user input floating point value. Both these commands have the same
options as the hm_getstring command. As an example, lets assign a floating
point value to a variable called force:
set force [hm_getfloat Force Enter force value]

Panel produced by hm_getfloat

With the addition of the HyperMesh Tcl commands, there are a few commands
which replace the HyperMesh Modify commands. Specifically there are the
hm_createmark and hm_clearmark commands. These commands perform
the same functionality as the *createmark and *clearmark commands, but
they are the HyperMesh Tcl equivalent. The advantage of using these
commands is that it avoids situations where additional Tcl commands need to be
used to evaluate the HyperMesh command. Using hm_createmark and
hm_clearmark when writing Tcl scripts is the more efficient and recommended
method.
HyperWorks 12.0

Introduction to HM Customization 49
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

The following table contains a list of the commonly used HyperMesh Tcl
commands as well as a short description of that command. For a full explanation
of the commands, please refer to the Reference Guide in the HyperWorks help.

Common HyperMesh Tcl Commands

Force an answer to the next * command
hm_answernext "yes"
hm_answernext
*deletemodel
Inform HyperMesh whether or not messages should
hm_blockmessages
be displayed in header message bar
Places entities on a mark based on user-supplied
hm_createmark
options
hm_elemlist
Return list of element ids for passed component id
hm_entityinfo
Get information about entities in current model
Get list of names or IDs of all entities of the
hm_entitylist
requested type in current model
hm_entitymaxid
Return maximum ID in use for an entity type
hm_errormessage
Display error message in header message bar
hm_getclosestnode Return ID of closest node to point x y z
Get information for an entity using the HyperMesh
hm_getentityvalue template interface
hm_getfilename
Get filename from user using HyperMesh file panel
Get floating point value from user using HyperMesh
hm_getfloat
panel
hm_getint
Get integer value from user using HyperMesh panel
hm_getmark
Get ids for passed entity type on passed mark mask
hm_getstring
Get text string from user using HyperMesh panel
hm_info
Get general information about HyperMesh
hm_markclear
Clear IDs for entity type from passed mark mask
hm_nodelist
Get list of node IDs for passed element
hm_nodevalue
Get XYZ values for passed node ID
Display message in HyperMesh header message
hm_usermessage
bar

Using the Command Window

The first step in learning to integrate Tcl scripts into the HyperMesh environment
is to learn how to launch scripts from the HyperMesh interface. An interactive
Command Window is provided and can be access through the View menu. This
Introduction to HM Customization 50
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

launches the Tk Console (TkCon) which is an interactive console which comes

with Tk.

The Command Window

In the Command Window, users can evaluate any command that can be issued
in Tcl or in HyperMesh through Tcl. Lets examine a few commands. General
Unix command such as ls, pwd, and cd can be used within the Command
Window. The ls command will return the directory contents, the pwd command
will return the current working directory, and the cd command allows users to
change directories.
In addition to general UNIX commands, general and HyperMesh specific Tcl
commands can be entered. For example, lets use the HyperMesh specific Tcl
command hm_info with the following options:
hm_info appinfo SPECIFIEDPATH TEMPLATES_DIR
The above command with the provided options will return the current template
directory. Any command that can be issued in Tcl or in HyperMesh through the
Tcl command layer can be entered at the Command Window prompt and it will
be evaluated. This capability provides the automation tool developer an easy
means of testing a concept before writing the full procedure.
The Command Window also provides the ability to run Tcl scripts by either using
the source command or using the File/Load Menu option. When using the
source command, the complete path and filename needs to be given (unless
the file is located in the directory the user is currently in within the Command
Window).
source C:/temp/my_macro.tcl
The other option is to use the File/Load Menu. This menu is available in the
Command Window by right clicking in the Command Window (shown below).
You can also save the session contents in the Command Window using the
File/Save Menu option.

HyperWorks 12.0

Introduction to HM Customization 51
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

The Command Window Load Menu

Tcl scripts can also be run in HyperMesh by creating a button on the Utility
menu User page. As was shown in Chapter 2, when creating a button for a Tcl
script, the EvalTcl basic macro will need to be referenced in the
*createbutton() command. In the examples and exercises following, we will
be using this macro to add buttons to the User page for the Tcl scripts that will be
written.

Example 4.1: Using the Command Window

The purpose of this example is to become familiar with using the Command
Window for developing in Tcl. In this example, HyperMesh Tcl and core Tcl
commands, will be used in the Command Window to determine the number of
elements in a component collector for a pre-defined HyperMesh model.
The following commands are used in this exercise:
Modified HyperMesh commands:
*createmark()
HyperMesh Tcl commands
hm_info
hm_getmark
Core Tcl commands
list
llength
set
source

Step 1: Launch the Command Window from HyperMesh

1. Open HyperMesh.
2. Go to the View menu and select Command Window.

Introduction to HM Customization 52
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

Step 2: Run operating system commands from the Command

Window
Run a couple operating system commands to become familiar with entering
commands and getting the output.
1. Run the command pwd.
The present working directory is returned.
2. Run the command ls
A list of the present working directorys contents is returned.

Step 3: Run HyperMesh Tcl and core Tcl commands from the
Command Window
1. Run the command set a [list 1 2 3 4 5]
A Tcl list variable named a is created and values 1-5 are added to this
list.
2. Run the command set a_length [llength $a]
The length of the list a is set to the variable a_length.

Step 4: Retrieve the HyperMesh file c_channel-tcl_vector.hm

Step5: Create a buffer (mark) for the elements in the component
upper
Create a mark which contains all the elements in the component upper using
the by comp name option in the *createmark command. In the Command
Window, type the following:
*createmark elems 1 by comp name upper

Step 6: Retrieve the element ids from the mark and store them
in a Tcl list variable.
In order to get the elements ids stored in the mark, the hm_getmark command is
used. This command returns the entity IDs of the passed entity type from the
specified mark In the Command Window, type the following:
set elemIds [hm_getmark elems 1]

Step 7: Count the number of elements in the list and display the
result
By using the llength Tcl command, the number of entities in the list elemIds
can be found.
HyperWorks 12.0

Introduction to HM Customization 53
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

set numElems [llength $elemIds]

In the Command Window the value of 390 is returned, which is the number of
elements in the component collector upper.

Step 8: Display the element count result

Using the puts command, we can print the output of a variable to the Command
Window.
puts $numElems
Again the value returned is 390 which is the number of elements in the
component collector upper.

Step 9: Verify the returned number of elements is the same

number reported in HyperMeshs Count panel.
1.
2.
3.
4.
5.
6.
7.

On the Tool page, enter the count panel, FE entities subpanel.

Switch the entity selector to comps.
Select comps >> upper.
Click select to complete the selections.
Click selected.
Notice in the elems field is the number 390.
Click return to exit the count panel.

Step 10: Save the executed commands to a file

1. In the Command Window, right click and select File >> Save >> History.
2. For File name type command_window_ex.tcl.
3. In a text editor, open the file command_window_ex.tcl and verify it
contains all of the commands you typed in the Command Window.

Step 11: Load the command_window_ex.tcl file into the

Command Window.
1. Right click in the Command Window and select File >> Load File.
2. Select the command_window_ex.tcl file.
390 is returned.
This example is complete. You can close the HyperMesh session.
Introduction to HM Customization 54
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

Process to Create a Tcl HyperMesh Macro

1. Define the task.
2. Delete the existing command.cmf file. This file is located in either the
start-in directory or the current working directory.
3. Perform the operations in HyperMesh that the script should run.
4. Extract the commands from the command.cmf
5. Create a Tcl script by converting the commands to Tcl format and
modifying as necessary (this includes adding additional Tcl commands)
6. Create a new Utility menu macro that runs a Tcl script.
7. Add macro button using *createbutton that calls the macro created in
Step 6 with the appropriate Tcl script filename.
8. Reload the current .mac file into HyperMesh to load the modified
userpage.mac.
9. Test the macro.
This process is nearly identical to developing a HyperMesh Basic macro. The
only differences are that the HyperMesh commands must be converted to Tcl
format and that Tcl core commands are allowed to introduce control logic to the
automation tools.

Example 4.2: Automate Creating Forces with a

User Specified Magnitude
In this example, we will go through the general process for creating HyperMesh
Tcl scripts. The script will automate the creating of forces with a user defined
magnitude.
The following commands are used in this example:
Modified and added HyperMesh commands:
*createmark
*clearmark
HyperMesh Tcl commands:
hm_getfloat
Core Tcl commands:
set

Step 1: Define the task to be automated.

1. Create a load collector named forces.
2. Request the user to select the nodes on which to apply a force.
HyperWorks 12.0

Introduction to HM Customization 55
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

3. Request the user to specify the magnitude of the forces to be created.

4. Create the forces and organize them into the forces collector.

Step 2: Delete the command.cmf file from your working

directory.
Every command executed in HyperMesh is recorded in the command.cmf file.
To view only the tasks commands, it is suggested you delete the command.cmf
file before doing the task. After deleting this file, the file is automatically
recreated when more commands are executed in HyperMesh.

Steps 3-5: Do the task in HyperMesh to capture its commands to

the command.cmf file.
Step 3: Retrieve the file c_channel-tcl_vector.hm
1. Open HyperMesh.
2. From File > Open, select the file c_channel-tcl_vector.hm

Step 4: Create a load collector.

1. Click the Model tab in the tab or go to the menu bar and select View >
Browsers > HyperMesh > Model.
2. Right-click in the white blank area and from the pop-up menu, select
Create > Load Collector..
3. For Name, type forces.
4. Select any color for Color.
5. Verify that there is a check mark next to Close dialog upon creation.
6. Click Create to create the load collector.

Step 5: Create a force on the beam

1.
2.
3.
4.
5.
6.
7.
8.

On the Analysis page, enter the Forces panel.

With the nodes selector active, select any node.
For magnitude =, type 23.
For the direction selector, select the z-axis.
Toggle from magnitude % = to uniform size =.
Create the force.
Return to the main menu.
Keep this HyperMesh session open for steps later in this example.

Step 6: Copy the tasks commands in the command.cmf file and

paste them to the create_force.tcl file.
Introduction to HM Customization 56
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

1. Open a text editor and create a new text file named create_force.tcl.
Save the file to your HyperMesh working directory (My Documents on
Windows).
2. From your HyperMesh working directory, open the command.cmf file.
3. Locate the following four commands at or near the end of the file.
*collectorcreateonly(loadcols, forces, , 7)
*loadsize(1,15,0,1)
*createmark(nodes,1) 3237
*loadcreateonentity(nodes,1,1,1,0,0,23,0,0,23,0,0,0,0,0)
4. Copy these commands and add them to the text file create_force.tcl

Steps 7-9 Modify and add to the script commands as necessary.

Step 7: Modify the code so it is in Tcl syntax
To modify the code so that it is in the appropriate Tcl syntax, parentheses and
commas need to be replaced with a blank space. This results in the following
four lines:
*collectorcreate loadcols forces 7
*loadsize 1 15 0 1
*createmark nodes 1 3237
*loadcreateonentity nodes 1 1 1 0 0 23 0 0 23 0 0 0 0 0

Step 8: Allow the user to select nodes on which to apply a force.

Here we are updating the code by adding the *clearmark command and
replacing the *createmark command with *createmarkpanel. The
*clearmark command clears the node ids that are currently in the mark (if any
are currently there). The *createmarkpanel command is used to get user
selected nodes using a HyperMesh panel and store them in the buffer.
1. Before the *createmark command, add the following line which clears
the node ids currently in mark 1.
*clearmark nodes 1
2. Modify the *createmark command to allow users to select the nodes
using a HyperMesh panel and store them in the buffer.
*createmarkpanel nodes 1 Select nodes
HyperWorks 12.0

Introduction to HM Customization 57
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

Step 9: Allow the user to specify a force magnitude.

Using the hm_getfloat command, the user can enter a value for the
magnitude and then using the set command it can be stored as a variable. The
variable can then be substituted for the hard coded force magnitude.
1. Get a force magnitude from the user using a HyperMesh panel and store it
in a variable. Enter the following line after the *createmarkpanel
command.
set mag_val [hm_getfloat Magnitude = Enter the force magnitude]

2. Substitute the hard coded force magnitude with the variable mag_val.
*loadcreateonentity nodes 1 1 1 0 0 $mag_val 0 0 $mag_val 0 0 0 0 0

Step 10: Review the script to see if it looks similar to the

following:
*collectorcreate loadcols forces 7
*loadsize 1 15 0 1
*clearmark nodes 1
*createmarkpanel nodes 1 Select nodes
set mag_val [hm_getfloat Magnitude = Enter the force magnitude]
*loadcreateonentity nodes 1 1 1 0 0 $mag_val 0 0 $mag_val 0 0 0 0 0

Step 11: Test the script by running it from the command window
1. Go to the currently open HyperMesh session.
2. Open the file c_channel-tcl_vector.hm.
This refreshes the HyperMesh database. The load collector and forces
you created earlier no longer exist.
3. Go to the View menu and select Command Window.
4. In the Command Window, type the following and then press Enter:
source create_force.tcl
A HyperMesh panel with a nodes selector appears.
5. Select node(s) in any manner you wish.
6. Click proceed to continue the scripts task.
A HyperMesh panel with an input field for the force magnitude appears.
7. For Magnitude =, type any number.
8. Click proceed to continue the scripts task.
The force(s) are created.

Steps 12-14 Test the script from a Utility tab button.

Introduction to HM Customization 58
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

Step 12: Create a button on the Utility tabs User page.

1. In your HyperMesh working directory, open the file userpage.mac.
If this file does not already exist, create a text file named userpage.mac.
2. On the next blank line from the top of the file, type the following
*createbutton line:
*createbutton(5, Create Force, -1, 0, 10, YELLOW,
Create a force on selected nodes, EvalTcl,
create_force.tcl)
3. Save the userpage.mac file.

Step 13: Load the userpage.mac file into the current HyperMesh
session.
The userpage.mac file can be loaded into the current HyperMesh session in a
couple of ways. By changing the User Profile the userpage.mac file gets
reloaded. While this method works, if you dont want to change the user profile,
another method is to simply reload the hm.mac file or to simply close and reopen
HyperMesh.
1. Close HyperMesh and then reopen HyperMesh.

Step 14: Test the script from the Utility menus button.
1. Open the file c_channel-tcl_vector.hm.
2. In the Utility tabs User page, click the Create Force button. A
HyperMesh panel with a nodes selector appears.
3. Select node(s) in any manner you wish.
4. Click proceed to continue the scripts task.
A HyperMesh panel with an input field for the force magnitude appears.
5. For Magnitude =, type any number.
6. Click proceed to continue the scripts task.
The force(s) are created.

Step 15: The exercise is complete. Close the HyperMesh

session.

HyperWorks 12.0

Introduction to HM Customization 59
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

Practical Exercises
Exercise 4a
Description
Using the file c_channel-tcl_vector.hm, create a HyperMesh Tcl script to
automate the following task
1) Create a component collector with a user specified name
2) Select elements and move those elements into the new component
collector.
3) Translate the elements in the new component collector a user
specified distance in the z direction.
Writing this script will make you more familiar with the general process for
creating HyperMesh Tcl scripts.
HyperMesh commands used
hm_getstring
*createmarkpanel
*clearmark
hm_getfloat

*collectorcreateonly
*movemark
*createvector
*translatemark

TCL/TK commands used

set
Hints
Be sure to do the steps in HyperMesh and then extract the appropriate
commands from the command.cmf file. Modify the commands as necessary and
be sure to clear the mark when needed.

Introduction to HM Customization 60
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0

Chapter 4: Using Tcl to Control the HyperMesh Session

Exercise 4b
Description
Using the file c_channel-tcl_vector.hm, for each element in the HyperMesh
model, build a list where the contents of the list are as follows
ELEMID {NODE1 NODE2 }
These lists should then be included in a list of lists:
{{ELEMID1 {NODE1 NODE2 } {ELEMID2 {NODE1 NODE2 }
Thus generating a record of the element information. No means of reporting this
to the user is necessary for this exercise
HyperMesh commands used
*createmark
hm_nodelist

hm_getmark

TCL/TK commands used

for
list
set
if
else

foreach
lappend
incr
elseif

Hints
The majority of this assignment will be discovering where to find information
about commands and how to apply the information you find. Be patient and use
the resources available to you, including the HyperWorks online help.

HyperWorks 12.0

Introduction to HM Customization 61
Proprietary Information of Altair Engineering, Inc

Chapter 4: Using Tcl to Control the HyperMesh Session

Introduction to HM Customization 62
Proprietary Information of Altair Engineering, Inc.

HyperWorks 12.0