Using Python to Create Functions, Models & Scripts
        |
Contents
Working with Mathematical Expressions
Mathematical expressions are widely used throughout EM.Cube for:
- Defining dependent variables based on existing independent variables
- Defining custom output parameters based on standard output parameters
- Defining design objectives based on standard or custom output parameters
- Performing operation on and modifying existing data files
- Generating new data files from the ground up
- Defining new custom curve and surface CAD objects
- Defining custom terrain objects in EM.Terrano's Terrain Generator
- Defining custom temporal excitation waveforms in EM.Tempo
Mathematical expressions are indeed text strings made up of reserved names like variable or standard output parameters in combination with operators and functions. You can use the basic arithmetic operators: addition "+", subtraction "-", multiplication "*", division "/", as well as the right and left parentheses "(" and ")" as delimiters. For raising powers, you can either use the power function pow(x,y) or simply use the symbol "^", e.g. "x^y". The Pi number π = 3.1415926... is denoted by "pi" as a reserved name, and letter "e" stands for the Euler number e = 2.7182818... or the base of natural logarithm.
 |
All of EM.Cube function names, standard and custom output parameter names and variable names are case-insensitive. |
EM.Cube's Function Library
EM.Cube provides an extensive library of standard and advanced mathematical functions as well as some special functions related to signal processing, filters and RF design. You can see a list of this functions by clicking the Functions button 
of the Simulate Toolbar or selecting Menu > Simulate > Functions... or using the keyboard shortcut Ctrl+I.
Click here to see a List of Library Functions.
Creating Custom Functions Using Models
Besides the standard mathematical functions and a large set of library functions, EM.Cube allows you to create custom functions of your own in a number of ways. User defined functions in EM.Cube are called "Models". A model is essentially a function of one or more variables defined by way of a "Method" that is saved to an ASCII text file. EM.Cube currently provides four types of models:
A functional model is the simplest type of model and consists of a mathematical expression in terms of one or more arguments or variables. The mathematical expression can involve any combination of the variables, basic operations and standard and library functions. An tabular model takes a data file with X and Y columns and provides a interpolator for the intermediate values. A Python model is a Python script that takes one or more arguments or variables and returns a real value.
An HDMR model is an advanced type of interpolation model that uses the simulation data generated by one of EM.Cube's simulation engines. HDMR models are constructed at the end of a special sweep simulation based on the High-Dimensional Model Reduction (HDMR) method and will be discussed in more detail later.
Models can be used anywhere in EM.Cube just like standard and library functions. They can be used to define dependent variables in the Variables dialog. Or you can use models in expressions that replace the numeric values of object properties in property dialogs.
Defining a New Functional Model
Follow the procedure below to define a new model in EM.Cube:
- Open EM.Cube's Models Dialog by clicking the Models button
of the Simulate Toolbar or selecting Menu > Simulate > Models... or using the keyboard shortcut Ctrl+L.
- To add a new model, click the Add button to open the "Add Model" dialog. Choose one of the three options: Functional, Tabular or Python. Keep in mind that HDMR models are built differently through a special sweep process.
- In the Model Definition dialog, type in the list of the arguments of your model separated by commas, e.g. x,y,z, ...
- Choose a name for your new model. This same name will also be given later to a ".DAT" data file associated with your new model. Therefore, choose a unique name for your model that distinct from your project's existing data files.
- In the case of a functional model, enter the mathematical expression as a function of the arguments you defined earlier.
Once you close the model definition dialog, a new entry is added to the Models List. A functional model file with a .UDM file extension is created in your project's folder. It is recommended that you use the same name for functional models and their model files. The example in the figure below shows a two-variable function called Sinc2D with two arguments x and y. From this point on, you can use your new function Sinc2D(x,y) everywhere in EM.Cube as you would use any standard or library function. You can always edit a model using the Edit button of the Models dialog. For example, you can change the mathematical expression of a functional model or add new arguments to it.
| |
As soon as you define any new model, all of its arguments are added to EM.Cube's Variables List as new variables that you can use elsewhere. |
 |
 |
 |
 |
Using Data Files to Define Models
Sometimes it is difficult to express a desired function as a mathematical expression. For example, you may have conducted an experiment to measure a quantity Y as a function of an observable X and have created an X-Y table. Then you want to use these data as a function. EM.Cube allows you to define tabular models for this purpose with built-in interpolation capability. If you select the Tabular option of the "Add Model" dialog, a new dialog opens up where you can use the Browse button to explore your folders and pick the desired data file. After you select and open a data file for your tabular model, it automatically fills out most of the model definition dialog's fields. The dialog shows how many columns and how many rows (data samples) your original data file has. It is assumed that all the columns except for one are independent variables and only one column is the dependent variable. In case you have more than one independent variable, you can specify the number of arguments for your new model, meaning that it can be fewer than the number of the independent variables. You can also designate the column number which contains the dependent variable values in the box labeled Output Column. You have to choose between two Interpolation Type options: Linear and Cubic (spline) interpolations.
Similar to the case of functional model, you can choose any names for your tabular model as well as its associated model file, which has a .IDM file extension. It is highly recommended that you choose a different name for your tabular model than that of the original data file if you intend to keep the original data file for later use. The example below shows a data file called MyData.DAT which was used to create a tabular model called MyDataModel together with a model file called MyDataModel.IDM. As you can see from the figure, the original file has two columns and 74 data samples. The argument is called Theta. Once your new tabular model is added to the Models List, you can use the new function MyDataModel(x) everywhere in EM.Cube just like any standard or library function. Note that you cannot modify the definition of a tabular model after its creation. If you open the Edit Model dialog, you will only see a list of its arguments with their value ranges.
 |
 |
Using Python Scripts to Define Models
If you have installed the Python scripting language on your computer, you can use Python scripts to define your custom models. In this case, you can build sophisticated models involving conditional statements or recursive loops. If you select the Python option of the "Add Model" dialog, a new dialog opens up where you can enter your Python script. First you need to define the argument(s) of your model. Then choose a name for your model and its associated model file. A Python script file with a .PY file extension will be added to your project's folder. In the box labeled Python Script, you can enter your Python code. Make sure that your code contains at lease one "return" statement to generate a value for your custom function. The figure below shows a Python model called MyTestPyModel that has one argument x and calculates the sinc function and returns sin(πx)/(πx). Once your new Python model is added to the Models List, you can use the new function MyTestPyModel(x) everywhere in EM.Cube just like any standard or library function. You can always edit a Python model using the Edit button of the Models dialog, e.g. you can change the contents of the Python script, add new arguments to the model, or change the returned value.
 |
 |
What Can You Do with Your Models?
EM.Cube models, whether functional, tabular, Python or HDMR, can be used just like any standard or library function in many scenarios:
- For defining a dependent variable in Variables dialog
- For building expressions that can replace the numeric values of object properties
- For defining custom curves or surfaces in Curve Generator and Surface Generator, respectively
- For defining custom waveforms for EM.Tempo's excitation sources
- For creating new data in Data Generator
- For performing mathematical operations on data in Data Manager's spreadsheets
In all of the above applications, you instantiate a model using a similar syntax as a regular standard function: "Mode_Name(x,y,…)", where x, y, … are the model's arguments.
Besides the above applications, you can also access models directly from the Models Dialog. In this dialog, you can select any model and use the Edit button to modify the definition or attributes of the selected model. You can use the Windows Notepad to open the model file and view its contents. You can also perform three important operations with any model in EM.Cube:
- Parametric Sweep
- Optimization
- HDMR Sweep
As mentioned earlier, all the arguments of a model are added automatically to the Variables List, and can be used as regular independent variables. You can run a parametric sweep of a model in the same way you run a parametric sweep using any of EM.Cube's simulation engines. In this process, successive evaluations of the model are made for all samples of the sweep variable(s). The results are written to an ASCII data file with a .DAT file extension that bears the same name as your model. To run a parametric sweep of a model, first select it from the Model dialog's list and then click the Sweep button of this dialog. This opens up the Parametric Sweep Settings Dialog, just as you will see in a regular parametric sweep in any of EM.Cube's computational modules. Follow the same typical sweep procedure and define your sweep variables from the list of available independent variables, which in this case must be the arguments of your model. At the end of the sweep simulation, open the Data Manager to view or plot the output data file.
Click here to learn more about Running Parametric Sweep Simulations.
In a similar way, you can perform an optimization on your models. In this case you have to define a objective that includes the name of your model (as an output parameter) or any expression of it. You define your objectives in the Objectives Dialog. To run a optimization of a model, first select it from the Model dialog's list and then click the Optimize button of this dialog. This opens up the Optimization Settings Dialog, just as you will see in a regular optimization in any of EM.Cube's computational modules. In this dialog, you need to define your optimization variables from the list of available independent variables, which in this case must be the arguments of your model. Note that your model can have several arguments and you can run a multivariable optimization. At the end of the optimization process, assuming that the optimizer algorithm converges, the current value of the optimization variable in the Variables List will be updated with its computed optimal value.
Click here to learn more about Running Optimization Simulations.
You can also generate an HDMR model from the numerical evaluations of any of your models. To run a HDMR sweep of a model, first select it from the Model dialog's list and then click the HDMR button of this dialog. This opens up the HDMR Settings Dialog, just as you will see in a regular HDMR sweep in most of EM.Cube's computational modules. In this way you can create a new compact HDMR model for your model of a different type.
Click here to learn more about Running HDMR Sweep Simulations.
| |
Running an optimization of your structure using one of EM.Cube's simulation engines can be a very time consuming and memory-intensive task. Instead, you may consider developing a model for a certain response or quantity of interest in your structure as a function of one or more structure parameters and then run an optimization of that model far more efficiently. |
