Using Sonnet's Macro Language

Sonnet provides a macro language that enables you to add and/or modify elements within a Sonnet project file (*.sonx). This is useful for users who wish control and automate Sonnet analyses using a programming language of their choice, such as Python, Ruby, MATLAB, C#, JavaScript, PowerShell, etc. The programming language is used to write a script that generates a Sonnet macro command file.

The Sonnet macro command (*.smc) file is a text file containing a list of macro commands. Sonnet's macro interpreter, runmacro, located in the Sonnet installation's "bin" directory, reads the Sonnet macro command file and executes the commands. It can perform operations on Sonnet projects, such as opening/saving a project, adding elements to the circuit, changing values of variables, and modifying other circuit element properties.

The following commands assume that the Sonnet bin directory is in your PATH. If it is not, you will need to specify the full path to runmacro.

The syntax of runmacro is as follows:

runmacro <Sonnet_macro_command_file(s)>

where <sonnet_macro_command_file(s)> is the Sonnet macro command file(s) containing a list of macro commands. For example,

runmacro my_macro.smc

runmacro my_macro1.smc my_macro2.smc my_macro3.smc

You may also add a "-v" to the command for a verbose output. This can be helpful for troubleshooting. For example,

runmacro -v my_macro.smc

A Usage Example

The following flowchart shows an example of how you might use Sonnet's macro language in an optimization loop.

In this example, most of the steps are performed using your script and do not utilize Sonnet's macro language. The two steps that require Sonnet's macro language are indicated with a "*":

• Create macro file that changes values: A Sonnet macro command file (*.smc) is generated by the script.
• Run macro: The macro file is executed using the runmacro command.

The example macros contains several simple macro command files and may be accessed using the Example Browser.

Macro IDs

Each element of a Sonnet project is identified by a unique Macro ID. This Macro ID is used in most macro commands to uniquely identify an element in your project. For example, the Macro ID of a polygon could be "polygon3".

Generating Macro IDs

If you have an old project that does not have Macro IDs, you may load it into Sonnet 19 and Macro IDs will be automatically generated. You may also use the following runmacro command to generate Macro IDs:

runmacro -idgen <input_file> <output_file>

For example,

runmacro -idgen dstub.sonx dstub_w_macroids.sonx

The above command will read the file dstub.sonx, add Macro IDs, and save the results to the file dstub_w_macroids.sonx.  

Viewing Macro IDs

You may view the Macro ID of most items by editing the properties of the item. The macro ID will be displayed, usually in the lower-left corner of the window. For polygons and vertices, select the polygon or vertex, and the Macro ID is displayed in the status bar. When creating new items using a dialog box, sometimes "macro ID: <not assigned>" is displayed. If this occurs, close the dialog box and reopen it and the macro ID will be displayed.

In addition, you may show or hide Macro IDs by changing a Project Editor preference. Select Edit > Preferences > [General] and either enable or disable the Display Macro IDs checkbox. This preference is enabled by default.

Compatible Versions

Sonnet's macro commands are compatible with Sonnet project files created by Sonnet version 19 or above. These files have a .sonx extension. Legacy files (*.son) are not supported.

---