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:

ENS_UNITS_LABEL - This is a simple ASCII text string that can be used as a label for the units of the tagged entity. It is not designed to be interpreted in any way and is the most basic level of units support.
ENS_UNITS_DIMS - This is an ASCII string in the form: "XXX/YYY", where X and Y are strings of the following characters: M, L, T, Q, K, A, D, I (Mass, Length, Time, Charge, Temperature, Substance amount, Angle, Intensity).
ENS_UNITS_SYSTEM - This is an ASCII string that defines a specific unit system for all of the data coming from this reader. With ENS_UNITS_SYSTEM specified and ENS_UNITS_DIMS set, it is possible for EnSight to generate units labels and even do unit system conversions.

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>

</varlist>
</vars>

<xy_queries>

</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>

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.

2.0 In version 2.0, label strings should have the format: {unit}[^{power}] with spaces between individual units. If the power is 1, the ^{power} can be dropped. If the unit is in the denominator, the power should be negative. No '/' characters should be in the expression and all positive powers should appear before negative powers. An example for 'm/s': 'm s^-1' for 'm2/s2': 'm^2 s^-2'. EnSight provides methods for converting these expressions into Unicode and EnSight annotation strings.
1.0 In this version, the label is just treated as ASCII text and passed w/o interpretation by the system. This option should not be used for new development.

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.