The Pointwise Plugin SDK was updated with the release of V18.1 to include grid import capability. This third post in a 4-part series provides details about how to write a structured grid importer. Previous posts have detailed unstructured grid import and provided an overview of the API. 

Yes, you read that correctly. You can now create grid import plugins for Pointwise! If Pointwise does not yet import the grid format you use, you no longer need to wait for Pointwise to add it for you. You can easily add it yourself. If you missed them, take time to read Part 1 and Part 2 of this series.

The Pointwise Plugin SDK now includes a new Grid Import Plugin API which provides a mechanism by which structured and unstructured grid data can be read from an external source and then converted into a representation that is understood by Pointwise. At this time, only the import of raw grid data is supported. That is, the import of boundary conditions and volume conditions is not yet supported. The addition of BC and VC support in future releases will be guided by user feedback.

To properly import grid data, you need a thorough understanding of the Pointwise Grid Model API. In this post, I will focus on the import of structured grid data.

Grid Handles

Through out the code examples in this post, you will see the use of Pointwise Grid Model API data types called handles.

Handles are used to uniquely identify a Pointwise Grid Model entity or element without using pointers. For those of you familiar with C++, a handle can be considered the Pointwise Grid Model’s equivalent of a C++ this pointer. The Pointwise Grid Model API supports five handle types for use with structured grids:

• PWGM_HGRIDMODEL
• PWGM_HBLOCK
• PWGM_HDOMAIN
• PWGM_HCONNECTOR
• PWGM_HVERTEXLIST

Each Handle type has one or more SDK functions that are used to query or manipulate the entity that the Handle represents.

The SDK uses a function naming scheme in which the name’s prefix reflects the entity Handle being accessed. For example, all functions beginning with PwDom take a PWGM_HDOMAIN as their first parameter (the domain’s this pointer).

You can also extract meta information from a Handle using various SDK macros. For more details, see the The Pointwise Grid Model API / Using C / Data Types / PWGM-API Opaque Data Handle Types section on the Pointwise Plugin SDK Modules page.

Grid Model

The imported grid data is created in a hierarchy. The root of this hierarchy is accessed via a PWGM_HGRIDMODEL handle. At import, the PWGM_HGRIDMODEL is passed to the plugin’s entry point function runtimeReadGrid(GRDP_RTITEM *pRti) via the pRti->model data member.

There is a slight difference in the process used to create structured grid entities versus unstructured grid entities. This difference is motivated by the inverted relationship between a structured and unstructured grid entity and its vertices as shown in the diagram.

Structured vs. Unstructured Grid Data Hiearchy

Structured grid entities each have their own private, trilinear array of  IJK vertices indexed [0, 0, 0] to [I-1, J-1, K-1].

Structured Grid Files 101

A typical structured grid file format has three common elements:

• One or more hexahedral blocks defined by a 3D array of vertices of size IJK.
• Zero or more lists of structured, inter-block connections
• Zero or more lists of structured grid boundary patches

Depending on the 2D or 3D dimensionality of a grid, a grid file’s vertices may be defined by either two or three floating point coordinate values. The values may be stored in the file with single or double precision. In a 3D grid file, each vertex must be defined by an XYZ coordinate triple. However, 2D grid files may define each vertex with either an XYZ triple, or an XY, YZ, or XZ coordinate pair. The Pointwise Grid Import API always expects vertices defined as double precision, XYZ coordinate triples.

A structured block’s hex element connectivity is explicitly defined by the IJK arrangement of the block’s vertices. Transitioning from one cell to its neighbor or from any grid point to its neighbors is accomplished with trivial index calculations. A simple, 2D structured grid is given in the following diagram.

Creating Structured Grid Entities

Unlike unstructured entities, it is not necessary to create a vertex list before creating a structured entity. Each structured entity contains a private, internal, structured vertex list.  When a structured entity is created, its internal, structured vertex list is also created.

The vertex coordinate values of a structured block’s vertex list are referenced using 3-D IJK indices. The vertex coordinate values of a structured domain’s vertex list are referenced using 2-D IJ indices. The vertex coordinate values of a connector’s vertex list are referenced using 1-D I indices.

Creating a Structured Block

A structured block is created using the steps listed below. The relevant API calls are listed below each step.

• Create a structured block
  • PwModCreateStrBlock(PWGM_HGRIDMODEL model, const PWGM_STR_SIZE blkSize)
• Obtain the private vertex list from the structured block
  • PwBlkGetVertexList(PWGM_HBLOCK h)
• Load the vertex coordinate values into the block’s vertex list
  • PwVlstSetXYZ3(PWGM_HVERTEXLIST h, PWGM_INDEX3 ndx3, PWGM_XYZVAL x, PWGM_XYZVAL y, PWGM_XYZVAL z)
  • PwVlstSetXYZVal3(PWGM_HVERTEXLIST h, PWGM_INDEX3 ndx3, PWGM_ENUM_XYZ which, PWGM_XYZVAL val)
  • PwVlstSetXYZ3Data(PWGM_HVERTEXLIST h, PWGM_INDEX3 ndx3, PWGM_VERTDATA &v)

Creating a Structured Domain

A structured domain is created using the steps listed below. The relevant API calls are listed below each step.

• Create a structured domain
  • PwModCreateStrDomain(PWGM_HGRIDMODEL model, const PWGM_STR_SIZE domSize)
• Obtain the private vertex list from the structured domain
  • PwDomGetVertexList(PWGM_HDOMAIN h)
• Load the vertex coordinate values into the domain’s vertex list
  • PwVlstSetXYZ2(PWGM_HVERTEXLIST h, PWGM_INDEX2 ndx2, PWGM_XYZVAL x, PWGM_XYZVAL y, PWGM_XYZVAL z)
  • PwVlstSetXYZVal2(PWGM_HVERTEXLIST h, PWGM_INDEX2 ndx2, PWGM_ENUM_XYZ which, PWGM_XYZVAL val)
  • PwVlstSetXYZ2Data(PWGM_HVERTEXLIST h, PWGM_INDEX2 ndx2, PWGM_VERTDATA &v)

Creating a Connector

A connector is created using the steps listed below. The relevant API calls are listed below each step.

• Create a connector
  • PwModCreateCon(PWGM_HGRIDMODEL model, PWP_UINT size)
• Obtain the private vertex list from the connector
  • PwConGetVertexList(PWGM_HCONNECTOR h)
• Load the vertex coordinate values into the connector’s vertex list
  • PwVlstSetXYZVal(PWGM_HVERTEXLIST vertlist, PWP_UINT ndx, PWGM_ENUM_XYZ which, PWGM_XYZVAL val)
  • PwVlstSetXYZ(PWGM_HVERTEXLIST vertlist, PWP_UINT ndx, PWGM_XYZVAL x, PWGM_XYZVAL y, PWGM_XYZVAL z)
  • PwVlstSetXYZData(PWGM_HVERTEXLIST vertlist, PWP_UINT ndx, PWGM_VERTDATA &v)

Closing Thoughts

Armed with an understanding of the Pointwise Grid Model API for importing structured grid data, you should be able to create a plugin that adds your grid importer of choice to Pointwise. Get started by visiting the Pointwise Plugin SDK section of our website.

We will close this 4-part series with the ultimate resource for integrating mesh generation into your CFD workflow using plugins.