IronPython Scripting
IronPython is an open-source implementation of the Python programming language which is tightly integrated with .NET. IronPython allows you to script in Python, but use .NET libraries, which is necessary since Aurora is written using .NET.
Using the Aurora Scripting window, you can script with IronPython by creating a new IronPython file. The IronPython file will have the .py extension, but it cannot be used interchangeably in another Python interpreter. This .py script file will only work in the Aurora Scripting window since it references .NET dlls for Aurora Scripting.
If you want to reference other IronPython or Python modules in your script, make sure the .py file you want to reference is in the same directory as your current script file. Since IronPython uses Python 2.7, instead of Python 3, make sure any modules you reference use Python 2.7.
We do not recommend using third party Python modules for Aurora IronPython scripting. First, many third party Python modules are written for Python 3, these modules must be compatible to run in Python 2.7, since that is what IronPython is written in. Second, some of the well-known ones, such as NumPy, are created using CPython, which the IronPython interpreter cannot read.
NOTE: Any module that uses CPython, such as SciPy or NumPy, cannot be used for IronPython. If you want to use third party modules, such as NumPy, you must script Aurora in Python using another Python application, such as Visual Studios or PyCharm. Here is a link describing how to script Aurora from another Python application, Scripting Aurora from Visual Studio with Python.
Python 2 vs Python 3
IronPython uses Python 2.7, instead of Python 3. This means that the Aurora IronPython scripts must be written in Python 2.7. The syntax of Python 2.7 is almost exactly the same as Python 3, however here are the three main differences to keep in mind.
1. Integer Division
NOTE: IronPython scripting in Aurora will round down division results to integers, unless you use decimal points when dividing.
In Python 2, if you write a number without any digits after the decimal point, it rounds your calculation down to the nearest whole number. For example, if you’re trying to perform the calculation 5 / 2, the result will be 2 (due to rounding). You would have to write it as 5.0 / 2.0 to get the exact answer of 2.5.
However, in Python 3, the expression 5 / 2 will return the expected result of 2.5 without having to worry about adding those extra zeroes.
2. Print Function
In Python 2, using print “Hello World” is the same as using print (“Hello World”). Using print (with and without the parenthesis) will both work in Python 2. However, in Python 3, using print without parenthesis is not supported.
3. Default Strings
In Python 3, strings are Unicode by default. In Python 2, strings are stored as ASCII by default. You have to add a “u” if you want to store strings as Unicode in Python 2.
Creating a New IronPython File
To create a new IronPython file in Aurora, use the New button in the Scripting ribbon and select IronPython File from the dropdown menu.
When the new IronPython script is created, the first lines you will see will be declaring the AC and ADS objects. Use these objects to access Aurora scripting functions, just like coding in VB or C#.
These AC and ADS Aurora scripting functions are written for .NET. For most Aurora scripting functions, they will have the same syntax, i.e., AC.LoadProjectWaitForDBRead("C:\\AURORAxmp\\Nodal_10Bus_Example.apz").
This call is the same whether you are coding in VB, C#, or IronPython.
In VB and C#, you use a function where you can skip certain parameters to implement the default, like ADS.AddNewStudyCase(“New Study Case”, , , , , , "New Change Set 1, New Change Set 2"). In Python scripting in Aurora, you cannot skip the parameters like shown above, you must put in values, i.e., ADS.AddNewStudyCase("New Study Case", True, False, 0, "", "", "New Change Set 1, New Change Set 2").
NOTE: Python 2.7 does not have built-in functionality for enums. Consequently, the common enums like Parameters.SimOptions and ADS.DataType, will not work with Intellisense and no dropdown will appear with autocomplete when typing. If you type out the name of the enum, it will still work when you run the script, but Intellisense will not autocomplete the enum when typing.
NOTE: Many Aurora scripting functions use arrays as parameters. However, Python has no built-in functionality for arrays, only lists. Therefore, we must use the .NET Array capability given to us through IronPython when calling certain Aurora scripting functions.
Array Example:
paramList = [Parameters.SimOptions.StartDateYear, Parameters.SimOptions.EndDateYear, Parameters.SimOptions.RunUsingStudyCaseList]
valueList = [2020, 2021, True]
paramArray = Array[Parameters.SimOptions] (paramList)
valueArray = Array[object] (valueList)
results = ADS.UpdateProjectParameters(paramArray, valueArray)
The function, ADS.UpdateProjectParameters, takes in an array of Parameters.SimOptions and an array of objects. To correctly use this function in Python, you must cast the Python List to a .NET Array.
If we tried to call ADS.UpdateProjectParameters(paramList, valueList), the function doesn't recognize the Python List type and it errors out. Thus, those parameters can be cast as a .NET Array for ADS.UpdateProjectParameters to work correctly.
The returned object of ADS.UpdateProjectParameters is a Boolean Array. Thus, the “results” variable will be a .NET Array of Booleans.
The .NET Array is under the .NET System dll, which IronPython references. That is why you can access the .NET Array functionality. However, if you tried to run this .py script using another Python application, it would not access or be able to read the .NET System dll and the script would error out. This is why IronPython is necessary when scripting Aurora.
Debug Windows
The two Debug windows that will be different when using IronPython than when using VB or C# is Output and Locals.
Output:
When using the Python print() function, the output will appear in the Output window.
Locals:
When you look at the Locals window when running an IronPython script, you will see a lot extraneous variables, which comes from references to the .Net System dll. You can ignore these variables. Actual local variables in your script will start with AC and ADS.
Aurora IronPython Script Example:
AC = ComApplication()
ADS = ComDataSet()
projectName = "C:\\AURORAxmp\\Nodal_10Bus_Example.apz"
AC.LoadProjectWaitForDBRead(projectName)
paramList = [Parameters.SimOptions.StartDateMonth, Parameters.SimOptions.EndDateMonth, Parameters.SimOptions.RunUsingActiveEdits]
valueList = [Parameters.StartDateMonth.July, Parameters.StartDateMonth.August, True]
paramArray = Array[Parameters.SimOptions] (paramList)
valueArray = Array[object] (valueList)
results = ADS.UpdateProjectParameters(paramArray, valueArray)
AC.Run()
print("Simulation Finished!")
Scripting
