Introduction
The AWR Design Environment (AWRDE) contains a built-in Scripting Development Environment (SDE) based on the SAX Basic programming language. SAX Basic is compatible with Visual Basic for Applications. Scripting automates tasks by controlling items such as schematics, EM structures, VSS system diagrams, and layout as well as retrieving data from the measurements. Python gives the user an alternate programming language in which to write scripts taking advantage of Python's access to a large body of readily available, open-source libraries. AWRDE has an extensive Application Programming Interface (API) to facilitate scripting and the API commands available with VBA can also be accessed using Python. Unlike the built-in SDE, Python is scripted using an external Integrated Development Environment (IDE) of the user's choosing. The Python executable as well the Python library modules reside outside of AWRDE, giving the user flexibility in configuring the Python environment as desired.
SAX Basic versus Python for AWR Scripting
SAX Basic and Python both have their advantages. Choosing which language to use depends on the user's experience level and the requirements that the script must perform.
Advantages of using SAX Basic within AWRDE
- For users who do not know Python.
- For users that do not know any programming languages, SAX Basic integrated within AWRDE can be quicker to develop a working script.
- Easy to create a user interface (UI).
- Can call the script from a menu pick or toolbar icon within AWRDE.
- Script can be saved within the project.
- AWR has a large body of example scripts. A developed script may already exist, or parts of an existing script can be used as a starting place.
Advantages of using Python
- For users who know Python and do not want to learn VBA.
- Access to Python libraries and utilities not available with SAX Basic
- high level math functions
- digital signal processing functions
- highly flexible plotting
- Faster compute speed on large data arrays.
- Python as a programming language is growing in popularity and as such, there is a large community in which to get help.
- Analysis in a Jupyter Notebook.
Interfacing Between AWRDE and Python
AWRDE uses the Common Object Model (COM) interface as a means of interacting with external applications. COM is a well established standard for many popular applications. One of these applications is Python through the standard win32com library.
The ability to script AWRDE functions using Python has been available for quite some time. With this method, the win32com module is imported directly into the Python script. One disadvantage of this approach is the lack of many convenience items such as code-completion.
An alternate approach for interfacing between Python and AWRDE is by means of the pyawr libary. The pyawr library incorporates win32com and adds AWR specific API functionality. Some of the features that pyawr provide include:
- Code-completion showing lists of API methods and variables associated with a particular API function
- Code-completion description and tips for the methods and variables
- Vector and array indexing that complies with Python coding conventions
- Descriptive error messages
The following is an example showing code-completion that highlights the list of variables and methods associated with the Project.Schematics function. Description associated with the Paste method is also shown
The pyawr library is installed using standard Python package installers such as pip. Once installed, the pyawr module is imported into the Python code similar to other commonly used Python modules. Unlike built-in VBA scripts, Python scripts are developed and executed from within an external IDE that supports code-completion. Some examples of IDE's that support code-completion with pyawr are Visual Studio Code (VS Code), PyCharm, and Spyder, however this list is not exhaustive.
Installation Prerequisites
Before installing the pyawr library, there are a number of required programs and libraries that need to be installed first.
Python and pip
Python 3.7 or later must be already installed. Python installer can either be downloaded from Python Org or from a distribution package such as Anaconda. The instructions here will follow using Python Org as the Python installation where pip is the primary means of installing individual modules.
Once Python is installed, you will need to add <Python install directory> and <Python install directory>/Scripts to the Windows path Environmental Variables
To verify Python and pip are installed, in a command window type
Code Block | ||
---|---|---|
| ||
python -V
pip -V |
If during a subsequent module installation process, a message is given to upgrade pip, use this command
Code Block | ||
---|---|---|
| ||
pip install --upgrade pip |
Note when using the Anaconda distribution package:
If the above commands are not recognized, then you will need to disable Python application execution aliasing
In Windows, Start > Settings > Apps > Apps & features
Click on App execution aliases
Set python.exe and python3.exe to the off position
Python IDE
There are several IDEs that support code-completion and you can use your preferred IDE if you would like. For users who do not currently use a particular IDE, Visual Studio Code is the recommended IDE, however PyCharm, Spyder, and Wing are IDEs that have been verified to work with pyawr and code-completion. The following are instructions for installing these IDES and configuring for pyawr code-completion.
VS Code
- Download from https://code.visualstudio.com, then install
- Install Python extension from within VS Code: File > Preferences > Extensions, search for Python extension for Visual Studio Code and click Install
- In VS Code, File > Preferences >Settings > Extensions > Python then scroll to Default Interpreter Path and type Python into the entry area
Pylance with VS Code is not recommended when using pyawr. If installed, please uninstall from File > Preferences > Extensions and search for Pylance
If the Anaconda distribution package was used to install Python, open the Anaconda prompt from the Windows Start Menu > Anaconda. In the Anaconda prompt window, type code
PyCharm
Download PyCharm from https://www.jetbrains.com/pycharm and install
pyawr is automatically recognized and there are no additional settings required to enable code-completion
Wing
Download Wing Python IDE from https://wingware.com and install
pyawr is automatically recognized and there are no additional settings required to enable code-completion
Spyder
- Download Spyder from https://www.spyder-ide.org and install
- In a command window, type pip install spyder-kernels
- In Spyder, Tools > Preferences > Completion and linting > Completion tab, check Enable code completion, Show completion details, and Show completions on the fly
- In Spyder, Tools > Preferences > Completion and linting> Advanced tab, uncheck Enable Kite
pyawr Installation Procedure
First install win32com and configure it for the AWR Design Environment using this procedure:
- In a command window, type
Code Block | ||
---|---|---|
| ||
pip install pywin32 |
For Python versions older than 3.9.5:
1. cd to <python install directory>/Lib/site-packages/win32com/client
2. type
Code Block | ||
---|---|---|
| ||
python .\makepy.py |
3. In the Select Library dialog box, select the AWR Design Environment that corresponds with the AWRDE version you are using
If the Select Library dialog box is blank, then ignore this step and click OK
Next, install the pyawr library:
In a command window, type
Code Block | ||
---|---|---|
| ||
pip install pyawr |
If upgrading from previous installation of pyawr.
Code Block | ||
---|---|---|
| ||
pip install --upgrade pyawr |
If upgrading and a message is displayed that requirement is already satisfied, then uninstall and install pyawr
Code Block | ||
---|---|---|
| ||
pip uninstall pyawr
pip install pyawr |
To view pyawr change history, see https://pypi.org/project/pyawr/
Example Python Script to Verify pyawr
Copy and paste the following into the Python editor
Code Block | ||
---|---|---|
| ||
import pyawr.mwoffice as mwo
awrde = mwo.CMWOffice()
NumSchem = awrde.Project.Schematics.Count
for s_idx in range(NumSchem):
schem = awrde.Project.Schematics[s_idx]
print(schem.Name) |
Open AWRDE and then open the built-in example LPF_Lumped.emp
Run the Python script
In the Python output terminal, the text output should be: LPF
It is possible to write scripts for AWRDE in Python.
AWRDE is a COM automation server and any programming language that can perform as a COM client can be used. This includes Python. With Python you will need to install the win32com.client library.
Why use Python with AWR
By far the most common question we get regarding Python is when to use Python vs. Visual Basic. Each language has advantages and disadvantages and while most scripting tasks can be performed in either, some tasks are much easier in one vs the other.
When to use Visual Basic
- You already know VB and don't know Python
- You don't know any language and what to use whatever is easiest
- Your script will need a form or other UI to interact with the user
- You want to call your script from a menu or toolbar in MWO
- You want to save your script in your project file so other users can run it
When to use Python
- You know Python and don't want to learn Visual Basic
- You need to use libraries that only run in Python
- You want to create scripts that run from a command line
- You want to do analysis in a Jupyter notebook
If you decide to use Python this page will help get you setup.
Installing win32com (pypiwin32)
Note it is recommended that you use Python version 3.7 or later with AWRDE although earlier versions may work.
The easiest way to do this is to use pip.
Code Block |
---|
pip install pypiwin32 |
...
title | sample console session... |
---|
Code Block |
---|
dane@PC-DANE C:\Python38\Scripts
> .\pip install pypiwin32
Collecting pypiwin32
Using cached https://files.pythonhosted.org/packages/d0/1b/2f292bbd74
Collecting pywin32>=223 (from pypiwin32)
Downloading https://files.pythonhosted.org/packages/a3/ca/d4011eb7f4c
3MB)
|████████████████████████████████| 9.3MB 6.4MB/s
Installing collected packages: pywin32, pypiwin32
Successfully installed pypiwin32-223 pywin32-300 |
This will install the package into your library. Once this is done the type library for AWRDE must be build. This is done by running the makepy.py script.
In a command prompt, perform the following...
Code Block |
---|
cd [python install directory]\Lib\site-packages\win32com\client
python makepy.py |
When prompted select the "AWR Microwave Office 15 (1.0)" entry in the menu. This script will then create a set of definitions that will be loaded automatically when you connect to AWRDE.
...
title | sample console session... |
---|
Code Block |
---|
dane@PC-DANE C:\Python38\Lib\site-packages\win32com\client
> python makepy.py
Generating to C:\Users\dane\AppData\Local\Temp\gen_py\3.8\5AE2215C-270C-470B-A2B6-609A964E53A2x0x15x0.py
Building definitions from type library...
Generating...
Importing module
|
Testing your installation
Here is a very simple python program that connects to AWRDE and writes out all the models in the software:
Code Block | ||
---|---|---|
| ||
# Simple script to test win32com installation
import win32com.client
awrde = win32com.client.Dispatch('AWR.MWOffice') # connect to AWRDE, load AWRDE types
for model in awrde.Models:
print(model.Name) |
Raw Connections
Connecting to a Specific Version of AWRDE
When you use this line:
Code Block | ||
---|---|---|
| ||
# Simple script to test interface to AWRDE
import win32com.client
awrde = win32com.client.Dispatch('AWR.MWOffice') # connect to AWRDE, latest installed
|
It will connect to the most recent version of the AWR Design Environment installed, said another way, the version of the last AWR Design Environment Installer run.
To call a specific version, you will add the major version number such as:
Code Block | ||
---|---|---|
| ||
# Simple script to test interface to AWRDE
import win32com.client
awrde = win32com.client.Dispatch('AWR.MWOffice.13.0') # connect to AWRDE version 13.0
|
Connecting to a Specific Instance of AWRDE
If you have multiple instances of the AWR Design Environment running at the same time, you can follow the following procedure on how to pick which instance to connect.
First, in the AWR Design Environment, you need to go into the VB scripting and run
Code Block | ||
---|---|---|
| ||
Sub Main
Debug.Print MWOffice.InstanceCLSID
End Sub |
to get the CLSID of the instance you want to connect to. This will be something like:
62F49D56-070F-4E6C-8AB9-25845CB94B9A
Then, from within python, you use:
Code Block | ||
---|---|---|
| ||
import win32com.client
obj = win32com.client.Dispatch("{CLSID}") |
...
For example
Code Block | ||
---|---|---|
| ||
import win32com.client
obj2 = win32com.client.Dispatch("{62F49D56-070F-4E6C-8AB9-25845CB94B9A}") |
...
Connecting with pyawr
The pywin32 package contains everything needed to connect to AWRDE from Python but since Python is not a strongly typed language, editors do not have the information they need to provide advanced functionality such as IntelliSense. To solve this problem, AWR has created an interface layer on top of win32com which add the type information for the AWR COM interface. With this interface, editors such as Visual Studio Code (using the Visual Studio IntelliCode and Pylance plugins), can provide type hints.
The pyawr package is available at: https://github.com/danecollins/pyawr. See the README for instructions on installation.
Install using pip
Here is an example of installing pyawr using pip from a command prompt.
Code Block |
---|
> pip install git+https://github.com/danecollins/pyawr
Collecting git+https://github.com/danecollins/pyawr
Cloning https://github.com/danecollins/pyawr to c:\users\dane\appdata\local\temp\pip-req-build-9vh7xc7x
Running command git clone -q https://github.com/danecollins/pyawr 'C:\Users\dane\AppData\Local\Temp\pip-req-build-9vh7xc7x'
Building wheels for collected packages: pyawr
Building wheel for pyawr (setup.py) ... done
Created wheel for pyawr: filename=pyawr-0.11-py3-none-any.whl size=150587 sha256=65a1040b99b78b28d817d0c8c10a96f41985cfa2f56e8d4c02948915a819da0b
Stored in directory: C:\Users\dane\AppData\Local\Temp\pip-ephem-wheel-cache-yydfdc8k\wheels\3b\75\a7\33446d1f3729be5ed4e7d0ac513b9a19aac85bfc1784618dc7
Successfully built pyawr
Installing collected packages: pyawr
Successfully installed pyawr-0.11 |
Using pyawr
When using the mwoffice.py API wrapper layer, connecting to AWRDE will be done a little differently. To connect use the CMWOffice class.
Code Block |
---|
import pyawr.mwoffice as mwo
awrde = mwo.CMWOffice() |
This will create an object of type pyawr.mwoffice.CMWOffice which has type information defined for it.
To allow connections to different versions or a specific instance of AWRDE, CMWOffice has the following arguments:
- version which is the version of AWRDE such as 13.0, 14.0 or 15.0
- If not specified then the last installed version will be invoked
- clsid which is the CLSID string as described above.
Helper Functions
pyawr also contains some helper functions which we have found quite useful when using python. The include:
...