ModelBuilder-2D

ModelBuilder-2D is a customized version of the open source CMB ModelBuilder simulation preprocessing application for numerical simulation. To provide general familiarization with CMB, this version of modelbuilder is designed to construct and carry out basic numerical simulations with two-dimensional geometry. In paricular, this version of modelbuilder includes a two-dimensional finite-element solver for flat stress problems. Users can input model geometry by creating and importing text files that describe planar polygon shapes. Model edge and vertex entities can be assigned simulation attributes to specify loads and displacement constraints. Users can generate unstructured triangle meshes from geometric models, generate solver input files, run the solver, and visualize the computed results (stress and displacement fields) from the modelbuilder user interface.

Contents:

Installing ModelBuilder-2D

Note

At present, the ModelBuilder-2D install package is only available for linux systems.

1. Download the Package File

The latest release packages for ModelBuilder-2D are stored online in the CMB-2D/Downloads Folder. Navigate a web browser to that link, locate the package file for your platform, and click the download button to the right of it.

2. Extract the Package File

After the download is complete:

• For linux, extract the files from the .tar.gz package to a convenient folder on your system. The modelbuilder executable is in the bin folder.

3. Run the Executable

When you first start ModelBuilder-2D, it looks similar to the ParaView desktop application, with the main differences being that (i) some of the ParaView toolbars have been hidden, and (ii) the left sidebar has two new dock widgets labeled Resources and Attribute Editor, and (iii) there is a new CMB2D project menu.

4. Initialize Settings

Before going further, there are a couple application settings that are particularly useful for modelbuilder workflows. To set them, open the settings panel

• On Linux and Windows systems, go to the Edit menu and select the Settings… item.

• On macOS systems, go to the modelbuilder menu and select the Preferences… item.

Then in the Settings dialog, select the Sim Pre-processing tab.

1. Find the Hightlight On Hover item and check the box.

2. Find the Resource Tree Style item and change the selector to two-level.

These settings do not take effect until the next time you start modelbuilder, so go ahead an exit by going to the File menu and selecting the Exit item (on macOS, go to the modelbuilder menu and select the Quit modelbuiler item.

Feature Walkthrough

In this section, we walk though a basic numerical stress/strain problem to demonstrate the functional capabilities of ModelBuilder: importing model geometry, assigning boundary conditions and material properties, generating meshes, generating solver input files, running a solver, and visualizing the results. The geometry we’ll use for this problem is a convex polygon with one inner loop (hole). We apply a two loads, one distributed land one point load, and calculate the resulting stress and strain fields.

Creating a Project

Most menu interactions will be with the CMB2D project menu, which has standard features to open ModelBuilder projects, create projects, save projects, and close projects. It also includes features specific to this tutorial for creating and editing project resources and using them to run the analysis code. For persistent storage, project resource files are stored in a user-specified directory on the available filesystem.

1. Create a Project

Although each of the features described in the following sections can be carried out in a standalone fashion, ModelBuilder-2D includes a project feature to simplify the data management required by end users. To begin, go to the CMB2D menu and select the New Project… item. In response, modelbuilder displays a file system dialog for selecting a directory to use for storing project data. Use the “New Folder” icon to create a project directory in a convenient location, for example, <home-directory>/modelbuilder/projects/cmb2d-example. In practice, you also use an existing directory — if it contains any files or subdirectories, modelbuilder will prompt you to confirm that it is OK to delete the contents of that directory before proceeding.

Once you click the OK button, a second dialog will appear with a few options. For now, just click the Apply button. When that dialog closes, modelbuilder configures the project with an attribute resource for specifying the analysis problem (material properties, displacement constraints, and loads). The user interface for editing these properties is displayed in the Attributes Editor tab. The contents of the Attribute Editor – tabs and editing fields – are specified by XML (text) file read in my by modelbuilder when the project is created. The XML template file used in this tutorial can be found under the installed ModelBuilder-2D directory. Look for the filename MinimalFEM.sbt. More details on the file format can be found at this Template File Syntax link.

2. Set RenderView to 2D mode

Be default, ModelBuilder applications display geometric models in three dimensions. Because we will be using two-dimensional geometry throughout this tutorial, make sure that the render view is set to its 2D interaction mode. To do this, look in the RenderView toolbar for a button labeled either 3D or 2D. If the label is 3D click it once to toggle it to 2D.

Importing Geometry

Our next step is to construct a geometric model to represent the shape and topology of our problem domain. ModelBuilder can be used to create geometric models interactively, or import geometry from a variety of file formats including Open Cascade, Genesis, and STL.

For two-dimensional problems, we created a simple Planar PolyGon (PPG) file format that you can use to specify two-dimensional geometry with a text editor. This format defines geometry as a list of vertex coordinates and polygon faces, with vertices connected implicitly by straight-line model edges. The geometry for our example problem can be defined in PPG format as follows:

# Vertices 1-8 for the outer polygon
v  0.0  2.0
v  1.0  0.0
v  9.0  0.0
v  9.0  2.0
v  8.0  4.0
v  6.0  5.0
v  3.0  5.0
v  1.0  4.0
# Vertices 9-12 for the inner loop (hole)
v  7.0  1.0
v  8.0  1.0
v  8.0  2.0
v  7.0  2.0
# Faces - note that vertex indices start with 1
f 1 2 3 4 5 6 7 8  # face
h 9 10 11 12       # hole

Because the PPG import software is intended for training and demonstration use, the supported feature set is purposely limited. Each polygon must have simple geomety, polygons cannot be self-intersecting, polygons may share edges but cannot otherwise intersect or overlap. More details can be found at this PPG File Format page.

3. Download PPG File

To add this geometry to the project, you can download the example.ppg file from the following link (right click on the link and find the “Save As” option), or copy the contents shown above into a file.

example.ppg

4. Import Geometry

Go to the “CMB2D” menu and select the Import Geometry… item, which displays a file dialog for entering the ppg file. Navigate to the ppg file and click the OK button. In response, ModelBuilder-2D will read the ppg file, generate a model resource, add it to the project resources, and display the model in the 3-D RenderView. Find and click the Camera Reset toolbar button to center the data in the display.

When you are done, modelbuilder should look similar to this

With the geometry model added to the project, we next begin the analysis specification.

Starting a Stress/Strain Analysis

5. Select MinimalFEM Analysis

The first step is to indicate to modelbuilder that we are going to specify a MinimalFEM simulation. In the sidebar’s Attribute Editor tab, there is one sub-tab labeled Analysis containing two selection fields labeled Simulation and Mesher. In the Simulation field, select MinimalFEM which, at the present time, is the only choice available. In response, ModelBuilder-2D will display a second tab labeled MinimalFEM and that tab will also display a red alert icon indicating that one or more fields in that tab are currently invalid.

6. Set Elasticity Properties

We can now specify the material properties to pass to the solver (which are used to construct the stiffness matrix for the analysis). Because our solver is limited to isotropic, homogenous media, elasticity can be specified with two scalar values from Hooke’s law: Young’s modulus and Poisson’s ratio. Clicking on the Minimal FEM tab, you can see that it contains three children tabs labeled Elasticity, Constraints, and Loads. In the Elasticity tab, there are two fields for Poisson’s Ratio and Young’s Modulus. The Poisson’s Ratio field is already set to a value of 0.25, which is a default value set in the MinimalFEM.sbt file mentioned above. The yellow background indicates that the current value is the default. Change that value to 0.3 to represent a typical steel. The background changes to white to indicate you are not using the default value.

The Young’s Modulus field has no default value, and the red background indicates that the value is invalid (in this case, missing). Enter a value of 2000, which is typical for steel, and note that the background color changes to white. Also notice that the alert icons in the Elasticity and MinimalFEM tabs also disappear when the value is entered.

7. Save the Project

With the model imported and the analysis specified, it is a good time to write the project changes to your file system. To do that, go to the CMB2D menu and select the Save Project item. When you do that, ModelBuilder-2D writes two files to a resources subdirectory under the project directory. One file, with name starting CMB2D-ANALYSIS- and an extension of .smtk is the attribute resource, which stores the data entered in the “Attribute Editor”. The other file, with name starting CMB2D-MODEL- and extension .smtk is the model resource, which stores the geometric model (including topology) that was imported from the ppg file. Resource files can be individually loaded into modelbuilder, however, we recommend using the CMB2D project menu to open and close all resources atomically.

With the elasticity properties set, we will proceed to assign boundary conditions in the next section.

Assigning Boundary and Load Conditions

We next add boundary conditions and loading specifications to selected edges and vertices in the geometric model.

8. Add Displacement Constraints

The only boundary conditions used in our MinimalFEM analysis are displacement constraints. For our problem, we will constrain two edges: the bottom edge and the adjacent one to its left. To do this, click on the Constraints tab. The user interface in this tab is an attribute view, in which you create attributes as needed for your specfication. For this problem, only one attribute is needed; to add it, click the New button to the right of the Constraint label, and note that an item labeled constraint-0 appears in a list below the button. You can double click the name to edit it, but the default name is fine.

Below the list of attributes is a Displacement Constraint field with a selection box to choose the direction, with the choices X Direction (default), Y Direction, or X and Y Directions. Choose X and Y Directions from the list.

Below that is a Model Boundary and Attribute Associations widget – this is where you assign the displacement constraint attribute to model entities. For this problem, select edge 01 and edge 02 in the Available list, then click the arrow to move those entities to the left-hand list (Currrent).

9. Set Loads

For our problem, we will apply two load conditions, one to the top-most edge and the other to a vertex on the right-hand size. To do this, click on the Loads tab to display its attribute view. In this view, we will create two attributes, one for each load.

• Click the New button to create the first load attribute. Below that, find the Force (N) fields and set the Y-Force to -3.5. In the Available list, select edge 06 and move it to the Current list.

• Click the New button to create the second load attribute. For the Force (N) fields set X-Force to -2.0 and Y-Force to -2.0. In the Available list, select vertex 04 and move it to the Current list.

10. Save the Project

We have now specified all of the information needed for our problem. Save the project once again by going to the CMB2D menu and selecting the Save Project item. The next step is meshing.

Generating the Mesh

To provide two-dimensional meshing, we embedded the open source Aquaveo XMS Mesher into ModelBuilder-2D. XMS Mesher is a full-feature tool for geometry discretization with features such as edge and line refinement, vertex and point refinement, and linear sizing functions. For this walkthrough, however, we only expose a global mesh size (constant). (For those interested, the full XMS feature set can be accessed through the modelbuilder operation view; the operation name is smtk::mesh::xms::GenerateMesh).

11. Add a RenderView

To start, we are going to add a second view to display the results of the meshing operation. There are several ways to do this; for this walkthrough we are going to create a separate layout. In the tab bar above the current RenderView, find and click the + button to create a second tab. A new tab labeled Layout #2 will be displayed, showing a Create View label and a vertical list of buttons. Click the Render View button, which is the first one in the list, which will display the geometry model.

In this new layout we are going to do two things: (i) reset the camera to be centered and scaled to our geometry, then (ii) hide the model. First, find the camera Reset button in the main toolbars and click on it, which will update the display so that you can see the geometric model centered in the view.

Then right-click over the model and select the Hide` item in the context menu, leaving an empty view. You can also rename each tab by right-clicking over the Layout # label and selecting the Rename option. Use that to rename Layout #1 to Model and Layout #2 to Mesh.

12. Select the Mesher

Although XMS is the only mesher currently available in ModelBuilder-2D, you must still select it in the Analysis tab. In the Attribute Editor, click on the Analysis tab and find the selector next to the Mesher label, and set it to XMSMesher. (We could have done this any time after creating the project, of course.)

13. Set the Mesh Size

When you set the mesher, a new tab “Meshing Configuration” appears in the Attribute editor. Click on the Meshing Configuration` tab to see it has one field labeled Global Sizing Constraint (Relative). You can enter a number in the range (0.0, 1.0) to control the number of mesh elements that get created. Enter 0.25 and hit the <Enter> key. You should see the field’s background change from yellow to white, indicating that the value you entered is different than the default.

14. Generate the Mesh

With the global mesh size set to 0.25, go to the CMB2D menu and select the Generate Mesh item. In response, modelbuilder will input the project’s model resource to the XMS mesher, run the meshing operation, translate the meshing results into a new mesh resource and add that mesh resource to the project. When this is complete (should only take a few seconds), ModelBuilder-2D will display the mesh resource. Click the Camera Reset button to again center the view. To see the mesh elements, right-click over the object and in the context menu change the Representation from Surface to Surface With Edges.

15. Save the Project

With the mesh now generated and added to the project, let’s again write the project changes to your file system. Go to the CMB2D menu and select the Save Project item.

Generating the Input File

At this point, we have three simulation resources in our modelbuilder project: (i) a geometric model which was imported from PPG file; (ii) an attribute resource storing the simulation input data, in our example, material properties and constraint/load conditions; and (iii) a discretization (mesh) of the geometry model for the finite element calculations. The next step is to generate an input file in the format consumed the MinimalFEM solver. To do this, ModelBuilder-2D includes an export operation, which is implemented as a Python script that traverses the simulation resources and writes the input file in the correct format. (Look for the file MinimalFEM.py underneath the ModelBuilder-2D directory.) The use of the interpreted Python language allows applications to be customized without requiring compiled code.

16. Export the Analysis

The process of generating the solver input file is referred to as exporting from modelbuilder to the solver-specific format. For this operation, the only user feedback are info messages writen to the Output Messages view indicating that the various operation steps were completed successfully. Before proceeding, click the Clear button below the Output Messages view to clear its current contents. Then generate the solver input file by going to the CMB2D menu and selecting the Export Analysis item. When you do this, ModelBuilder-2D will run the python script (MinimalFEM.py) which creates an export subfolder under your project folder and generates a file with the name minfem.inp in that folder. The script only takes a second to run. The resulting minfem.inp file is ascii, so you can load it into a text editor to view its contents if desired (but be sure not to make any changes!). It should be no surprise that most of the file consists of lists of mesh node coordinates and mesh element connectivity. In addition, the first line of the file contains the two elasticity parameters you entered, and the last 150 or so lines of the file specify the boundary conditions and load data you entered.

Running the MinimalFEM Solver

In most applications, the finite element code is run separately, outside of modelbuilder, possibly on a different machine (desktop, network cluster, HPC system, or cloud system). For convenience, we have embedded the MinimalFEM solver into ModelBuilder-2D so that you can run it directly. (Our problem set is sufficiently small that MinimalFEM can run on a standard desktop machine.)

17. Run MinimalFEM

Clear the Output Messages view again by clicking the Clear button. Then go to the CMB2D menu and select the Run Solver option. In response, ModelBuilder-2D will load the minfem.inp file generated in the previous step, execute the MinimalFEM solver, read the native MinimalFEM output, and translate the data into a VTK polydata file that is named minfem.vtp. The code to convert the result to .vtp file format was written by Kitware to make it easy to ingest for visualization. This code was added to a fork of the origin MinimalFEM repository; you can access the MinimalFEM source that includes our additions at Our GitLab repository.

As with meshing, the solver should run in 1-2 seconds, and the only user feedback are info messages that the operation succeeded.

Viewing the Results

Because ModelBuilder-2D incorporates the full ParaView visualization feature set, there are numerous ways to display the stress and displacement data computed by MinimalFEM After enabling the ParaView visualization features and loading the computed data, we will show three different ways to display the data.

18. Enable ParaView Features

By default, ModelBuilder-2D hides the ParaView pipeline inspector and related toolbars and filters. To see them, find and click the toolbar button with a gray ParaView icon. Once clicked, the button will change to display the familiar red-green-blue ParaView logo, a number of new toolbars will be displayed, and the Pipeline Browser view will display in the sidebar.

For convenience, undock the Pipeline Browser and drag it over the Attribute Editor view so that it is displayed as another tab.

19. Add a Third Layout and RenderView

Follow the same steps as before (Add a RenderView) to create a (third) RenderView tab:

• In the tab bar above the current RenderView, click the + button.

• In the new tab, click the Render View button.

• Click the Camera Reset button to center the model and mesh contents.

• Right click on the content and select Hide. You will need to do this twice to hide both the model and mesh respectively.

• Right click on the new tab label and rename it “Results”.

20. Load the VTP Data

In the previous step (Running the MinimalFEM Solver) the results of the elasticity calculations were written to a minfem.vtp file under the project directory. Go to the File menu and select the Open… item, navigate to your project directory, then the export subdirectory, select the minfem.vtp file, and click the OK button. ModelBuilder will display a dialog titled Open Data With… listing a number of readers for VTK polydata files. Choose the XML PolyData Reader and click the OK button. ModelBuilder-2D will load the file and render a basic 2-D display. That display will show the computed stress values; because they are calculated on mesh elements, you can see faceting in the data.

To produce a smooth display, go to the Filters menu, open the Alphabetical submenu and select the Cell Data To Point Data item. This creates a new set of point data that can be interpolated by the graphics hardware.

21. Open the Properties View

The main visualization features can be accessed from the Properties view. To open this view, go to the View menu and check the box next to Properties. When the Properties view appears in the sidebar, you can undock it and drag it over the other tabbed views and dock it as another tab.

22. Add WarpByVector Filter

To visualize physical distortion, first go back to the original display settings - do this by going to the Pipeline Browser tab and use the eyeball icons to hide `CellDataToPointData1 and show minfem.vtp. Then select the minfem.vtp item, go to the Filters menu, select the Common submenu, and select Warp By Vector.

In the Properties tab, you will find three top-level sections labeld Properties (WarnByVector1), Display (GeometryRepresentation), and View (Render View). We suggest that you collapse all three sections and open them one at a time to make these changes.

• In the first section – Properties (WarnByVector1)` – set the Scale Factor to 25.

• In the second section – Display (GeometryRepresentation) – set the Coloring to displacement.

Note

After typing a numerical field in the Properties View, either hit the <Enter> key or click the Apply button to apply the change.

With these settings, you can see bowing of the upper edge and skewing of the hole geometry.

23. Add Glyph Filter

To display the strain field with vector arrows, go to the Pipeline Browser tab and:

• hide the WarpByVector1 item,

• show the CellDataToPointData1 item,

• select the minfem.vtp item.

Then go to the Filters menu, select the Common submenu, and select Glyph. You will see some warning messages in the Output Messages view, which we will deal with next. (You can clear the Output Messages.)

The Properties view now has three top-level sections labeled Properties (Glyph1), Display (GeometryRepresentation), and View (Render View). We suggest you collapse all three before setting the following properties:

Expand the Properties (Glyph1) section and

• Find the Scale subsection and set Scale Array to displacement.

• In the Scale subsection, set Scale Factor to 50.

• Find the Masking subsection and set the Maximum Number Of Sample Points to 400.

• Collapse the Properties (Glyph1) section.

Expand the Display (GeometryRepresentation) section and:

• Find the Coloring subsection and set it to displacement.

When you are done, you should see a set of arrow-shaped glyphs colored and scaled by the magnitude of computed displacement data, with the polygon colored by the computed stress data.

These examples should give you some idea of what you can do with ModelBuilder and the CMB platform. With the full range of ParaView` feature available, you can explore many more properties, filters, and other options.

Closing the Project

24. Close the Project

When you are done exploring the results, go to the “CMB2D” menu and select the “Close Project” item to remove it from memory and clear the corresonding view panels. You will need to manually delete the visualization items in the Pipeline Browser, because that data is not considered part of the project. You can do this by first selecting each of the items under minfem.vtp in the Pipeline Browser and hitting the <Delete> key (or you can right-click and select the “Delete” item in the context menu). Then select the minfem.vtp item itself and hit the <Delete> key.

Note that the ModelBuilder/CMB platform is not tied to any specific modeling, meshing, or simulation software, but instead is designed so that it can be customized for nearly any simulation toolset and workflow. In this particular implementation, we have integrated three open-source software libraries for demonstration:

• The Boost Polygon library provides the geometry manipulations for the CMB modeling subsystem.

• The Aquaveo XMS Mesher is used to generate two-dimensional unstructured meshes from polygons.

• And the MinimalFEM solver is used for the finite-element calculations.