This appnote shows different ways of using equations in ADS:

  • simple equations “on the fly” in the ADS data display and
  • user defined functions (code) for use in data display or optimization for target definitions.

The re-use of custom equations/functions is discussed, and how to store them to your workspace library. The example workspace is available for download here.

Simple equations “on the fly”

This is what you have seen and used many times: In the data display, equations are added “on the fly” to apply math functions to simulation data. The newly created data is then available in the “Equations” list.

The advantage is that it’s really easy to create such equations. Re-use is possible by saving the entire data display as a “template” and re-use that exact data display later.

However, this method is not convenient if we want to compare multiple data sets, which all need to be calculated with the same equation. In this case, it is much better to define a customized math function, and then process all the data sets using that user defined math function. This is quite easy, as we will see next.

User defined function – What is that?

For math functions that we need often, we can create a user defined function by writing code in the text editor. Don’t be afraid of that, this is very similar to the equations created in the data display, just stored into a text file, and with some header to declare the function name and parameters.

Once defined, this can be used similar to ADS built-in functions in data display, or for measurement equations and optimization goals in the schematic.

For the inductance calculation above, we can split the math into two custom functions.  The first function extracts the series path impedance from 2-port data:

defun Zseries_from_S2P (S)
{
decl aZ = stoz (S);
decl aZseries = aZ(1,1) – aZ(1,2) – aZ(2,1) + aZ(2,2);
return aZseries;
}

S are the 2-port S-parameters passed into the function
stoz is a pre-defined ADS function that calculates the Z-parameters from S-parameters. The advantage of using this (instead of enabling Z-Parameter output in ADS frequency sweep control) is that it also works with imported S-parameter datasets where no Z-parameter data is available in the dataset.
aZseries is a variable that holds our calculated data, and then returns this as the functions result.

The second function calculates the series inductance from the 2-port S-parameters. As you can see, it internally calls the first function.

defun Lseries_from_S2P (S)
{
decl aOmega = 2*pi*indep(S);
decl aLseries = imag(Zseries_from_S2P (S)) / aOmega;
return aLseries;
}

You might wonder why this uses indep(S) instead of using the freq variable for frequency. Again, the reason is that this also works with imported S-parameter datasets, where no freq variable exists in the dataset.

You might also wonder why the variable names have the a prefix. The reason is that all variables defined here are visible to the ADS data display, and the ADS data display will automatically rename variables in the data display if a duplicate name is found. So we better use a “unique” name in the custom equation code that doesn’t conflict with variable names in the data display.

Where are user defined functions stored?

There are different ways to make user defined functions available. If you search the ADS online help for “User-Defined Functions” in the “Introduction to Measurement Expressions” chapter, you will find instructions how to add them to your local ADS installation, so that they are available to all your ADS projects.

However, if I store my function definitions in my local installation, and you download my ADS example project, the project will not work properly on your computer. You would need to also install my functions to your ADS separately. Sounds complicated, right?

There is a better way to share projects with user defined functions: We can also store the file directly in the ADS project, and have ADS load it automatically, as described below. This way, the workspace can be shared and custom functions are immediately available, with no need to install them manually. The loading mechanism is the same as used for ADS design kits, and also used in my Customized AEL Artwork examples.

Including user defined functions in a workspace library

ADS provides a mechanism to load and execute certain files on startup, when a workspace library is opened. We will use that to load our user defined functions.

ADS always checks for a file “eesoflib.cfg” in the library directory and is able to execute a “boot” file defined there. In that file, a special variable tells ADS where to search for the custom equation (expressions) file. We can choose any name for that directory, and then specify that in eesof_lib.cfg.

For the expressions directory location, I would suggest to place it inside the library directory.
The name of the equation file is hardcoded into ADS and always the same: “dk_defined_fun.ael

With these settings, the custom equations file should be loaded when ADS loads the workspace (to be more specific: the library). You should then see a compiled file (*.atf) if everything was successful. If the *.atf file is missing, something went wrong and your *.ael was not loaded, or had errors when ADS tried to load and compile it.

To force re-loading the workspace (including our code), we can use the file history from the menu: File > Recent Workspaces. Always do this when you have changed the code, to re-load the latest code version. It is not necessary to close the project before re-loading it.

An example workspace

In the attached example workspace, all these equation methods are shown. You will notice that custom equations, as well as equations on the fly, are used in the schematic to define an optimization goal.

Note the left MeasEqn, which creates two 2-port results (Smeas and Smodel) from the 4-port simulation, for use in the optimization goal and easier postprocessing in the data display.

Download UseEquationDemo workspace (73kB)