A Glyph library that helps with the export of 2D or 3D grid data to an unstructured format.
Exporting grid data to an unstructured format requires the serial enumeration (1 to N) of all unique grid points. However, because Pointwise grid entites share points, non-trivial data management is needed to efficiently serialize the grid points. The pwio library provides the required data management.
The pwio library supports both structured and unstructured Pointwise grid entities. However, structured entities are exported as unstructured quads and hexes.
- Support for 2D boundaries needs work
- For more information, see the Access Cell Connectivity / Entity By Entity section.
##Table Of Contents
- Namespace pwio
- Library Reference pwio
- The Export Sequence
- Example Usage
- Library Reference pwio::utils
- Library Reference pwio::cell
- Pointwise Cannonical Order
- Disclaimer
All of the procs in this collection reside in the pwio namespace.
To call a proc in this collection, you must prefix the proc name with a pwio:: namespace specifier.
For example:
pwio::beginIO $entspwio::beginIO { ents }Prepare a list of grid entities for export. Must be called once at the beginning of an export.
ents- The entities to export.
For a 2D grid, ents should contain pw::Domain entities.
For a 3D grid, ents should contain pw::Block entities.
```Tcl pwio::endIO { {clearAllLocks 0} } ``` Cleans up after an export. Must be called once at the end of an export.
clearAllLocks- If 1, all entity locks will be released even if pwio did not make them.
Typically, clearAllLocks should be 0.
```Tcl pwio::getCoordCount {} ``` Returns the number of unique grid points in this export.
```Tcl pwio::getCoord { enumNdx } ``` Get an export grid coord.
enumNdx- The grid coord index from 1 to pwio::getCoordCount.
```Tcl pwio::getCoordIndex { coord {mapCoordToOwner 1} } ``` Returns the index corresponding to a [grid coord][coord].
coord- The grid coord.
mapCoordToOwner- If 1,
coordneeds to be mapped to its owning entity.
If you know that the grid coord's entity is already the owner, this call is faster if you set mapCoordToOwner to 0.
```Tcl pwio::getCellCount {} ``` Returns the number of unique, serialized grid cells in this export.
For a 2D grid, the cells will be of type tri or quad.
For a 3D grid, the cells will be of type tet, pyramid, prism, or hex.
```Tcl pwio::getCell { enumNdx {vcVarName ""} } ``` Returns an export grid cell as a list of global pwio indices.
enumNdx- A grid cell index from 1 to pwio::getCellCount.
vcVarName- If provided, the cell's volume condition is stored in this variable.
The object stored in vcVarName is a pw::VolumeCondition.
```Tcl pwio::getCellIndex { ent entNdx } ``` Returns the global, export cell index corresponding to an entity's local cell index.
ent- The grid entity.
entNdx- A cell index in
ent's local index space.
```Tcl pwio::getCellEdges { enumNdx {cellVarName ""} {minFirstOrder 0} {revVarName ""} } ``` Returns an export cell's edges as a list of global pwio indices.
enumNdx- A grid cell index from 1 to pwio::getCellCount.
cellVarName- If provided, this var receives the cell's indices.
minFirstOrder- If 1, edge indices are reversed, if needed, so that the minimum index value is first.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCell
```Tcl pwio::getMinFirstCellEdges { enumNdx {cellVarName ""} {revVarName ""} } ``` Returns an export cell's edges as a list of global pwio indices in min first order.
enumNdx- A grid cell index from 1 to pwio::getCellCount.
cellVarName- If provided, this var receives the cell's indices.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCell
```Tcl pwio::getFaceEdges { face {cellVarName ""} {minFirstOrder 0} {revVarName ""} } ``` Returns a list of `face`'s edges. Each edge is a list of global pwio indices (a list of lists).
face- A face as a list of global pwio indices.
cellVarName- If provided, this var receives a copy of face.
minFirstOrder- If 1, edge indices are reversed, if needed, so that the minimum index value is first.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCellFaces
```Tcl pwio::getMinFirstFaceEdges { face {cellVarName ""} {revVarName ""} } ``` Returns `face`'s edges as a list of global pwio indices in min first order.
face- A face as a list of global pwio indices.
cellVarName- If provided, this var receives a copy of face.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCellFaces
```Tcl pwio::getCellFaces { enumNdx {cellVarName ""} {minFirstOrder 0} } ``` Returns a list of a grid cell's faces. Each face is a list of global pwio indices (a list of lists).
enumNdx- The grid cell index from 1 to pwio::getCellCount.
cellVarName- If provided, this var receives the cell's unmodified indices.
minFirstOrder- If 1, the face indices are rotated so that the minimum index value is first. The relative ordering of the vertices is not changed (the face normal is not flipped).
See also, pwio::getCell.
```Tcl pwio::getMinFirstCellFaces { enumNdx {cellVarName ""} } ``` Returns a list of a grid cell's faces in min first order. Each face is a list of global pwio indices (a list of lists).
enumNdx- The grid cell index from 1 to pwio::getCellCount.
cellVarName- If provided, this var receives the cell's unmodified indices.
See also, pwio::getCell.
```Tcl pwio::getCellType { enumNdx } ``` Returns the grid cell's type.
enumNdx- The grid cell index from 1 to pwio::getCellCount.
For a 2D grid, the cell type will be one tri or quad.
For a 3D grid, the cell type will be one tet, pyramid, prism, or hex.
```Tcl pwio::getFaceType { face } ``` Returns the face type.
face- A face as a list of global pwio indices.
For a 2D grid, the face type will be bar.
For a 3D grid, the face type will be one tri or quad.
See also, pwio::getCellFaces.
```Tcl pwio::getEntityCell { ent ndx {localCellVarName ""} } ``` Returns an entity cell as a list of global pwio indices. These indices are only valid for calls to **pwio::getCoord**.
ent- The grid entity.
ndx- The cell index in
ent's local index space. localCellVarName- If provided, this var receives the cell's local indices.
```Tcl pwio::getEntityCellEdges { ent ndx {cellVarName ""} {minFirstOrder 0} {revVarName ""} } ``` Returns an entity cell's edges as a list of global pwio indices. These indices are only valid for calls to **pwio::getCoord**.
ent- The grid entity.
ndx- The cell index in
ent's local index space. cellVarName- If provided, this var receives the cell's indices.
minFirstOrder- If 1, edge indices are reversed, if needed, so that the minimum index value is first.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCell.
```Tcl pwio::getMinFirstEntityCellEdges { ent ndx {cellVarName ""} {revVarName ""} } ``` Returns an entity cell's edges as a list of global pwio indices in min first order. These indices are only valid for calls to **pwio::getCoord**.
ent- The grid entity.
ndx- The cell index in
ent's local index space. cellVarName- If provided, this var receives the cell's indices.
revVarName- If provided, this var receives a list of edge flags. A flag is set to 1 if the edge was min first reversed.
See also, pwio::getCell.
```Tcl pwio::getCaeDim {} ``` Returns 2 if the grid dimensionality is 2D or 3 if the grid dimensionality is 3D.
```Tcl pwio::getSelectType {} ``` Returns **Domain** if the grid dimensionality is 2D or **Block** if the grid dimensionality is 3D.
See pwio::utils::getSelection.
```Tcl pwio::fixCoord { coordVarName } ``` Returns the [grid coord][coord] corrected to use proper indexing form.
coordVarName- Required. The grid coord to be modifed if needed.
```Tcl pwio::coordMapLower { coord } ``` Returns the [grid coord][coord] mapped to its next lower level entity.
coord- The grid coord to be mapped.
```Tcl pwio::mapToOwner { coord {trace 0} } ``` Returns the [grid coord][coord] mapped to its owning entity.
coord- The grid coord to be mapped.
trace- For debugging only. If 1, the mapping sequence is dumped to stdout.
```Tcl pwio::coordGetEntity { coord } ``` Returns the entity of the [grid coord][coord].
coord- The grid coord.
```Tcl pwio::coordGetIjk { coord } ``` Returns the ijk index of the [grid coord][coord].
coord- The grid coord.
pwio::LevelEnumerated entity level integer values.
Accessed as:
- pwio::Level::Block
- pwio::Level::Domain
- pwio::Level::Connector
- pwio::Level::Node
See also pwio::coordMapToLevel, and pwio::entGetLevel.
```Tcl pwio::entGetLevel { entOrBaseType } ``` Returns an entity level value.
entOrBaseType- A grid entity or an entity base type.
See also, pwio::utils::entBaseType.
```Tcl pwio::coordGetLevel { coord } ``` Returns an entity level value for the entity in the [grid coord][coord].
coord- The grid coord.
```Tcl pwio::coordMapToEntity { fromCoord toEnt coordsVarName } ``` Returns non-zero if `fromCoord` can be mapped to a [grid coord][coord] in `toEnt`.
fromCoord- The starting grid coord.
toEnt- The target grid entity.
coordsVarName- Required. Receives the list of mapped grid coords.
```Tcl pwio::coordMapToLevel { coord toLevel coordsVarName } ``` Returns non-zero if `coord` can be mapped to a specific grid level.
coord- The starting grid coord.
toLevel- The target grid level.
coordsVarName- Required. Receives the list of mapped grid coords.
Exporting a grid using pwio requires the same basic sequence:
- Call
pwio::beginIOwith a list of entites to export.- A list of pw::Domain entites for a 2D export.
- A list of pw::Block entites for a 3D export.
- Access the grid data using pwio and Glyph procs.
- See the Example Usage section.
- See the Pointwise Cannonical Order section.
- Call
pwio::endIOwhen finished.
The following section show how to use pwio in conjuction with the standard Glyph calls.
While many formats have a lot in common, each export format will have differing needs. The usage examples given below will not be needed by every exporter.
pwio::beginIO $gridEntsToExport
# Get the number of unique grid points in $gridEntsToExport.
set coordCnt [pwio::getCoordCount]
for {set ii 1} {$ii <= $coordCnt} {incr ii} {
# Get the grid coord for grid point $ii.
set coord [pwio::getCoord $ii]
# Get the physical xyz location of coord. The returned xyz is always in the
# form {x y z}
set xyz [pw::Grid getXYZ $coord]
# Get the location of coord. If coord is database constrained, pt will be in
# the form {u v dbentity}. If *not* database constrained, pt will be in the
# form {x y z}.
set pt [pw::Grid getPoint $coord]
# Get grid entity that owns this coord.
set ownerEnt [pw::Grid getEntity $coord]
}
pwio::endIOAccessing interior and boundary cell connectivity is done on an entity by entity basis.
pwio::beginIO $gridEntsToExport
# Access the top-level pw::Domain (2D) or pw::Block (3D) volume cells.
foreach ent $gridEntsToExport {
# Get vc asigned to $ent
set vc [$ent getVolumeCondition]
# Get the number of cells in $ent.
set cellCnt [$ent getCellCount]
for {set ii 1} {$ii <= $cellCnt} {incr ii} {
# Get $ent cell $ii as a list of global pwio indices. These indices are only
# valid for calls to pwio::getCoord.
set cell [pwio::getEntityCell $ent $ii]
}
}
# Access the pw::Connector (2D) or a pw::Domain (3D) boundary cells.
set bcNames [pw::BoundaryCondition getNames]
foreach bcName $bcNames {
set bc [pw::BoundaryCondition getByName $bcName]
# Get the boundary grid entites using $bc. $bcEnts will contain
# pw::Connector (2D) or a pw::Domain (3D) entities.
set bcEnts [$bc getEntities]
# See notes below about handling the boundary entities.
}
pwio::endIOProperly handling the boundary entities is beyond the scope of this example.
Things to consider:
- Only items in
$bcEntsthat are used by$gridEntsToExportentities should be exported (connectors used by domains, domains used by blocks). - When exporting 2D boundaries:
- The
getCellCountandgetCellprocs are not defined forpw::Connectorentities. - The
pw::Connector(linear) cells are defined as two consecutive local connector points {0 1}, {1 2}, etc. - The local cell indices must be mapped to global pwio indices using
pwio::getCoordIndex.
- The
- When exporting 3D boundaries:
- The
getCellCountandgetCellprocs are defined for pw::Domain entities. - The pw::Domain boundary cells can be enumerated in a manner similar to the volume cells example.
- The
Like grid points, some export formats require the serial enumeration (1 to N) of all unique cells.
pwio::beginIO $gridEntsToExport
# Get the number of cells in $gridEntsToExport.
set cellCnt [pwio::getCellCount]
for {set ii 1} {$ii <= $cellCnt} {incr ii} {
# Get grid cell $ii. cell is a list of grid coord indices.
# These indices correspond to the coords returned by [pwio::getCoord $ii]
set cell [pwio::getCell $ii vc]
}
pwio::endIOThe cell and face lists returned by these procs arrange the indices in Pointwise cannonical order.
The ordering is defined as follows:
Scripts are freely provided. They are not supported products of Pointwise, Inc. Some scripts have been written and contributed by third parties outside of Pointwise's control.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, POINTWISE DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THESE SCRIPTS. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL POINTWISE BE LIABLE TO ANY PARTY FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THESE SCRIPTS EVEN IF POINTWISE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND REGARDLESS OF THE FAULT OR NEGLIGENCE OF POINTWISE.