1.1. User Defined Reader APIs

The user defined reader capability included in EnSight can allow otherwise unsupported structured or unstructured data to be read. The user defined reader capability utilizes dynamic shared libraries containing routines defined in this document but customized by you, the user, (or some third party). This capability is available for all our supported architectures.

Two versions of this API are available.

User Defined Reader Version 1.0 API

Starting with EnSight Version 6.0, the 1.0 API was made available. It was designed to be friendly to those producing it, but requires more manipulation internally in EnSight. It may be a little easier to produce readers using this format (especially if a global coordinate array is a hallmark of your data format), but it requires more memory and processing time. It also has been frozen in capability - so it does not contain many of the newer features.

Underlying Philosophy

API 1.0 deals with:

  • global coordinate array and corresponding

    • global node id array

    • global nodal variables

  • for each part:

    • local element connectivities (grouped by type) & corresponding

    • local element ids

    • local elemental variables

The element connectivities, within parts, reference the global coordinate array. If node ids are provided, the element connectivities have to be in terms of the node ids. If node ids are not provided, the connectivities are in terms of the (one-based) index number of each node in the global coordinate array. Therefore, node ids are more than labels - they are a part of the connectivity referencing scheme. Element ids are purely labels.

This API was originally setup to try to make the interface to other codes as straightforward as possible. Efficiency was not the major consideration.

EnSight must do a fair amount of work to get data provided in the manner described above into the form that it uses internally. There is mapping that has to be setup and maintained between the global arrays and the local part arrays so that updating over time can be accomplished efficiently. There is hashing that is required in order to deal efficiently with node ids.

All of this leads to a considerable amount of temporary memory and processing, in order to get a model read into EnSight.

User Defined Reader Version 2.0 API

The current 2.0 API is considerably more efficient, and was designed more with that in mind. It lends itself closely to the EnSight Gold format.

Underlying Philosophy

API 2.0 deals with:

  • for each part:

  • part coordinates & corresponding

  • part node ids

  • part nodal variables

  • part element connectivities (grouped by type) & corresponding

  • part element ids

  • part elemental variables

API 2.0 requires that the coordinates and corresponding nodal variables be provided per part. This eliminates the global to local mapping with all its associated temporary memory and processing time. The connectivity of the elements in each part reference the node indices of its own (one-based) part coordinate array. The connectivity of the elements do not reference the nodes according to node ids. Node ids (and element ids) are purely labels for screen display and for query operations within EnSight. This eliminates the need for node id hashing as a model is read.

The 2.0 API has been created for those needing more efficiency - both in terms of memory use and speed. The increased efficiency is possible because data is requested in a manner which more closely represents the way that EnSight stores and manipulates information internally. The new API requests size information and allocates the actual internal structures and arrays accordingly. Pointers to these arrays are passed directly to you in the routines which gather data, therefore eliminating a considerable amount of temporary memory (and allocation time) that is needed in the 1.0 API. Depending on what you must do to get your data into the form required, the memory savings and the speed improvement when loading models can be quite significant!

Therefore, some of its advantages and new features are:

  • Less memory, more efficient, and faster - as indicated above.

  • Model extents can be provided directly, such that EnSight need not read all the coordinate data at load time.

  • Tensor and complex variables are supported

  • Exit routine provided, for cleanup operations at close of EnSight

  • Geometry and variables can be provided on different time lines (timesets).

  • If your data format already provides boundary shell information, you can use it instead of the border representation that EnSight would compute.

  • Ghost cells (for both structured and unstructured data) are supported

  • User specified node and/or element ids for structured parts are supported

  • Material handling is supported

  • Nsided and Nfaced elements are supported

  • Structured ranges can be specified

  • Failed elements is supported

  • Material Species is supported

  • Rigid Body values can be supplied from the reader.

  • Reader can be allowed to deal with block min, max, and stride within itself - instead of having EnSight deal with it.

User Defined Reader Version 3.0 API

The 3.0 API is the preferred API for the future. The other two APIs are considered legacy APIs.

The 3.0 API includes all the capability of API as well as all of the efficiencies. It adds a level of versatility in that each part can have multiple geometries. Each geometry has one nodeset and can have multiple element sets (each element set has only one element type). This simplifies decomposition as each part can be decomposed into multiple, independent geometries.

Variables are decomposed as well by geometry node set and element sets.