I recall the days of finite element analysis (FEA) mapping nodes and elements on paper and entering the model data into a workstation. I became very familiar with the command line structure of the major FEA packages. Also, with a few text edits in a file, multiple runs could be batched and automated very effectively.
The advent of CAD-embedded FEA resulted in a change in analysis productivity. Solid modelling gave instant visual feedback of geometry. SOLIDWORKS, integrating with the FEA package COSMOS, became a leader in the field. The command line approach was becoming a thing of the past. I didn’t miss the tedium of typing in all those commands but I did miss having the granular control of the FEA model that I was accustomed to. I started seeing the limitations of the all-GUI approach.
Enter the API
I had been working on a shell-based FEA model in SOLIDWORKS Simulation and had multiple unique shell thicknesses to be defined. The GUI wasn’t getting the job done. In scouring the help file, I noticed “commands” that could be used to define model parameters. This API approach looked like a way to have the best of both worlds, a powerful GUI and command line control. This article looks at an example of this technology based on my experience with learning the SOLIDWORKS Simulation API.
Hello World
Regardless of one’s experience in CAD or programming, picking up the SOLIDWORKS (or any high-level) API can be daunting. I will start with the SOLIDWORKS GUI interface and step through how to get started writing your first API macro.
Launching the macro environment is found in the SOLIDWORKS menu Tools à Macro à New, which will create a blank macro template as shown in Figure 1. What is better than creating a “Hello World” for starters? Our macro and the code in Figure 1 do that.
Figure 1. VBA code for “Hello world.”
This simple code ensures that all the support and reference files are in place to continue building more advanced macros.
Another way to check and make sure all the components are installed is to go to Tools à Reference. The appropriate references should appear similar to Figure 2.
Figure 2. VBA reference libraries.
Getting Started
Surface models (as opposed to solid) are very efficient when using FEA. Figure 3 shows a cantilever bracket surface model. It currently has zero thickness in the FEA environment.
Figure 3. Cantilever bracket model.
We will be defining the bracket thickness programmatically. First, we will review some common steps in all Simulation API routines by stepping through the code block below.
Set swApp = Application.SldWorks
‘swApp.SendMsgToUser2 “Hello world! from SOLIDWORKS API”, swMbWarning, swMbOk
‘1
‘Get SOLIDWORKS Simulation object
Set CWObject = swApp.GetAddInObject(“SldWorks.Simulation”)
Set COSMOSWORKS = CWObject.COSMOSWORKS’2
‘Get the study object
Set ActDoc = COSMOSWORKS.ActiveDoc()
Set StudyMngr = ActDoc.StudyManager()
Set Study = StudyMngr.GetStudy(0)End Sub
End Sub
The following is an explanation of the steps corresponding to the above code block numbers:
- These lines get a reference to the Simulation objects. CWObject and COSMOSWORKS represent the root level objects for the SOLIDWORKS Simulation API interface, allowing further access to all of the functions of the Simulation API.
- This set of lines gets the reference to the actual study we want to work with. Working backwards, the Study object is retrieved by calling GetStudy on the StudyMngr object. The StudyMngr object is created by calling the StudyManager property of the active Simulation document. The active Simulation document is initialized by setting the ActiveDoc property of the COSMOSWORKS to the variable ActDoc.
This lays out the common groundwork for setting up a macro. Our goal is to programmatically set the thickness of the surface model. Figure 4 shows the current setting for the shell thickness in the UI. Because it is a surface model in the CAD environment, it begins a zero thickness shell in the Simulation environment.
Figure 4. Simulation shell definition dialog.
This example assumes that a static study has been initialized. We will change the shell thickness from 0.0″ to 0.50″ using the API.
Where to start? Searching the API helps show that there is a property in the Simulation API called ShellThickness. Below is a partial screenshot of the help file.
Working backwards, we can see that the ShellThickness property is accessed through the ICWShell Interface, so we need to create an ICWShell (Shell) object. The documentation for the Shell interface reveals that its accessor is ICWShellManager::GetShellAt, so we need to create a ShellManager object.
Almost there . . .
To create the ShellManager object, we see from the help (Figure 5) that its accessor is the ShellManager property of ICWStudy. We have previously defined an ICWStudy object in the variable Study.
Figure 5.
Set swApp = Application.SldWorks
‘swApp.SendMsgToUser2 “Hello world! from SOLIDWORKS API”, swMbWarning, swMbOk
‘1
‘Get SOLIDWORKS Simulation object
Set CWObject = swApp.GetAddInObject(“SldWorks.Simulation”)
Set COSMOSWORKS = CWObject.COSMOSWORKS’2
‘Get the study object
Set ActDoc = COSMOSWORKS.ActiveDoc()
Set StudyMngr = ActDoc.StudyManager()
Set Study = StudyMngr.GetStudy(0)’3
‘Get Shells
Set shellMgr = Study.ShellManager
Set Shell = shellMgr.GetShellAt(0, errCode)’4
Shell.ShellBeginEdit
Shell.ShellThickness = 0.50
Shell.ShellEndEdit’Mesh and run the analysis
errCode = Study.CreateMesh(0, 4.7, 0.25)
runError = Study.RunAnalysis
‘Get the maximum vonMises stress
Set CWResult = Study.results
stress = CWResult.GetMinMaxStress(9, 0, 1, Nothing, 1, errCode)
End Sub
The following is an explanation of the steps corresponding to the code block numbers above (steps 1 and 2 were discussed previously):
- The API interface for accessing shells is ShellManager. shellMgr is the object that we will use to get the shell by calling the method GetShellAt(NIndex, errCode). NIndex is a zero-based index of the shells in the FEA model. We only have one surface body, so NIndex is 0 for the first (and only) shell.
- This block sets the actual numeric value of the shell thickness to 0.25. It is important to note the ShellBeginEdit and ShellEndEdit commands flanking the thickness definition. Many API functions follow this pattern. Modifications for load, boundary condition, geometry and the like are almost always preceded by a statement declaring that changes are about to begin or end. Just making the statement Shell.ShellThickness = 0.25 does not suffice.
The final few lines of code actually run the macro. After running, the shell definition dialog box (Figure 6) has been updated to our macro value.
Figure 6. Shell dialog after macro is run.
Getting Results
A great amount of time in analyses and simulation is spent interrogating and interpreting results from the model runs. While there are many tools for probing and filtering results using the GUI, the API allows for more precise control over the quantities and areas of the model in which to investigate. Also, there is the ability for the Simulation API interface to read and write from Microsoft Excel spreadsheets, creating a powerful method for breaking down model results beyond the built-in SOLIDWORKS Simulation GUI.
The results for the model are accessed through the set of methods and properties exposed by the ICWResults interface. For our example, we will be extracting the maximum von Mises stress in our cantilever bracket. There is a method on ICWResults named GetMinMaxStress, and its definition is given below:
GetMinMaxStress(NComponent, NElementNumber, NStepNum, DispPlane, NUnits, ErrorCode)
The inputs to this method are defined as follows:
- NComponent is an integer corresponding to the type of stress we want returned. 9 represents von Mises stress.
- NElementNumber is the element number. 0 is typically used, which tells the method to include all elements.
- NStepNum is 1 for static analyses.
- DispPlane is the reference plane for results components. “Nothing” is typically used if there are no references.
- NUnits are the engineering units in which to return the results.
- ErrorCode is 0 if successful or another integer corresponding to an error code.
Putting It All Together
Below is the complete code for modifying the thickness of the surface model, running the analysis and returning results.
Dim COSMOSWORKS As Object
Dim CWObject As CosmosWorksLib.CwAddincallback
Dim ActDoc As CosmosWorksLib.CWModelDoc
Dim StudyMngr As CosmosWorksLib.CWStudyManager
Dim Study As CosmosWorksLib.CWStudy
Dim shellMgr As CosmosWorksLib.CWShellManager
Dim Shell As cwShell
Dim errCode As Long
Dim CWResult As CosmosWorksLib.cwResults
Sub ShellModel()
Set swApp = Application.SldWorks
‘swApp.SendMsgToUser2 “Hello world! from SOLIDWORKS API”, swMbWarning, swMbOk
‘1
‘Get SOLIDWORKS Simulation object
Set CWObject = swApp.GetAddInObject(“SldWorks.Simulation”)
Set COSMOSWORKS = CWObject.COSMOSWORKS’2
‘Get the study object
Set ActDoc = COSMOSWORKS.ActiveDoc()
Set StudyMngr = ActDoc.StudyManager()
Set Study = StudyMngr.GetStudy(0)’3
‘Get Shells
Set shellMgr = Study.ShellManager
Set Shell = shellMgr.GetShellAt(0, errCode)’4
Shell.ShellBeginEdit
Shell.ShellThickness = 0.5
Shell.ShellEndEdit
‘5
‘Mesh and run the analysis
errCode = Study.CreateMesh(0, 4.7, 0.25)
runError = Study.RunAnalysis
‘6
‘Get the maximum vonMises stress
Set CWResult = Study.results
stress = CWResult.GetMinMaxStress(9, 0, 1, Nothing, 1, errCode)
End Sub
Section 6 of the code block is the stress results retrieval. As the name implies, GetMinMaxStress returns the overall minimum and maximum stress of the model. Because we have asked for component 9 in the method, we will get the von Mises stress returned to the variable stress. stress stores the results into a four-element array according to the following format:
- stress(0) is the node number of the minimum stress element.
- stress(1) is the minimum stress.
- stress(2) is the node number of the maximum stress element.
- stress(3) is the minimum stress.
Figure 7 gives the raw output results for our cantilever bracket model.
Figure 7. The output window for our macro.
Conclusion
The SOLIDWORKS Simulation API gives access to the SOLIDWORKS Simulation engine through programming methods. It is an efficient method of changing simulation paramenters and automating simulation tasks. This article demonstrates the method of changing the shell thickness of a model programatically. In addition, loads and restraints can be modified using the API as an alternative to the GUI.
About the Author
Attilio Colangelo has more than 25 years of experience in engineering and project management in the chemical, process, ceramic and advanced-materials industries. His specialties include CAE, with an emphasis on FEA, high-temperature and heavy industrial design. His software skills include SOLIDWORKS Simulation, NASTRAN, Caesar II, ANSYS and iOS programming.