Equations

Overview

Equations are a powerful tool that enable post processing of data, control over inputs to simulations, and definition of user-defined custom models. Two languages are available for defining equations: Engineering Language (EngLang) and Mathematics Language (MathLang).

Equations User Interface

The following image shows a typical Equations window:

The Equations window has three subwindows:

• The Variable Viewer, located on the left.
• The Script Editor, located on the upper right.
• The Command Window, located on the lower right.

The Equations window also has an associated toolbar, shown here:

The icons are:
Show or hide the Line Numbers margin
Turn autocalculate on/off
Bring up the Equation Wizard
Display Errors for this set of equations
Go - run the equations, or continue on from a breakpoint (Ctrl+G)
Stop - stop debugging (abort execution). This button is only enabled while breakpointed.
Step Into - step inside a function and break at the first line of execution in the function (F11). This button is only enabled while breakpointed.
Step Over - execute statements on the current line (F10). This button is only enabled while breakpointed.
Step Out - run until the current function ends, then break at the next line (the caller) (Shift+F11). If there is no function call at the current line, or the equation processor cannot step into the function, then all statements on the current line are simply executed. This button is only enabled while breakpointed.
Add or Remove a breakpoint from the current line (Ctrl+B)
Toggle all existing breakpoints to either the "enabled" or "disabled" state

Variable Viewer

The Variable Viewer displays any variables that currently exist in the Equations object.  If the variable is a scalar, the value is displayed.  If the variable is an array, the type and dimensions of the array are displayed.

If you right-click on any variable displayed in the Variable Viewer, you will be presented with a menu containing options to plot the variable on a graph or display it on a table.  If you wish to see the variable's value without creating a table, you can do so in the Command Window, as discussed below.

Two buttons are located at the top of the Variable Viewer window: The Equation Language button, and the Units button. The Equation Language button allows you to set the language of the Equations to be defined, as shown here:

The Units button allows you to define how the values of the variables shown in the variable list are to be interpreted when used elsewhere, such as part-parameters. If the Units are set to "Use MKS", then the value of the variables in this Equations block will be treated as MKS values. If, on the other hand, the Units are set to "Use Display", then the units will be defined where the value is actually used.

"Use Display" means to to interpret the unit of measure of a parameter as a scale factor. So, if an equation variable X=20 is used in an Inductor set to nH in Use MKS the inductor value is 20H (MKS) in Use Display the inductor value is 20nH. "Use MKS" is very important for Model portability and units portability.

We recommend you use "Use MKS" for model equations to get unit portability. Use "Use Display" for equations with tuned or gang-tuned parameter variables to make it easy to read/edit the variables.

Script Editor

The Script Editor is used to type in a sets of equation statements to be executed.  More specifically, the Script Editor window is used to:

• Post-Process data, or define variables as inputs to be used elsewhere.
• Create user-defined functions.
• Define equations inside a Model.

New If you want context sensitive help on a keyword, select the keyword and press F1 in the Script Editor.
New Use Ctrl+MouseWheel to zoom in and out on the equations Script Editor.

Command Window

The Command Window is used to execute statements line-by-line.  It interacts with the same variables that are visible to the Script Editor.  It is a useful debugging tool since the contents of a variable can be displayed here.

If an assignment statement does not end in a semicolon, the results of that assignment are outputted in the Command Window, as can be seen in the above figure.  If an assignment statement does end in a semicolon, then the dump of the contents of the result is suppressed.

Any errors or warnings caused by executing a line in the Command Window are outputted to the Command Window.

Comparing MathLang and EngLang Languages

There are two languages available to use in Equations. Which one should you choose?

Engineering Language is well suited for interacting with the workspace and for ease of use, while Mathematics Language gives you full control over array processing. In Engineering Language, it is simpler to access dataset variables, it understands Swept variables and provides some flexibility in dealing with them, understands units of measure, and is well suited for use with graphs and post-processing. Engineering language uses functions like setindep and setunit,  and it understands that Dataset.Var is a variable in the workspace.

Mathematics language is largely compatible with M-files. It has a lot of power for numeric processing. However, arrays are just sets of numbers, there is no concept of unit of measure or dependent variables, and the code is much more verbose than Engineering Language. For example, if a Linear Analysis produces a swept 2x2 S-matrix of 100 frequencies, EngLang would understand that S[2,1] means S21 for all frequencies. In MathLang, you must explicitly specify that you want all frequencies by using the syntax S[:,2,1]. Math Language allows things like writing 1+3j for a complex number, or 1/Var to invert a matrix, and it  includes tcp/ip communication functions.

The two equation languages can talk to each other's variables (and the MathLang may retain units and dependencies when you use an EngLang variable). They do not share functions because they are syntactically different (MathLang can return multiple results, for example).

Select which language is being used by an equation set by picking from the Math or Eng button pulldown in the Equation window.

Hierarchy in Equations

Equations obey hierarchy as defined by their place in the Workspace Tree.

In the example above, the value of z will be coming from another equation set (NextEquations or TopEquations) to execute without errors. The Equations engines look up the workspace hierarchy until the value of z is found, otherwise an error is reported.

In other words, in this example, if z is defined in NextEquations, then z will come from there. If NextEquations  does not define z then the Equations engine looks up another folder level to TopEquations for z .\

Equations on the same level of hierarchy should all be visible to each other.

Automatic Calculation

Historically, equations are always kept up to date, in the program. As you type it updates the left hand variable values, for example. You can disable this by turning off Automatic Calculation in equations. The tool button calculator toggles automatic calculation on and off.

If you disable Automatic Calculation , the only way to recalculate the equation is manually with the calculate button, or with the Ctrl+G keyboard shortcut. Equations that have Automatic Calculation turned off will not update during simulations. You would normally disable Automatic Calculation for Math Language equations that control hardware, for example, so the hardware doesn't get re-controlled every time a variable changes. If you disable an equation that is just a function, the function won't exist until you manually calculate the equation.

Using Engineering Language

Engineering Language is a simple programming language with structured control statements. Variable types are defined in context and matrices and arrays can be easily manipulated with equations.

• For a full description see Using Engineering Language.
• For a complete function reference see Engineering Language Function Reference

Using Mathematics Language

Mathematics Language, along with most of its built-in functions, was designed to be compatible with m-file script syntax.

• For a full description see Using Mathematics Language.
• For a complete function reference see Math Language Function Reference

Debugging Equations

A fully featured and intuitive debugger is built-in to the equation editing user interface.

Using Breakpoints and Single-Stepping

You can use the equation toolbar and the equation script editor to set breakpoints and to step through your code one line at a time. Breakpoints can be set both in equations contained in the workspace and in a model's equations (eg. sub-circuits). In all cases, evaluation of equations will be halted when a breakpoint is hit. The user may then execute statements line by line using single-stepping, abort execution, or continue execution until the next breakpoint is hit.

• Workspace Equations: to run the equations click the Go button in the toolbar. If a workspace equation is set to Auto-Calculate, they will calculate whenever something they are dependent on triggers a calculation. If any breakpoints are set, the evaluation of the equations is halted and the user interface is brought to the front, clearly marking what line of code the equation processor is currently halted at.

It is important to keep in mind that an equation block may be calculated may times due to various factors, such as a simulator changing a variable. The evaluation of the equations will halt whenever the breakpoint is hit. Typical scenarios include:

• Equations in sub-circuit models: the breakpoint will be hit once per run of the simulator except when the equation is dependent on the simulator independent variable. For example, in the linear simulator, frequency dependent equations will calculate at each frequency. For CAYENNE (time domain), time dependent equations will calculate at each T.
• Equations in a MathLang block: the breakpoint will be hit at each 'tic' of the simulator as data is delivered to the block.

Setting Breakpoints

Click the Breakpoint Margin at the line you wish to set a breakpoint at in the script editor window to toggle a breakpoint on/off. A red dot will appear when the breakpoint is on. The Breakpoint margin is located between the Line Number and Folding margins. You may also set a breakpoint at the current line by using the Ctrl+B keyboard shortcut or clicking the Add/Remove Breakpoint toolbar button.

When the equation processor hits a breakpoint, the current line it is halted at will display a yellow arrow in the breakpoint margin as can be seen in the picture below. At this point you may single-step, step-into functions, continue, or abort execution. If you step-into a function, a green arrow marks the line that the function was called from.

Using the Debug buttons on the Equation toolbar

The toolbar looks like this:

The icons relevant to the debugger are:
Go - run the equations, or continue on from a breakpoint (Ctrl+G)
Stop - stop debugging (abort execution). This button is only enabled while breakpointed.
Step Into - step inside a function and break at the first line of execution in the function (F11). This button is only enabled while breakpointed.
Step Over - execute statements on the current line (F10). This button is only enabled while breakpointed.
Step Out - run until the current function ends, then break at the next line (the caller) (Shift+F11). If there is no function call at the current line, or the equation processor cannot step into the function, then all statements on the current line are simply executed. This button is only enabled while breakpointed.
Add or Remove a breakpoint from the current line (Ctrl+B)
Toggle all existing breakpoints to either the "enabled" or "disabled" state

Using Debug Print functions

The debug print functions shown below produce lines of debug text in the Equation Debug docking window.
Please note that debug lines will only appear in the window after the simulator runs, due to current multi-threading locks.

Equation Debug docking window

The Equation Debug docking window can be shown/hidden using the Edit/View/Docking Windows/Equation Debug menu path or using the show/hide dockers button on the main toolbar. This window has a list of debug lines that your equations generate using functions described below. A sample Equation Debug Window is shown here.

Debug Functions

There are two functions available (in both Engineering Language and Mathematics Language) for writing to the Equation Debug docking window. Both functions add lines to the Equation Debug Docking Window so you can trace progress as the program runs. The code samples are written in Mathematics Language.

1. dbg_print( 'Message' )
   dbg_print( 'Message', 'Equation')
   dbg_print( 'Message', 'Equation', Line)

   prints the Message in the Equation Debug window. The Equation and Line parameters may be omitted, in which case the equation engine will attempt to auto-detect which equation set and line number called the function.

2. dbg_showvar( 'Message', Variable)

   prints Message=VariableValue in formatted output

Tips for Effective Equation Writing

As a program becomes more complex, it becomes necessary to carefully debug and test the results. Breakpoints and Debug-Print functions can be very helpful, as has already been discussed. In general, however, there are several things one should get accustomed to doing when writing equations. Below are some tips to follow when an equation is causing difficulty:

1. Make sure the input and output equations are in separate blocks
   It is a bad idea to have something like:
   c = ?4  ' value of some capacitor in the schematic
   s21  = Linear1_Data.S[2,1] ' s21 from analyzing the schematic
   The "c" is an input to a schematic; it MUST exist before Linear1_Data is ever created, so this equation block will not compile reliably. Any equation statements that call variables from analysis datasets should be in a separate block.
2. Let each line compile cleanly before typing more text
   Avoid the temptation to write a long set of statements before verifying that it works; type one line at a time and check that there are no error messages, and that the variables are showing up in the left side of the equation editor.
   
3. Before writing a large loop or in-line vector statement, check the boundary values
   Instead of writing a large loop then wondering why there are out of bounds errors or wrong calculations, first type something like:
   testA = myVector[firstIndex]
   testB = myVector[lastIndex]
   The values will display in the Variable view; this way you first verify that the initial and final values are as expected; then you can let the loop or vector operation run with more confidence.
4. Don't try to pack everything into one line of code
   It is very difficult to find the problem when there are too many calculations packed into a one line statement. By breaking up a line into several variables and lines you give yourself the chance to debug and find problems, rather than just look at a huge line that doesn't work as intended.
5. Check dimensions of variables carefully
   Always pay attention to the size and dimension of variables being used; a common pitfall is to use incorrect multiplication or division of vectors and thus accidentally create wrong-sized matrices or other unwanted results.
   
   Careless use of the "/" operator causes a 1601x1601 matrix to be created; the variables view alerts the user of the problem, so element-wise division can be used instead:
   

   Note that the functions numcols( myMatrix) and numrows( myMatrix) can be used to find the dimensions of a variable. For matrix operations, the number of columns of a left-hand operator should equal the number of rows of a right-hand operator, while for element-wise operations the dimensions should be identical.

6. Use the Command Window to output or change variable values
   See Equations User Interface for more information about the Command Window.
7. Use the online help
   The online help for equations is extensive. You can select a keyword in the equation editor and press F1 for context help on that keyword. General equation help is in the User's Guide manual Using Equations section.