ENS_UNITS Schema

Parent Previous Next

ENS_UNITS Schema

This schema allows a reader to tag variables and parts with real-world unit information that can be accessed by the EnSight GUI.  The schema comes in three parts:

Note: the most important two parts to implement are ENS_UNITS_DIMS and ENS_UNITS_SYSTEM.  If these are specified, EnSight can generate ENS_UNITS_LABEL values.  Without ENS_UNITS_DIMS and ENS_UNITS_SYSTEM, EnSight will not support unit conversions, proper generation of units for computed variables and calculator parameter filtering.

These tags are defined on part, variable and case objects.  Note that the spatial dimensions are taken from the units specified for the Coordinates variable. An example of the schema is the following:

  
<?xml version="1.0" encoding="UTF-8"?>
<CEImetadata version="1.0"> 
  <vars>
    <metatags>
      <tag name="ENS_UNITS_LABEL" type="str"></tag>
      <tag name="ENS_UNITS_DIMS" type="str">/</tag>
    </metatags>
    <varlist>
      <var name="myvar" ENS_UNITS_LABEL="m s^-1" ENS_UNITS_DIMS="L/T"></var>

      <var name="Coordinates" ENS_UNITS_LABEL="m" ENS_UNITS_DIMS="L"></var>

      <var name="Time" ENS_UNITS_LABEL="s" ENS_UNITS_DIMS="T"></var>

    </varlist>
  </vars>

  <xy_queries>

    <metatags>
      <tag name="ENS_UNITS_QUERY_X_VAR" type="str"></tag>
      <tag name="ENS_UNITS_QUERY_Y_VAR" type="str"></tag>
    </metatags>
    <querylist>
      <query name="myvar vs time" ENS_UNITS_QUERY_X_VAR="Time" ENS_UNITS_QUERY_Y_VAR="myvar"></query>

      <query name="myvar vs Re" ENS_UNITS_QUERY_X_VAR="myvar" ENS_UNITS_QUERY_Y_VAR=""></query>

    </querylist>

  </xy_queries>
  <case>
    <metatags>
      <tag name="ENS_UNITS_LABEL" type="flt">2.0</tag>
      <tag name="ENS_UNITS_LABEL_TIME" type="str">s</tag>
      <tag name="ENS_UNITS_DIMS" type="flt">1.0</tag>

      <tag name="ENS_UNITS_SYSTEM" type="flt">1.0</tag>

      <tag name="ENS_UNITS_SYSTEM_NAME" type="str">SI</tag>
    </metatags>
  </case>
</CEImetadata>

 

For an EnSight case file dataset, a reference to this xml file needs to be referenced in the .case file SCRIPTS section.  The file should be located in the same directory as the .case file and the name passed with the 'metadata' tag like this:

SCRIPTS

metadata:       example.xml


User-defined readers can return this information to EnSight via the optional int USERD_get_metadata(int *nbytes, char *data) function. This function is called right after USERD_set_filenames. It is called two times. The first time, data is NULL, and the reader should put the number of bytes in the XML text (including the terminating ‘\0’) in nbytes and return Z_OK. The second call will have a valid ‘data’ pointer specified (pointing at nbytes of storage space) and the function should return the effective contents of the metadata XML file in data before returning Z_OK.

ENS_UNITS_DIMS

The ENS_UNITS_DIMS string defines the dimensionality of the object, not the specific units. It can be used to validate values and expressions.  In conjunction with ENS_UNITS_SYSTEM, it is possible to generate ENS_UNITS_LABEL values for things like derived variables or from calculator functions. As a simple example, if one had a velocity variable, the dimensions string would be: L/T or length over time.  For acceleration: L/TT or length over time squared.  Note that for a dimensionless quantity, use the string "/", the string "" means the units are undefined.  The dimensions are defined as:

Quantity (SI value)

Letter

Mass (Kilogram)

M

Length (Meter)

L

Time (Second)

T

Temperature (Kelvin)

K

Current (Ampere)

Q

Angular measure (Radian)

D

Intensity (Candela)

I

Substance amount (Mol)

A

ENS_UNITS_LABEL

This is a user specified label that should be used when the units for a specific entity are requested.  Note that while it can be helpful to specify units on things like parts, one should include units on the Coordinates and Time variables as well as these variables are used by reference for things like palettes and plots in EnSight.  Note: there are two versions of this schema specified.  

ENS_UNITS_SYSTEM

This schema is not completely implemented in EnSight yet, but will be soon.  If one begins to use it, additional features will automatically be enabled for your dataset in EnSight in the future.  This tag is set on an ENS_CASE object.  It is a string that defines a unit system. These are the current legal values for this tag:


System name

System string

Units: mass, length, time, temperature, current, angle, intensity, substance amount

User defined

USER

There is no known unit system. Labels will be treated as labels.

Metric SI

SI

kg, m, s, A, K, rad, mol, cd

Metric CGS

CGS

g, cm, s, A, C, rad, mol, cd

US ft Consistent

BFT

slug, ft, s, A, F, rad, slugmol, cd

US in Consistent

BIN

slinch, in, s, A, F, rad, lbmmol, cd

Metric MKS

MKS

kg, m, s, A, C, rad, mol, cd

Metric MPA

MPA

tonne, mm, s, mA, C, rad, mol, cd

Metric uMKS

uMKS

kg, um, s, pA, C, rad, mol, cd

Metric CGSK

CGSK

g, cm, s, A, K, rad, mol, cd

Metric NMM

NMM

kg, mm, s, mA, C, rad, mol, cd

Metric uMKSS

uMKSS

kg, um, s, mA, C, rad, mol, cd

Metric NMMDAT

NMMDAT

decatonne, mm, s, mA, C, rad, mol, cd

Metric NMMTON

NMMTON

tonne, mm, s, mA, C, rad, mol, cd

US ft

BFTS

lbm, ft, s, A, F, rad, lbmmol, cd

US in

BINS

lbm, in, s, A, F, rad, lbmmol, cd

US Engineering

USENG

lb, in, s, A, R, rad, lbmmol, cd


With ENS_UNITS_SYSTEM and ENS_UNITS_DIMS specified, it is possible for EnSight to generate ENS_UNITS_LABEL values.  This allows for unit decoration of derived quantities, etc.  It can also be used to perform unit conversions.

Model Queries: ENS_UNITS_QUERY_X_VAR, ENS_UNITS_QUERY_Y_VAR

Some readers return raw, precomputed queries via the user defined reader API calls: USERD_get_num_xy_queries, USERD_get_xy_query_info, USERD_get_xy_query_data.  These queries do not have units associated with them as ENS_QUERY objects in EnSight do not have units. The ENS_UNITS_QUERY_X_VAR and ENS_UNITS_QUERY_Y_VAR metatags are designed to address this limitation.  These tags are only valid in the <xy_query> section, where all of the model queries can be listed by name. The metatags provide the name of an EnSight variable that should be used in the determination of the unit label and dimensionality of the appropriate axis of a given query.  In the example above, the units for the X axis in the "myvar vs time" query would be the same as the EnSight 'Time' variable.

Usage Details

In EnSight, the XML passed from the reader to the client is always available on the ENS_CASE object via the read only SERVERXML attribute. For example:


ensight.objs.core.CURRENTCASE[0].SERVERXML


returns the XML for the current case.  This can be very useful in debugging readers.  Additional Python units manipulation APIs are documented here.

An Example dataset

An example dataset is available for download here as an attachment. It loads the guardrail dataset with a simple hierarchy included as an XML file as well as ENS_UNITS_LABEL, ENS_UNITS_DIMS and ENS_OBJATTR tags.