3-1

Ansoft HFSS宏汇编语言初步

Richard RemskiApplications Engineer, Central Region

(Rev B to include V7 Commands, July, 1999)

本文的目的

3-2

Provide a Basic Intro to Functioning in the Ansoft Macro Language within HFSS

Macro Access and Execution

General and Command Syntax

Import/Export to Database Files

Wizard Customizable Macro Dialogs

Example(s) and Recommendations

宏培训纵览

3-3

Macro AccessRecording, Viewing, and Executing Macros

General SyntaxPositions and Vectors in CommandsVariables and Expressions: Why two different beasts?

Command SyntaxCommand Construct Structure and Examples

Using a DatabaseThe key to data import and export from HFSSDatabase Operations (reading, writing results)

Wizard Macro DialogsMore User-Friendly, Graphical Input RequestsTying to Variables, Functions, and Secondary Macros

A Programming WalkthroughFrom Recorded Drawing Session to Full MacroStyle Recommendations

What and Why?

3-4

What is a Macro?A macro is a series of commands that are grouped such that they can be executed at once, just like a mini-program within HFSS.Macros can ask the user for feedback during execution; read and write to and from external data files; aid the development, alteration, and post-processing of projects, etc.

Why should I waste my time learning Macros?Automation of Model Construction for Similar ‘Families’ of ProjectsAutomation of Calculation Steps within Projects (e.g. PML tensor development)Automation of Frequently-Used Post-Processing/Field Calculator TasksParametric Studies and OPTIMIZATION

3-5

Ansoft HFSS 宏汇编语言入门

Recording and Executing Macros

General Macro Usage

3-6

Macro BasicsUnless otherwise specified, macro files assumed to be in the current project directoryMacros are ASCII text-only files, and do not require an extension

However, extensions (e.g. *.mac) make them easier to findCommands are NOT Case Sensitive (FileRecord = filerecord)

Macros can be edited via any text editorMacros can operate on ANY subprocess within HFSS

Model Creation: From 3D Modeler to Materials, Boundaries, Soln. Setup, Execution, and Matrix Data/Plot.Post-Processor Macros a little different (Post3D is not a ‘child’process but a stand-alone application)

Macros cannot ‘cross’ project boundaries without helpOptimization, sequential runs w/ different boundaries, etc all accomplished using ONE project

3-7

运行HFSS的选项

Recording and Accessing Macros: I

3-8

Opening the Command PromptExecute HFSS with command prompt toggle

<path>/hfss8/hfss -cmdwind y projectname.pjtPuts command prompt in Executive window

Hotkey Access: CTRL-F4Works in All Modules (3D Modeler, Materials, Sources/Boundaries,Mesh3D, MatrixData, MatrixPlot, Post3D)MAY CAUSE PROBLEMS in some modules (Materials, MatrixData, MatrixPlot, Mesh3D(?))

Menu Access: Macro under File MenuAlso Available: View Command Prompt

Note: Command Prompt Need Not Be Open to Record, End Recording of, or Execute Macros!!!

(Feedback during Execution MAY Require Prompt)

Recording and Accessing Macros: II

3-9

在HFSS非活动状态执行宏To Open an HFSS project and run a macro on it:

<path>/hfss8/hfss -macexec macroname projectname.pjt

To Open an HFSS project, run a macro on it, and exit when complete:

<path>/hfss8/hfss -macandexit macroname projectname.pjt

Note: Both above assume that macro is in the project folder, and project is in the ‘default’ project directory

<pathtoexecs>/hfss8/hfss -macexec<pathtomacro>/macroname -<pathtoproject>/projectname.pjtis full command

Note: Model Must Be Properly Written for External OperationRemember to use appropriate ‘Launch’ commands, Initiate using all necessary CommandSets

Recording and Accessing Macros: III

3-10

Executing with HFSS Active: Three Methods

METHOD 1: (No command prompt open)CTRL-F3 opens window requesting “Enter Filename to Exec:”Provide macro filename (and path if necessary)

METHOD 2: (Command Prompt open)Type FileExec “<path>macroname” in Command Prompt field

METHOD 3 [PREFERRED]: Select “Macro→ Execute” from File Menu of most modules

Recording and Accessing Macros: IV

3-11

Recording with HFSS Active: Three MethodsMETHOD 1: (No command prompt open)

CTRL-F1 opens window requesting “Enter Filename to Record:”CTRL-F2 stops recording, saves file

METHOD 2: (Command Prompt open)Type FileRecord “<path> macroname” in Command Prompt FieldType FileRecStop to end recording, save file

METHOD 3: Select “Macro→Record” from the File menu of most modules

May optionally record in “Append” mode to add to pre-existing file

RECORDING HIERARCHY NOTE:Recording in Executive Window Records EVERYTHING except Post3D and Mesh3D commands.Beginning Recording in any other module (e.g. Sources/Boundaries, Post3D) records only commands executed in THAT module.

3-12

Ansoft HFSS 宏汇编语言入门

Macro Syntax

General Macro Syntax

3-13

Macro Language Echo Formats In CommandsHow HFSS Parses Commands; Use for Numerical-Only Lines

[1, 2, 3] is a 3D Position or Vertex Location<10, 20, 30> is a 3D Vector (or delta between vertices) Quantity“blahblahblah” is a String Quantity. To list multiple strings, use Braces: { “yadda” “yadda_yadda” “yadda_yadda_yadda” }Example Macro Lines:

Box [0,2.5,3] 10 10 10 “cube”

SweepVec { “profile” } <2, 4, 6>

Macro Language Programming FormatsFor Use to Apply Variables to Commands

POS3 (x y z) is a 3D Position or Vertex Location using VariablesVEC3 (xdist ydist zdist) is a 3D Vector Quantity using VariablesExample Macro Lines:

Box POS3 (x y z) 10 10 10 “cube”

SweepVec { “profile” } VEC3 (xdist ydist zdist)

Variables and Expressions I

3-14

VariablesVariables have names and values. Available variable types are LONG, DOUBLE,and STRING. Variable names ARE case-sensitive. (a1 ≠ A1)Variables are created with the ‘Assign’ command, and may have basic mathematical or comparison operations performed on them

GT, GE, LT, LE, EQ, NE: ComparisonsMUL, DIV, ADD, SUB: Basic Math OperationsAND, OR, XOR: Logical OperatorsOperation Syntax is: <operation> <first quantity> < second quantity>

ONLY VARIABLES MAY BE USED DIRECTLY IN COMMANDS

ExpressionsExpressions appear similar to variables, but include algebraic evaluation capability. Expressions are always enclosed in “ ” and are text (string) dataExpressions are created with the ‘ExpAssign’ command and have full math operations available using the ‘ExpEval’ command

Expression on right side of ‘=‘ in ExpEval lines must be pre-ExpAssign-ed Examples:

ExpAssign “const” 3ExpEval “calculation=20*const”

Expressions by themselves CAN NOT be Arguments in Drawing Commands‘Assign’ a variable with the result (evaluation) of an expression, or just use the result of the ExpEval“expressionname” instead

Variables and Expressions II

3-15

A Short List of Math Functions Available with Expressions:

+, -, /, *,**sin(x), cos(x), tan(x)asin(x), acos(x), atan(x)sinh(x), cosh(x), tanh(x)exp(x), log(x), ln(x)pow(x,y) [xy] (also x**y)sqrt(x)abs(x)

Parentheses Understood for Longer Operations (Use with care)As a Programming Style recommendation, don’t put too much of a formula on any one line. The possibility of error increases in entry, plus it’s harder to understand by others you may share the macro with. It’s also much harder to debug.

Variables and Expressions III

3-16

Assigning Expressions and VariablesVariable Examples

Assign var1 10

Assign namevar “drawing_object”

Assign diel 2.432

Assign result ExpEval “z”

Assign usrval GetDouble “Enter desired height”

Assign switch GetLong “Enter 1 to continue or 2 to exit”

Assign gimmename GetString “Enter name for part”

Variable Examples with Operations: Same CommandAssign sum ADD a b

Assign diff SUB a b

Assign divide DIV a b

Assign multiply MUL a b

Assign longer DIV (MUL a b) (SUB a b)

Note Ordering of Operation and Quantities!!

Variables and Expressions IV

3-17

Assigning Expressions and Variables, cont.Expression Examples

ExpAssign “var1” 10

ExpAssign “nameexp” “drawing_object”

ExpAssign “diel” 2.432

ExpAssign “result” var1

ExpAssign “usrval” GetDouble “Enter desired height”

ExpAssign “switch” GetLong “Enter 1 to continue or 2 to exit”

ExpAssign “gimmename” GetString “Enter name for part”

Expression Examples with Operations: Uses ExpEvalExpEval “sum=a+b”

ExpEval “dif=a-b”

ExpEval “div=a/b”

ExpEval “mul=a*b”

ExpEval “longer=a*sin(b)/pow(a,b)”

Variables and Expressions V

3-18

Assigning Expressions and Variables, cont.Assigning Values Between Expressions and Variables

Assign putinvar ExpEval“expr”

ExpAssign “expr” putinexp

Singular or Combined Use in Drawing OperationsRectangle [0,0,0] 0 5 10 “5_by_10_rect” 1 (no var or exp)Rectangle POS3 (xvar yvar zvar) 0 5 10 “5_by_10_rect” 1

Rectangle POS3 (ExpEval“xexpr” yvar zvar) 0 5 . . .

Rectangle [0,0,0] normvar sizeu sizev “rect” 1

Rectangle [0,0,0] 0 ExpEval “sizeu” . . .

Rectangle [0,0,0] 0 5 10 namefromuser 1

Rectangle [0,0,0] 0 5 10 ExpEval “nameexpression” 1

Rectangle [0,0,0] 0 5 10 “rectangle” cvr

. . .

…clearly, a number of options to use both exist

Drawing Command Syntax

3-19

Although Drawing Commands are all Different, they Share Some Common Syntactic Rules

Rectangle [0, 3, 2.5] 0 14 23 “rect1” 1

Normal is 0 for X axis, 1 for Y axis, 2 for Z axisWidth and Height follow in order (if Norm is X, Width is Y and Height is Z, etc.)Covered Value toggles from 1 (yes, make sheet) to 0 (no, make outline)

Box [1, 2, 3] 10 20 30 “airvolume”

Generally, 2D commands are similar and 3D commands are similar

Command Starting Coord.

Normal Width

Height

Name Covered Sheet?

Command Starting Coord.

SizeX SizeY

Height

Name

Other Useful Commands

3-20

A Short List of Frequently-Used Non-Drawing Commands Includes:

Assign, ExpAssign - assign variables and expressionsGetLong, GetDouble, GetString - request user input for above assign and expassign operations via Command PromptExpEval “name” - return the value of the “name” expressionWhile, If, and Repeat, all concluded with End

Select “part” - select an object (to list multiple parts uses braces, e.g. Select { “part1” “part2”} )Deselect * - deselect all selected objects (Select * also available)FitAllViews - resize all windows to show all geometryEcho “text” - writes the “enclosed” text back to the user (may also be followed by a variable to be echoed in the Command Prompt# text - the “#” symbol specifies information following as a commentRename “oldname” “newname” - self-explanatoryRecolor “partname” r g b - recolor part, where r, g, and b are values from 0 to 255 for red, green, and blue content of desired color

3-21

Ansoft HFSS 宏汇编语言入门

Command Constructions

Command Constructs I

3-22

Exist to Allow Programming of Conditional OperationsDo not ‘mimic’ normal drawing, HFSS usage commands

Available Command Syntax Options Include:‘IF’ a condition exists, do the following, then ‘END’

Once-Through Command Construct‘ELSE’ Allows Command Instructions for ‘false’ result on original ‘IF’ statement.

‘REPEAT’ an operation a specified number of times, then ‘END’

Cycles Through For a Specified Number of Times‘WHILE’ a condition exists, do the following, then ‘END’

Cycles Through Until the Condition is no longer met.Warning: CAN RESULT IN ENDLESS LOOPSFrequently used in conjunction with one of above or math operations to change exit status

Command Constructs II

3-23

IF Command Construct Examples:Assign pick GetLong “Enter 1 for Bones or 2 for Spock:”

If EQ pick 1

Echo “Dangit Jim, I’m a doctor, not a programmer!”

End

If EQ pick 2

Echo “Live long, and prosper.”

End

--or--

Assign test GetString “Want to See a Program Error (y/n)?”

If EQ test “y”

ExprEval “error=10/0”

Else

Echo “Aww...you’re no fun...”

End

V7 Required

Command Constructs III

3-24

REPEAT Command Construct Example:

Assign num 10

Repeat 10

Echo “Self-Destruct Procedure Commencing in “ num “...”

Assign num SUB num 1

End

Echo “Kaboom.”

Command Constructs IV

3-25

WHILE Command Construct Example 1:‘IF’ Based Exit Criteria

Assign initial 0

While EQ initial 0

Echo “I’m running in circles!”

Assign input GetString “Can I quit yet? (y/n)”

If EQ input “y”

Assign initial 1

Else

Echo “You’re the boss…starting another lap.”

End

End

Echo “I’m glad that’s over with; I’m dizzy.”

V7 Required

Command Constructs V

3-26

WHILE Command Construct Example 2:Math Based Exit Criteria

Assign unk GetDouble “Give me a number greater than pi:”

While LT unk 3.141592654

Echo “Value Entered is NOT greater than pi.”

Echo “Did you skip geometry classes a lot?”

Assign unk GetDouble “Please re-enter a value:”

End

Echo “Thank You. Now I have more pi than you.”

Note that in Both the IF and Math Exit Criteria Examples, the means for Exiting the Loop Were Within the Loop Itself, but the Variables (or Expressions) were Defined OUTSIDE the Construct First.

3-27

Ansoft HFSS Macro Language Primer

Databases

Database Operations I

3-28

A ‘database’ is a text data file which can accompany and enhance operation of a MacroDatabase can be created manually ahead of time

Read by Macro as Input DataRead as ‘formatted’ or ‘raw’ database

Database can be modified by macroCan increment ‘counters’ in database for repeated operationsCan feed-back user-entered variables into database for storage

Database can be wholly created by macroSame uses as aboveAlso for storing Post-Processor output before next iteration, etc.

Database location defaults to same as Macro Path unless otherwise specified!Database Fields are Space Delimited

Tabs are also acceptable

Database Operations II

3-29

Database Formats“Raw” is just rows and columns of unspecified data

WG_Name Broadwall NarrowwallWR90 0.9 0.4WR75 0.75 0.375WR62 0.622 0.311

“Formatted” Database includes Row, Column Count information:

4 3WG_Name Broadwall NarrowwallWR90 0.9 0.4WR75 0.75 0.375WR62 0.622 0.311

Num Rows Num Columns

Database Operations III

3-30

Database Field NumberingA single entry in a database is a ‘field’Fields are numbered from zero, left to right and top to bottom(EXCLUDING row/column count, if present)

4 3WG_Name Broadwall NarrowwallWR90 0.9 0.4WR75 0.75 0.375WR62 0.622 0.311

Highlighted Entry is Field 2, 1

Row 0

Row 1Row 2

Row 3

Column 0 Column 1 Column 2

Database Operations IV

3-31

Databases must be identified in Macro Prior to Using its Contents

Database Exists Prior to Macro Initiation:ImportDatabase command imports a database fileCommand should be used to import database information to a Variable for use:

Assign db_file ImportDatabase “c:/hfss6/data1.dat”

For ‘raw’ database, use ImportRawDatabaseOnce identified, information can be read from and/or written to the database

Database to be Created by the Macro:NewDatabase command creates a new database

NewDatabase 12 - numeric value is number of columnsAgain, use Assign command to identify a name for the database

Assign exported_results NewDatabase 12

Database Operations V

3-32

Reading Information from Databases:DatabaseGetColumns db_name - returns # of columnsDatabaseGetRows db_name - returns # of rows

Example Usage (to perform an operation once per row in a database):

Assign counter DatabaseGetRows db_partlist

Repeat counter

. . .

End

DatabaseGetField db_name X Y - returns specific field entry, where X is the row number and Y is the column number of the desired field

Example: DatabaseGetField wg_data 2 1

Example Usage: To put database field into variable for drawing:Assign height DatabaseGetField wg_data 2 1

Assign width DatabaseGetField wg_data 2 2

Rectangle [0, 0, 0] 0 height width “wg_profile” 1

Remember count starts at row/column ZERO!!!

Database Operations VI

3-33

Writing Information To Databases:DatabaseAddRow db_name - adds a row to the bottom of an

existing databaseDatabaseSetField db_name X Y - sets a field (row X, column

Y) to the value specifiedExample Usage:

Assign freq SzgDataSolnFreq “S_1” 1

Assign db_flist NewDatabase 1

DatabaseAddRow

DatabaseSetField db_flist 0 0 freq

Saving Created/Updated Databases:ExportDatabase db_flist “d:/macros/databases/db1.dat” “yes”

NOTE: UNTIL EXPORTED, CHANGES ARE NOT SAVED!!!!

Filename and Path Overwrite Switch (“yes” or “no”)DB Name (in macro)

3-34

Ansoft HFSS Macro Language Primer

Wizard Customizable Macro Dialogs

3-35

When the Command Prompt Just isn’t Enough...

For More Complex Macro Operation, a Pop-Up Wizard Dialog offers better User Interaction

Radio Buttons, Checkboxes, and Push ButtonsDefault Field Values and Automatic Range Testing PossibleHelp on Demand Available

Wizard Dialog Construction

3-36

Begin with CreateWizard CommandCreateWizard “wiz_name”All subsequent commands within the wizard must use the same “wiz_name”

Execute via RunWizard “wiz_name”Runs the dialog, performing all operations to set up fields, buttons, etc. with the same wizard name.All defined fields set up as variables in the macro parser

Or Execute as Variable:Assign run_it RunWizard “wiz_name”

Returns “0” if Wizard is CancelledReturns “1” if Wizard is completed with “OK”

Post-Execution CleanupDestroyWizard “wiz_name” deletes all variables associated with the wizard and frees names for other use (Note: also deletes contents of variables!)If ‘Cancel’-ed rather than ‘OK’-ed, must StopWizard“wiz_name” first!

Wizard Dialog Execution Defaults

3-37

RunWizard command may pre-set Default Options for Buttons, fields, etc.

SYNTAX:

RunWizard “wiz_name” { “fieldname:condition” “...” }

“fieldname” is the name of a field, button variable, etc. from the wizard being executed (described in more detail ahead)“condition” is the desired default condition, which may be eithercheck, disable, or hide (again, usage described in more detail ahead)Multiple “fieldname:condition” pairs are included as a string list.

Wizard Dialog Help

3-38

Help Button Automatically Enabled if ‘AddWizardHelp’command used:

AddWizardHelp “wiz_name” “Help Text if Button Pressed”

Help Text may be multiline, with line feeds identified by \nMacro command lines may also have ignored line feeds, as long aspreceded by ‘\’EXAMPLE MACRO LINES:

AddWizardHelp “wiz_name” \“ The following text will appear in a new pop-up window\n\if the user presses the HELP button at the bottom right\n\corner of any Wizard dialog box for which the Add- \n\WizardHelp command has been written.\n\\n\Extra Blank lines as separators can be added as shown\n\above.”

Note Extra Space following open quotes helps text alignment. Spaces preceding subsequent lines’ text are ignored.

Help Pop-up can only be exited by Clicking “OK”‘Cancel’ help wouldn’t make much sense

Wizard Dialog Text

3-39

Text Within a Wizard Dialog Added with ‘AddWizardText’command

AddWizardText “wiz_name” “Text for Wizard Window”

As with AddWizardHelp, Text may be displayed on multiple lines as well as incorporated in multiple macro lines using ‘\n’ and ‘\’, respectivelyUseful to provide instructions without requiring Help access.EXAMPLE MACRO TEXT USAGE:

Assign units GetUnitNameAssign wiztext StrConcat “Current Drawing Units are “ unitsAddWizardText “wiz_name” \“ This wizard will ask the user for a frequency to perform\n\a waveguide cutoff calculation on some geometry\n\drawn previously. To do so it might be useful to remind the\n\user that the current active drawing units will be taken into\n\account.\n\”

AddWizardText “wiz_name” wiztext

Wizard Dialog Entry Fields

3-40

Data Entry Fields can take multiple data types (only one type per field!)Types available include: String, Long, Double, Pos2, Pos3, Vec2, Vec3, String_List, Double_List

Syntax:AddWizardField “wiz_name” “var_name” “TYPE” “Prompt Text to show in Wizard Dialog:”

SetWizardFieldDefault “wiz_name” “var_name” “Default Value”

SetWizardFieldRange “wiz_name” “var_name” MINVAL MAXVAL

Example:AddWizardField “wiz1” “width” “double” “Enter the Desired WG Width”SetWizardFieldDefault “wiz1” “width” “Must be between 0 and .65”SetWizardFieldRange “wiz1” “width” 0 .65

Note that the ‘default’ value was a STRING providing extra info, despite the requirement the user entry be a DOUBLE decimal.A recommended value applicable to the type of variable could also be provided (good for demonstration-type macros!).SUGGESTION: If using Ranges, use user-friendly variable names, since invalid entry warnings will use the variable name.

Wizard Dialog Buttons

3-41

Three Types of Buttons are Available:Checkbox:

Allows multiple options to be selectedMay be Toggled On and Off

Pushbuttons: Immediately Execute some command/actionRadio Buttons:

May be Toggled On and OffOne and only one may be selected at a time

Command Syntax:AddWizardButtons “wiz_name” “type” WIDTH {“var_names”} {“label_text”} {“command_actions”} “ORIENTATION”

“type” is push, check, or radioWIDTH is a number (character length) to set button size/spacing“var_names” are variables to be associated to each button“label_text” is what appears in the dialog beside/on each button“command_actions” may be a single command per button or empty“ORIENTATION” should be “vert” or “horiz”

Wizard Dialog Buttons, Example

3-42

Example Command Lines:AddWizardText “wiz1” “Select whether to deembed using Zpi, Zpv, or Zvi:”AddWizardButtons “wiz1” “radio” 10 {“wpi” “wpv” “wvi”} {“Use Zpi” “Use Zpv” “Use Zvi”} {“Fileexec ‘calcpi.mac’” “Fileexec‘calcpv.mac’” “Fileexec ‘calcvi.mac’”} “horiz”

AddWizardText line provides contextual description for short button names.Each button, when selected, will result in Fileexec command on a different secondary macro

Could hard-wire a SINGLE macro command to the button if desiredIf multiple commands should result from a button selection, must be within secondary macroNote use of ‘single-quotes’ inside string list containing FileExeccommands

Optionally, Button Selection Can Result in Variable Assignment instead.

Leave {“Command_Actions”} string list empty [ {} ]Selected button will have corresponding variable assigned to a value of 1; unselected buttons will have variable assigned to value of 0 (zero).

Wizard Dialog Buttons, Additional Functions

3-43

Within Submacros Activated by a Button Selection, two additional Commands Available:

SetWizardControlState permits activation/deactivation, showing/hiding other wizard fields.

Can Alter Defaults set up in original RunWizard command!!SYNTAX: SetWizardControlState “wiz_name” “field_name” ENABLE_VAL VISIBLE_VAL CHECK_VAL

ENABLE_VAL: 0 disables, 1 enablesVISIBLE_VAL: 0 hidden, 1 visibleCHECK_VAL: 0 unchecked, 1 checked (checkboxes only)

SetWizardControlText permits changing the text of a button once it is pressed.

SYNTAX:SetWizardControlText “wiz_name” “variable” “New Button Text”

“variable” is the variable associated with the button of interest“New Button Text” will replace earlier button label text from original AddWizardButtons command.

Wizard Dialog Validators

3-44

Wizards can be used to Execute a Subsequent Command

AddWizardValidatorCmd “wiz_name” “Command”

Command must NOT require any arguments!Command will execute when wizard “OK” button is pressed.

Wizards can perform Expression operationsAddWizardValidatorExpr “wiz_name” “val_var”“Expression”

EXAMPLE:AddWizardValidatorExpr “wiz1” “val1” “log((x**2)/4)=10”

Expression will be Evaluated when “OK” button is pressed.If Expression is untrue, Wizard Dialog will Remain Active.

Wizard Dialog Notes

3-45

Wizard Variables no longer Available after Wizard execution ‘stopped’

Good idea to use ‘interim’ variable names in Wizards, then assign fields to more permanent ones which will be maintained outside the wizard.

Usage of Wizards Biases Programming Technique toward ‘main macro’ and ‘submacros’ rather than one long program

Wizard Button Selections can only execute one command line, so if multiple operations are desired that should be a “Fileexec”to call another macro.

3-46

Ansoft HFSS Macro Language Primer

Programming Walkthrough and Recommendations

3-47

Pulling it All Together: A Programming Example

Write a Macro that Can Create a Coaxial Binomial Quarter-Wave Transformer, of Order n = 0 through 4

Allow User Designation of Starting, Ending ImpedanceAllow User Designation of FrequencyAllow User Designation of Order (0 thru 4 only)Allow User Designation of Center Conductor DiameterUse a Database to Store Binomial Coefficients for CalculationsUse Pre-Recorded Drawing Commands to Gather Starting Syntax

For this Exercise, We’ll do only do the 3D Modeling StepsMaterial, Boundary Assignment will be in a later exercise (much later, as I haven’t written it yet!!)

Programming Preparation I

3-48

Pre-Programming ThoughtsWhat Variables Will I need Supplied by the User?

FrequencyOrderCenter Conductor DiameterStarting Impedance and Line LengthEnding Impedance and Line Length

What Internal Variables/Expressions Might I Need?Outer Diameter Calculation from Center Diameter and DielectricIntermediate Impedance ValuesCoefficient Variables (for Binomial Coefficients to calculate intermediate Impedance values)Length for each Section

Programming Preparation II

3-49

Pre-Programming Thoughts, Continued.What Math Functions Will I Need?

Standard Operations (*, +, -, /) in many placesPowers for intermediate impedance calculation:

Exponents for outer conductor diameter calculation:

What Drawing Commands Will I Need?CylinderSplit (for symmetry)FitAllViews (for visual feedback)

nkM

Lk Z

ZZZ2

000 ⎟⎟

⎠

⎞⎜⎜⎝

⎛=

⎟⎟⎠

⎞⎜⎜⎝

⎛

⋅= 600 rZ

eabε

Programming Preparation III

3-50

Pre-Programming Thoughts, Continued.Where should I position the model?

For ease of Split Operations (for symmetry) and Field Post-Processing, put coax axis along a principle coordinate axis. We’ll use X.Let’s plan on starting at X = 0, then extending positive from there.

Model Starts at X = 0Input Section will end at X = (input length)Each Transformer section will end at X = (n*lambda/4 + inputlength)Output part will end at X = (n*lambda/4 + inputlength + outputlength)

Programming Preparation IV

3-51

Pre-Programming Thoughts, Continued.What information should the Database Contain?

Binomial coefficients can be easily obtained from Pascal’s Triangle, or formulaically, but formula requires factorialsBinomial coefficients are summed to find constant Mk

Perhaps have database contain values Mk across rows for each order n?

1

1 1

1 2 1

1 3 3 1

1 4 6 4 1

Row # is Order (starting with 0)

Pascal’s Triangle

Mk = C1 + C2 + ... + Ck ,

where k = 1, 2, ... n+1.

Thus, for n = 3

M1 = 1 M3 = 7

M2 = 4 M4 = 8

5 6

0 1 0 0 0 0

1 1 2 0 0 0

2 1 3 4 0 0

3 1 4 7 8 0

4 1 5 11 15 16

Database Contents

Row & Col. Count

First Column is Order ‘n’

Following Rows have Mkvalues, with k = column #

(Zeros are place-holders only)

Programming Preparation V

3-52

Pre-Programming Thoughts, Continued.What should my primary Command Construct be?

Order ‘n’ directly related to number of sections (n+1)Probably ‘Repeat’ structure most valid for transformer section creation:

Representative Syntax:Assign n GetLong “Enter the order for the transformer?”

Repeat ADD n 1

{Operations for each section}

.

.

.

End

Enough Planning; Let’s Program!!

Macro Programming I

3-53

Create the Database File:Contents as shown below, single-space delimitedName file “coeff.dat”Place file in root directory of data disk (eg d:/ )

5 6

0 1 0 0 0 0

1 1 2 0 0 0

2 1 3 4 0 0

3 1 4 7 8 0

4 1 5 11 15 16

Macro Programming II

3-54

Pre-Record a Starting Macro FileOpen a New Project, and enter Draw moduleOpen Command Prompt with CTRL-F4Type FileRecord “d:/qtrw.mac”

Perform the following drawing commands:Draw a Cylinder with Axis along the X axisSplit it, keeping negative half only, along the XZ plane

Exit Recording by typing FileRecStop in Command PromptExit Project (no save necessary)Open File d:/qtrw.mac to View and Prepare for EditingStarting Macro Results shown on next slide (your specific coordinates, sizes, etc. may vary)

Macro Programming III

3-55

Pre-Record a Starting Macro File, cont.Results of Pre-Recording:

UseCommandSet "Solve Setup"UseCommandSet "Emissions Setup"UseCommandSet "MatrixData"UseCommandSet "hfss"UseCommandSet "Default"UseCommandSet "mod3view"UseCommandSet "mod3proj"UseCommandSet "Modeler3"UseCommandSet "Generic Module"Cyl [-10, 0, 0] 0 5 20 "cyl1" 12 [10, 5, 0]FitAllViewsSplit 1 1 { "cyl2" }

Command Set Loading can now be kept for 3D Modeler Macro

Split Syntax for XZ plane (Y normal), keep neg. half

Cylinder Creation (note extra point at end; defines first edge vertex)

Macro Programming IV

3-56

Begin Macro Editing: Opening CommentsAdded Lines Shown in Boldface

# The following macro will create a binomial quarter-wave transformer# of order 0 to 4 to transform a user-provided input and output# characteristic impedance at a given frequency. It will request user# input of Zin, Zout, frequency, center conductor diameter, and# dielectric constant.# Last edited: 07 - 21 - 99#UseCommandSet "Solve Setup"UseCommandSet "Emissions Setup"UseCommandSet "MatrixData"UseCommandSet "hfss"UseCommandSet "Default"UseCommandSet "mod3view"UseCommandSet "mod3proj"UseCommandSet "Modeler3"

. . .

Macro Programming V

3-57

Pre-assign ‘abortsignal’ variable to allow later termination if necessaryCreate a Wizard to Gather User-Entered Values

Assign abortsignal 0## Request User Entries Via a Wizard#CreateWizard "inputs"SetWizardTitle "inputs" "Quarter-Wave Transformer Parameters:"AddWizardField "inputs" "wiz_n" "LONG" "Enter the Order (0 to 4):"AddWizardField "inputs" "wiz_zin" "DOUBLE" "Enter input coax impedance:"AddWizardField "inputs" "wiz_zout" "DOUBLE" "Enter output coax impedance:"AddWizardField "inputs" "wiz_lin" "DOUBLE" "Enter input coax length:"AddWizardField "inputs" "wiz_lout" "DOUBLE" "Enter output coax length:"AddWizardField "inputs" "wiz_ctr" "DOUBLE" "Enter center conductor diameter:"AddWizardField "inputs" "wiz_f" "DOUBLE" "Enter design frequency (GHz):"#

Note All Wizard field entries must be Variables, not ExpressionsUse names specific to the Wizard Only; we’ll assign these entries to other variables and expressions as appropriate after running wizard.

Macro Programming VI

3-58

Set Acceptable Ranges for Each Variable to Prevent Illegal Entries

SetWizardFieldRange "inputs" "wiz_n" 0 4SetWizardFieldRange "inputs" "wiz_zin" 1 377SetWizardFieldRange "inputs" "wiz_zout" 1 377SetWizardFieldRange "inputs" "wiz_lin" 1e-5 1e+5SetWizardFieldRange "inputs" "wiz_lout" 1e-5 1e+5SetWizardFieldRange "inputs" "wiz_ctr" 1e-5 1e+5SetWizardFieldRange "inputs" "wiz_f" 1e-3 1e+3#

Eliminates Need for IF loop checking of inputs via Command Prompt to assure dimensions are all positive valuesNote that Frequency range also reinforces instructions to enter a value in GHz.

Macro Programming VII

3-59

Use Wizard Buttons to Offer Three Symmetry Options:

AddWizardText "inputs" "Indicate below whether or not to utilize symmetry:"AddWizardButtons "inputs" "radio" 40 {"full" "half" "quarter"} {"Use No

Symmetry" "Use Half Symmetry" "Use 1/4 Symmetry"} {} "horiz"## note: above 'addwizardbuttons' info is all on one line, word-wrapped!#

Buttons for full, half, or quarter symmetryNo command action entered, but null string list ( “{}” ) still presentHorizontal Button Arrangement in Wizard

Macro Programming VIII

3-60

Execute the Wizard as a Variable:Assign runinputs RunWizard "inputs"If EQ runinputs 0

DestroyWizard "inputs"Echo "Inputs Aborted"Assign abortsignal 1

EndIf EQ runinputs 1

Assign n wiz_nExpAssign "zin" wiz_zinExpAssign "zout" wiz_zoutAssign l_in wiz_linAssign l_out wiz_loutExpAssign "ctr" wiz_ctrExpAssign "freq" wiz_f

If Wizard ‘Cancel’ button is pressed, Wizard is Destroyed, and our Abortsignal variable is changed to 1If Wizard ‘OK’ button is pressed and all fields have acceptable range values, we begin Assigning (or ExpAssigning) them to use for the rest of the macro.

Macro Programming IX

3-61

Assign Correct Symmetry Option, Close Wizard, and Open ‘if’loop to contain remainder of macro:

If EQ full 1Assign sym 0

EndIf EQ half 1

Assign sym 1EndIf EQ quarter 1

Assign sym 2EndStopWizard “inputs”DestroyWizard “inputs”

End## Continue with rest of macro only if inputs were not aborted!#If EQ abortsignal 0

Note button variable names used to pick symmetry optionIf wizard was run, must ‘stop’ before ‘destroy’-ing.

Macro Programming X

3-62

Begin Calculations with Lambda/4 DeterminationPut calculations that will be used by many subsequent steps nearthe front of your macroHead Calculation Sections with comments to aid troubleshooting and editing

#

# Calculate wavelength in dielectric#ExpAssign "conv" GetUnitConvExpEval "lambda=.3*conv/freq"Assign qtrl MUL .25 ExpEval("lambda") Echo "Quarter-wave calculated to be" qtrl

Echo results back often. Although these will appear in the Command Prompt stack too quickly to be read during use, they provide feedback to assist you in troubleshooting the macro if anon-fatal error (e.g. a formula mistake) occurs.If we wanted to feedback user-critical information, we could create new Wizards to display the data more effectively.

GetUnitConv is a macro command which returns the value to multiply the model’s present dimensions by to convert them to meters. This allows the calculation to be dimension independent.

Note also we asked for the ‘freq’in GHz, therefore we use .3/freq instead of 3E+8/freq.

Macro Programming XI

3-63

Calculate Outer Diameter from provided Impedance for Input and Output Sections

Put calculations that will be used by many subsequent steps nearthe front of your macroHead Calculation Sections with comments to aid troubleshooting and editing

#

# Calculate outer dia for input and output lines#ExpEval "temp1=zin/60"ExpEval "temp2=exp(temp1)"ExpEval "outd_in=ctr*temp2"ExpEval "temp3=zout/60"ExpEval "temp4=exp(temp3)"ExpEval "outd_out=ctr*temp4"Echo "Input section outer diameter is" ExpEval "outd_in"Echo "Output section outer diameter is" ExpEval "outd_out"Assign outr_out DIV ExpEval "outd_out" 2Assign outr_in DIV ExpEval "outd_in" 2

Echo Results after Completion

Macro Programming XII

3-64

Let’s FINALLY do some actual Drawing Commands!Again, start section with Comments

#

# Draw input line outer and center conductor#Cyl [0, 0, 0] 0 outr_in l_in "input" 18 POS3 (l_in outr_in 0)Assign inr DIV ExpEval "ctr" 2Cyl [0, 0, 0] 0 inr l_in "ctr_input" 18 POS3 (l_in inr 0)FitAllViews

Performing a FitAllViews after every (few) drawing commands is also recommended as it aids visual feedback to the programmer and user.Regarding Cyl Syntax: the additional vertex point defined at the end of the command defines from which point the facetization of the curved cylindrical face into rectangles shall begin. Note it is a radius away along one of the two radial dimension components from our cylinder base, and the length of the cylinder away in the axial direction.

Macro Programming XIII

3-65

Conditional Routine: Split Geometry if Symmetry IndicatedAgain, start section with CommentsThis refers back to the request for a ‘use symmetry’ response at the beginning of the macro

#

# Split for symmetry if requested (note this section can be re-used# with name changes only for the main loop and output sections)#If GE sym 1

Split 1 1 { "input" "ctr_input" }EndIf EQ sym 2

Split 2 1 { "input" "ctr_input" }End

Note that the indent for the line within the command construct is not necessary, but is recommended for clarity of macro editing.Remember the ‘split’ command syntax: the first number entered is the plane normal, the second indicates which half (or both) to keep.

Macro Programming XIV

3-66

Import Database and Prepare to use Contents for main construct loop

Note ImportDatabase command includes full path to database file.Actual contents of database will be used within command construct loopNote initialization of counter variable before loop construct begins

#

# Begin Main Command Construct for Transformer Sections## Load Database, Initialize Variables Needed#Assign data ImportDatabase "d:/coeff.dat"ExpAssign "nexp" nExpEval "denom=pow(2,nexp)"Assign count 1## Begin Loop which will produce each section#. . .

Macro Programming XV

3-67

Main Command Construct Loop‘Repeat’ Loop for order of transformer plus one

Repeat ADD n 1

## Get coefficient, use to calculate section Zo#ExpAssign "M" DatabaseGetField data n countEcho "Coefficient" ExpEval("M") "read."Echo "Denom is" ExpEval ("denom")ExpEval "power=M/denom"ExpEval "temp4=zout/zin"ExpEval "zsec=zin*pow(temp4,power)”

Note use of ‘DatabaseGetField’ to get the appropriate valueBegin preparing for transformer section drawing by finding necessary characteristic impedanceAgain, using Echo statements permits easier debugging in the event of non-fatal errors.

Macro Programming XVI

3-68

Main Command Construct Loop, continuedContinue loop, calculating outer diameter for current section and starting and stopping X axis points

## Calculate outer diameter for current section Zo#ExpEval "t1=zsec/60"ExpEval "t2=exp(t1)"ExpEval "outd_sec=ctr*t2"Echo "Current section outer diameter" ExpEval "outd_sec"Assign secouterrad DIV ExpEval "outd_sec" 2## Calculate starting and ending position along X axis#Assign numsofar SUB count 1Assign currseclengths MUL numsofar qtrlAssign startX ADD currseclengths l_inAssign endX ADD startX qtrl

Note creation of separate ‘Numsofar’ variable one less than count instead of using ‘n’. This is because we want this variable to increase with the count, rather than stay fixed.

Macro Programming XVII

3-69

Main Command Construct Loop, continuedContinue loop, drawing current section of transformer and splitting if requested

## Draw inner and outer conductor cylinders in this location#Cyl POS3(startX 0 0) 0 secouterrad qtrl "tempout" 18 POS3 (endX secouterrad 0)Cyl POS3(startX 0 0) 0 inr qtrl "tempin" 18 POS3 (endX inr 0)## Split inside and outside sections if symmetry was requested#If GE sym 1

Split 1 1 { "tempout" "tempin" }EndIf EQ sym 2

Split 2 1 { "tempout" "tempin" }End

Note use of ‘temporary’ names for these parts. This is done because string variables representing user-assigned names cannot be used in the Split command. These names will be changed in the next few lines prior to concluding this loop.Note also that the split is being performed within the loop for each part, as this way it only needs to be defined for the temporary name. If performed after the loop it would require that we save a list of all the part names, which is more difficult.

Macro Programming XVIII

3-70

Main Command Construct Loop, concluded (finally!)Conclude Loop, renaming objects and ‘End’ing to initiate return to ‘Repeat’ statement

## Tricky part: create a NAME for the current section with its number# concatenated to the end of the string#Assign currout StrConcat "transform" countAssign currin StrConcat "inner" countRename "tempout" curroutRename "tempin" currin## Increment counter, then end loop#Assign count ADD count 1FitAllViews

End

‘StrConcat’ command concatenates strings together, in this case adding a number (‘count’) to the end of transform and inner.Remember to increment your counter at the end of the loop, or it will create identically sized and positioned objects n+1 times.

Macro Programming XIX

3-71

Finishing touches and ExitDraw final output section, split if required, and we’re finished.

## Done with loop. Draw exiting section#Assign lastX ADD endX l_outCyl POS3 (endX 0 0) 0 outr_out l_out "output" 18 POS3 (lastX outr_out 0)Cyl POS3 (endX 0 0) 0 inr l_out "ctr_output" 18 POS3 (lastX inr 0)## Split output pieces if symmetry requested#If GE sym 1Split 1 1 { "output" "ctr_output" }

EndIf EQ sym 2Split 2 1 { "output" "ctr_output" }

EndFitAllViews#End

Echo "Macro Complete."

Again note use of ‘FitAllViews’ to resize visual area for user feedback.It’s nice to give the user a final text feedback to let them know the macro has finished executing, hence the last ‘Echo’ command.Final ‘End’ statement concludes ‘If’ loop with ‘abortsignal’ test.

Macro Programming XX

3-72

Example Result of Running Macro40 ohm to 120 ohm, 4th order quarter-wave transformer.

Input and output lengths both 0.5 cmCenter conductor diameter 0.2 cmDesign frequency 3.5 GHz

Macro Programming XXI

3-73

Example Result of Running MacroSolution Results

4 passes, 0.028 ending Delta-S (mostly phase per above), 03:11 total solution time on Pentium II 350 MHz w/512 MB RAM3508 tetrahedra final mesh

Characteristic Impedance

S-Parameters from Final Pass (dB and Phase)

Delta-S, Final Pass (dB and Phase)

Macro Style Guide

3-74

Suggestions When Writing Macros For Customers/Other UsersComment, Comment, Comment! There is no such thing as too many comments!!! (yadda, yadda, yadda...)

Include in header the name of the author, the last modified date, and the level from which the macro should be run (e.g. outside HFSS, from main executable, from draw, etc.). Instructions for execution are also usefulInclude the name of any required database files and their locations as specified in the macro, if any.

Frequent use of FitAllViews for Visual FeedBack in Drawing OperationsFrequent use of Echo Commands to provide written feedback of calculation results, feedback during user-entered variable entry, etc.

Even with Wizards for Data Entry/Results reporting, Echoes are very helpful for Debugging purposes

Don’t put too much of a complex formula one one program lineThis also aids debugging

Complete Macro “Murphy-Proofing” is impossible, but try to anticipate common entry errors when asking for user-entered variables

Set Appropriate Field Ranges for Inputs requested via Wizard dialogsUse IF and/or WHILE loops to test entries (and force re-entry if incorrect) requested via Command Prompt

专注于微波、射频、天线设计人才的培养 易迪拓培训 网址：http://www.edatop.com

H F S S 视 频 培 训 课 程 推 荐

HFSS 软件是当前最流行的微波无源器件和天线设计软件，易迪拓培训(www.edatop.com)是国内

最专业的微波、射频和天线设计培训机构。

为帮助工程师能够更好、更快地学习掌握 HFSS 的设计应用，易迪拓培训特邀李明洋老师主讲了

多套 HFSS 视频培训课程。李明洋老师具有丰富的工程设计经验，曾编著出版了《HFSS 电磁仿真设计

应用详解》、《HFSS 天线设计》等多本 HFSS 专业图书。视频课程，专家讲解，直观易学，是您学习

HFSS 的最佳选择。

HFSS 学习培训课程套装

该套课程套装包含了本站全部 HFSS 培训课程，是迄今国内最全面、最

专业的HFSS培训教程套装，可以帮助您从零开始，全面深入学习HFSS

的各项功能和在多个方面的工程应用。购买套装，更可超值赠送 3 个月

免费学习答疑，随时解答您学习过程中遇到的棘手问题，让您的 HFSS

学习更加轻松顺畅…

课程网址：http://www.edatop.com/peixun/hfss/11.html

HFSS 天线设计培训课程套装

套装包含 6 门视频课程和 1 本图书，课程从基础讲起，内容由浅入深，

理论介绍和实际操作讲解相结合，全面系统的讲解了 HFSS 天线设计

的全过程。是国内最全面、最专业的 HFSS 天线设计课程，可以帮助

您快速学习掌握如何使用 HFSS 设计天线，让天线设计不再难…

课程网址：http://www.edatop.com/peixun/hfss/122.html

更多 HFSS 视频培训课程：

两周学会 HFSS —— 中文视频培训课程

课程从零讲起，通过两周的课程学习，可以帮助您快速入门、自学掌握 HFSS，是 HFSS 初学者

的最好课程，网址：http://www.edatop.com/peixun/hfss/1.html

HFSS 微波器件仿真设计实例 —— 中文视频教程 HFSS 进阶培训课程，通过十个 HFSS 仿真设计实例，带您更深入学习 HFSS 的实际应用，掌握

HFSS 高级设置和应用技巧，网址：http://www.edatop.com/peixun/hfss/3.html

HFSS 天线设计入门 —— 中文视频教程

HFSS 是天线设计的王者，该教程全面解析了天线的基础知识、HFSS 天线设计流程和详细操作设

置，让 HFSS 天线设计不再难，网址：http://www.edatop.com/peixun/hfss/4.html

更多 HFSS 培训课程，敬请浏览：http://www.edatop.com/peixun/hfss

`

专注于微波、射频、天线设计人才的培养 易迪拓培训 网址：http://www.edatop.com

关于易迪拓培训：

易迪拓培训(www.edatop.com)由数名来自于研发第一线的资深工程师发起成立，一直致力和专注

于微波、射频、天线设计研发人才的培养；后于 2006 年整合合并微波 EDA 网(www.mweda.com)，

现已发展成为国内最大的微波射频和天线设计人才培养基地，成功推出多套微波射频以及天线设计相

关培训课程和 ADS、HFSS 等专业软件使用培训课程，广受客户好评；并先后与人民邮电出版社、电

子工业出版社合作出版了多本专业图书，帮助数万名工程师提升了专业技术能力。客户遍布中兴通讯、

研通高频、埃威航电、国人通信等多家国内知名公司，以及台湾工业技术研究院、永业科技、全一电

子等多家台湾地区企业。

我们的课程优势：

※ 成立于 2004 年，10 多年丰富的行业经验

※ 一直专注于微波射频和天线设计工程师的培养，更了解该行业对人才的要求

※ 视频课程、既能达到现场培训的效果，又能免除您舟车劳顿的辛苦，学习工作两不误

※ 经验丰富的一线资深工程师讲授，结合实际工程案例，直观、实用、易学

联系我们：

※ 易迪拓培训官网：http://www.edatop.com

※ 微波 EDA 网：http://www.mweda.com

※ 官方淘宝店：http://shop36920890.taobao.com

专注于微波、射频、天线设计人才的培养

官方网址：http://www.edatop.com 易迪拓培训 淘宝网店：http://shop36920890.taobao.com