Introduction

The StressCheck automation framework outlined in this COM API overview includes the following basic, but fundamental, concepts:

• Importing the StressCheck application object library
• Starting a new StressCheck application
• Opening a parametric StressCheck Handbook file
• Modifying existing parameters to change model definition
• Solving a linear analysis using p-extensions
• Extracting engineering quantities (stress, strain) to a StressCheck table
• Transferring data from StressCheck tables to an Excel spreadsheet and/or Python console
• Ending the StressCheck session
• Script execution

These concepts are intended to show how the loading, solving, and post-processing of pre-defined StressCheck models (e.g. Handbooks) is accomplished via COM API automation. Excel VBA and Python v3.8 will be used to demonstrate each of the above concepts.

Importing the StressCheck Application Object Library

The StressCheck application object library contains all StressCheck objects, along with the associated methods and properties, needed to develop, solve, and post-process StressCheck models on the fly.

In order to create a new instance of StressCheck for COM API automation, the StressCheck application object library must be registered (automatically performed during installation) and available to be imported during script runtime or as part of a custom .NET project.

Excel VBA

In Excel VBA, the user must simply locate and check the latest StressCheck Application X.X Object Library under Tools > References within the VBA Editor (Developer tab > Visual Basic or right-clicking on a Sheet tab and clicking View Code):

Once the StressCheck.tlb (Type Library file) is properly referenced, the user can now write VBA scripts, modules and class modules to include calls to StressCheck’s API.

Python

There are several console applications for executing Python commands and Python scripts (.py files), such as PythonWin (aka pywin32, Figure 2). To get started, the user must first import the win32com.client library (standard with PythonWin installations):

Once imported, the user can write Python code to call the StressCheck API.

For details on ensuring Python is properly configured to instance StressCheck and other application API’s, refer to Python’s Getting Started Guide. For best results, it is recommended to install the latest PythonWin application, as well as the NumPy and Pandas libraries.

Creating a New StressCheck Application

To create a new instance of a StressCheck application, we need to tell Windows to construct a new StressCheck.Application object and assign this object to a named variable. We can then use this variable to communicate with the active StressCheck application. This step can be accomplished several ways, depending on the programming language/environment.

Excel VBA

Within the VBA Editor, use Insert > Module to add a module to the current VBAProject. By default, this will be called Module1 but can be re-named later. Within the Module1 code space, we will add a subroutine called Main:

Within the Main subroutine, we will declare a variable (SCApp) to which we will assign a new StressCheck Application object (StressCheck.Application) via the Set command:

In effect, the above code will create a background StressCheck process (StressCheck.exe) and assign its properties to SCApp.

Python

In PythonWin, we use File > New to create a new Python Script (.py file). Save the Python script as FirstPythonCOM.py.

In the new Python script, we will first import the win32com.client (as discussed in the previous section) and assign it to the alias win32. Then, we will use the EnsureDispatch() command to instance a new StressCheck Application object and assign it to a variable called scapp:

Similar to the Excel VBA code, the above will create a background StressCheck process (StressCheck.exe) and assign its properties to scapp.

Opening a StressCheck Handbook File

To demonstrate how to open a StressCheck Handbook file (SCW or SCP format), we will open peter02.scw from the “C:\Program Files\ESRD\StressCheck PE 11\Handbook\Basic\2D-Basic” directory. In order to open the file, we must specify the location and name of the file to be opened. Then, we will use the Open command of the StressCheck Application object’s Document property to open the Handbook model in the current StressCheck application, and the Show command of the StressCheck Application object to display the current StressCheck application’s GUI to the desktop.

Note that we can use “.” to append the Document property to the StressCheck application instance (SCApp/scapp), and then call the Document property’s Open method. By extension, we can use “.” to access all levels of the StressCheck application object hierarchy. This will be explored in later automation examples.

Excel VBA

On the next line of code, we will use SCApp.Document.Open and provide the path to the peter02.scw file. We will also show the StressCheck application on our desktop, via SCApp.Show(True), so we can view the model:

Python

Similarly, in Python we can use the same syntax to open peter02.scw via Document.Open, and show the StressCheck application object:

Modifying Handbook Model Parameters

In the StressCheck Handbook model file we opened (peter02.scw), there are several pre-existing parameters which we may modify. These include geometric parameters (L = Plate Length = 15 inches, W = Plate Width = 5 inches, a = Hole Diameter = 1 inch, and h = Plate Thickness = 1 inch) and a load parameter (S = Remote Axial Stress = 1 ksi).

We will modify the hole diameter “a” from the default value of 1 inch to 0.5 inches and update the model using the Document property’s ParameterAssign method. The ParameterAssign method takes three arguments: the parameter name (“a”), the new value (0.5), and if the parameter should be automatically updated (True).

Note that there are several “shortcut” methods available in the Document property, including ParameterAssign, xSolve, xPlot and xExtract; the latter three will be discussed in future sections when we solve/post-process the Handbook model.

Excel VBA

On the next line of VBA code, we will use SCApp.Document.ParameterAssign and update “a” to 0.5:

Python

Similarly in Python, we can provide the same line of code but the arguments must be contained in parentheses:

Solving a Linear Solution

Once we have updated the model parameter for the hole diameter, we are ready to solve a linear solution for the model using p-extensions. Because this is a Handbook model with saved solution and extraction settings, let us use the parameters (linear solution, p-extension from 1 to 8) stored in the peter02.scw Handbook model’s “1-Linear” solution setting.

To solve the model using this solution setting, we simply call the Document property’s “shortcut” method xSolve and give the name of the desired solution setting (“1-Linear”).

Excel VBA

In Excel VBA, this would be in the form SCApp.Document.xSolve “1-Linear”:

Python

In Python, this would be in the form scapp.Document.xSolve(‘1-Linear’):

Extracting a Maximum Stress

When an extraction is performed in StressCheck, the data of interest (max S1 in peter02.scw), as well as other associated information (Run #, DOF, Maximum Limit, etc.), are placed in a StressCheck Datatable for access. This datatable is in row and column format.

Interactively, the StressCheck Datatable for peter02.scw’s max S1 extraction will appear as the following (Figure 12):

There are eight (8) rows, one for each polynomial level, and seven (7) columns, each describing the attributes of the extraction, in the above StressCheck Datatable. To perform the extraction shown above, we will simply call the Document property’s xExtractData method. This is used in the same manner as the xSolve method, in that we supply the name of the saved extraction setting (“2-Min/Max/Avg”).

However, because the xExtractData method returns a StressCheck Datatable object, we must define a StressCheck Datatable object for assignment (e.g. SCDT).

Excel VBA

In Excel VBA, we will define the StressCheck Datatable variable (“SCDT”) and set the xExtractData datatable result to this variable:

Python

Similarly, we will set the xExtractData datatable result to a variable “scdt”:

Accessing Specific Datatable Quantities

Once the StressCheck Datatable object SCDT/scdt is set to the datatable output by the xExtractData method from the 2-Min/Max/Avg extraction setting, we may access/interrogate this datatable for relevant engineering information.

The relevant information for peter02.scw is the maximum first principal stress (S1max) and the estimated maximum for this quantity. From these two values, we can determine the estimated relative error in S1max. Since we are interested in the p=8 value for S1max, we can directly interrogate the Data property for this value.

The Data property of the SCDT/scdt object contains an array of all extraction information relevant to the given datatable type.  As mentioned, this array is in row and column format with a beginning index of zero (0).  This means that at p=8, we will interrogate row number seven (7), and for the Max. S1 and Maximum Limit we use column numbers two and three (2 and 3), respectively.  We can then compute the relative estimated error percentage for S1_max.

Excel VBA

In Excel VBA, we will need to define variables to hold the value of the maximum S1 (S1max) and the estimated limit (Limit), and then the relative estimated error computation (RelError). Then, we will access the necessary Data row/column information and populate these variables:

Python

In Python, we will access the Data row/column information and assign this information to similar variables:

Presenting Results to the User

Now that the max S1 and relative estimated error values are available in memory, these values may be presented to the user in a variety of formats/delivery mechanisms. Some options include producing a message dialog, exporting a text file, or simply writing the results in the spreadsheet/console.

Excel VBA

In Excel VBA, we can write the values to an Excel spreadsheet cell using the .Cells property of the current Sheet:

Python

In Python, we can print the variables to the console using the print function:

Closing StressCheck

To close StressCheck after the completion of automation tasks, we invoke the StressCheck Application object’s Close method. In effect, this will destroy the StressCheck.exe process.

Excel VBA

In Excel VBA, we add the code SCApp.Close at the end of the Main subroutine:

Python

In Python, we add the code scapp.Close() at the end of the Python script:

Executing the Automation Script

Now that our code is written, we can execute the automation script to return the max S1 and associated estimated relative error for the peter02.scw Handbook model. The expected results are:

• Max S1 = 3.0549
• Estimated relative error (%) = 0.0175%

Excel VBA

In the VBA Editor, and with the Module1 window in focus, click the Play button (or use Run > Run Module) to execute the VBA script. The StressCheck GUI should briefly appear, and the active sheet (Sheet) cells A1 and A2 will be populated with the max S1 and relative estimated error, respectively:

Python

In PythonWin (or in your preferred Python application), use File > Run. Make sure the FirstPythonCOM.py is selected as the Python script. Click OK to execute the Python script. Similar to the Excel VBA script, the StressCheck GUI will briefly appear while the computation(s) are performed, and the max S1 and estimated relative error are printed to the console:

Try It Yourself

The complete VBA code for this example is as follows:

Sub Main()
    
    Dim SCApp As StressCheck.Application
    Set SCApp = New StressCheck.Application
    SCApp.Document.Open "C:\Program Files\ESRD\StressCheck PE 11\Handbook\Basic\2D-Basic\peter02.scw"
    SCApp.Show (True)
    SCApp.Document.ParameterAssign "a", 0.5, True
    SCApp.Document.xSolve "1-Linear"
    Dim SCDT As StressCheck.DataTable
    Set SCDT = SCApp.Document.xExtractData("2-Min/Max/Avg")
    Dim S1max, Limit, RelError As Double
    S1max = SCDT.Data(7, 2)
    Limit = SCDT.Data(7, 3)
    RelError = (Limit - S1max) / Limit * 100
    Sheet1.Cells(1, 1) = S1max
    Sheet1.Cells(2, 1) = RelError
    SCApp.Close
    
End Sub

The complete Python code for the above example is as follows:

import win32com.client as win32
scapp = win32.gencache.EnsureDispatch('StressCheck.Application')
scapp.Document.Open(fr'C:\Program Files\ESRD\StressCheck PE 11\Handbook\Basic\2D-Basic\peter02.scw')
scapp.Show(True)
scapp.Document.ParameterAssign('a', 0.5, True)
scapp.Document.xSolve('1-Linear')
scdt = scapp.Document.xExtractData('2-Min/Max/Avg')
s1max = scdt.Data[7][2]
limit = scdt.Data[7][3]
relerror = (limit-s1max)/limit*100
print(s1max)
print(relerror)
scapp.Close()

Download the .xlsm and .py files associated with the above example here:

• Download Excel VBA XLSM
• Download Python PY Script