Introduction

StressCheck provides a COM (Component Object Model) interface to its model construction, solution, and post-processing functions. This enables StressCheck to be used as a finite element solution engine for user-developed simulation applications (Sim Apps) that are developed using COM-enabled, object-oriented tools/languages such as VB.NET, Excel, MATLAB, C#, Python, AFGROW, etc.

The COM server is registered with Microsoft Windows in a typical installation, so a scripting program can reference “StressCheck Application X.X Object Library”. StressCheck also includes the file ESRD.StressCheck.Core.dll which is a managed .NET wrapper assembly for the COM interface; we recommend that automation scripts built with .NET use this library.

Documentation for StressCheck‘s COM API may be found by clicking Help > COM Programming Help (Figure 1). This documentation describes all the classes, objects, methods and properties of the COM interface:

For a 64 bit program StressCheck can be run in the same process or a in a separate process. StressCheck must be run as a separate process in 32 bit programs. For more information on getting started with StressCheck COM API scripting, refer to Can I Write Scripts to Automate StressCheck Professional? and StressCheck Demo: Sim App Development via Excel VBA and StressCheck API.

What is a COM API?

Microsoft COM (Component Object Model) technology in the Microsoft Windows-family of Operating Systems enables software components to communicate. COM is used by developers to create re-usable software components, link components together to build applications, and take advantage of Windows services. COM is used in applications such as the Microsoft Office Family of products. For example COM OLE technology allows Word documents to dynamically link to data in Excel spreadsheets and COM Automation allows users to build scripts in their applications to perform repetitive tasks or control one application from another.

An Application Programming Interface (API) is an interface in computer science that defines the ways by which an application program may request services from libraries and/or operating systems. An API determines the vocabulary and calling conventions the programmer should employ to use the services, and it may include specifications for routines, data structures, object classes and protocols used to communicate between the requesting software and the library.

Coupled with an Object Oriented (OO) programming language, a software application’s API can use COM technology to automate processes and develop new applications. A brief introduction to OO concepts is provided in the following.

Introduction to Object Oriented (OO) Concepts

An object is a structure containing data and methods that manipulate the data. For example, a StressCheck or Excel application is an object, as are the components which make up the application hierarchy. Each object has properties, methods and events which give the object distinction.

The properties, methods, and events of an object are enabled by the class from which the object is defined. Generally speaking, a class is an abstract representation of something, whereas an object is a usable example of the thing the class represents. Objects are therefore instances of a given class.

A class may be imagined as a blueprint, capable of providing instructions as to how an object is to be represented. For example, imagine a floor plan for a house. The floor plan may be represented by the number of rooms, dimensions for each room, etc. These are properties of the house. Additionally, instructions may be provided as to how modifications may be made to a floor plan. These modifications are implemented by various methods. Figure 2 provides an example of how this class structure might look:

The floor plan, though, is only a set of instructions, or an abstraction, for how to produce a house (class). A house is therefore a habitable, or usable, instance of a given floor plan (object). From the above example, the idea of StressCheck object hierarchy can be extrapolated and explored.

Introduction to StressCheck’s COM API

The StressCheck COM API allows users access to all of the objects, methods and properties found within the StressCheck GUI. You may build models, solve and extract information through the COM API as you would interactively.

The major benefit is that the COM API allows for external applications and interfaces to communicate with StressCheck, and vice versa. The following are examples of tools/programming languages which can “hook into” StressCheck’s COM API:

• Excel VBA
• Python
• MATLAB
• AFGROW
• .NET (VB, C#)
• Practically any other Object Oriented (OO) language

StressCheck API Object Hierarchy

The StressCheck API has a typical Class hierarchy:

• Objects (Class instances)
• Properties
• Methods
• Events
• Enumerations
• Structures (User Defined Data Types, or UDT’s)

In the way that a house can be represented by the number of rooms and the dimensions of each room, the doors, windows and other attributes (properties) for each individual room can also be specified. Additionally, each of the doors in a given room may be assigned a different color. We may continue extending this hierarchic approach until all the attributes of the house, meaning all objects and their properties, have been assigned. These attributes may be assigned by using the default configurations provided in the floor plan or by explicitly stating them as the house is built. Since StressCheck is hierarchic in the manner described above, a user has access to any StressCheck model attribute through the object hierarchy provided by the StressCheck COM API.

At the top of the StressCheck object hierarchy is the Application (Figure 3). Below the Application is the Document (database). The StressCheck Document (database) is therefore a property of the StressCheck Application, but it is also a hierarchic object with its own methods, properties, etc. The StressCheck Document methods include the ability to solve a pre-defined solution saved within a StressCheck input file, or to extract engineering information from a solution using a pre-defined extraction. This is very useful for Handbook applications.

Below the Document (database) are Model, Extractions, Solutions, etc. Again, these are properties of the StressCheck Document but are also hierarchic objects. For instance, the Model object has as its properties geometric objects, mesh objects, boundary condition assignments, and so on. If we want to create a new, or modify the properties of an existing instance of a mesh object, such as a node or an element, methods exist which will perform such actions.

In this manner, we may continue to work our way through the StressCheck COM API hierarchy until all relevant information has been communicated. The StressCheck COM API hierarchy may be examined in detail through the COM API Help included in the StressCheck installation (Help > COM Programming Help).

COM API Example #1: Updating Automesh Settings in Excel VBA

We are interested in ensuring that an Automesh object’s Ratio setting is active (True) and then updating the Ratio setting’s value to 1.0. We can do so using the Active and Value properties of the Automesh object. The Excel VBA code for activating and updating the Ratio setting for the 1st Automesh item in the Model object would be:

'Update the automesh Ratio value to 1.0
Dim myautomeshes As StressCheck.Automeshes, plateautomesh As StressCheck.Automesh
Set myautomeshes = SCApp.Document.model.Automeshes
Set plateautomesh = myautomeshes.Automesh(1)
plateautomesh.Active(apRatio) = True
plateautomesh.Value(apRatio) = 1
plateautomesh.Update
'Re-mesh the model
SCApp.Document.model.Automesh
'Update the display
SCApp.Document.model.Update

COM API Example #2: Updating and Solving a Linear Solution Setting in Python

We are interested in updating the p-levels to be p=1 to 3. We can do so by setting the PLevel and PLimit properties to 1 and 3, respectively, and then using the Update method to update the Solution item. We will then use the xSolve method to solve the solution setting. The Python code to update the solution setting “LinearSol” to p=1 to 3, and then re-solve, would be :

#Update the linear solution from p=2 to 4 to p=1 to 3
mysols = scapp.Document.Solutions
linearsol = mysols.Solution('LinearSol')
linearsol.PLevel = 1
linearsol.PLimit = 3
linearsol.Update
#Solve the linear solution
scapp.Document.xSolve('LinearSol')

COM API Example #3: Surface/Curve Laminate Assignment in C#

To make a surface/curve laminate stack assignment, begin by creating a set of type “Any Object” containing surfaces and curves. For example, this C# line creates a set called “assignset” that contains selected surface and curve objects:

model.Sets.AddSelected(“assignset”, SetObjectType.stObject);

After the set is created, assigning a material stack is identical to StressCheck; simply reference the set containing surfaces and curves. For example, this line assigns stack “stack” to set “assignset”:

model.MaterialAssignments.AddStack(“stack”,”assignset”,Assignment.atSet, 0, “Steel”, MaterialAssignOrder.maoNormal, “”, StackAssignmentType.satProportional);

Sample StressCheck COM API Scripts for Excel VBA

Sample Visual Basic for Applications (VBA) Excel macros illustrating the use of the COM interface may be downloaded from ESRD’s Resource Library. Some highlights:

• Helpful Hints and Tips: Excel VBA Basic Example
• Helpful Hints and Tips: Excel VBA StressCheck Wrapper Example #1
• Helpful Hints and Tips: Excel VBA 3D Crack Design Study
• Helpful Hints and Tips: Excel VBA 3D Crack Driver Example
• Helpful Hints and Tips: Excel VBA 3D Automeshed Plate Example
• Helpful Hints and Tips: 2D Cracked Bulkhead Beta Factor Sim App
• Helpful Hints and Tips: Automated 3D Beta Factor Curve Sim App (Figure 4)