Parent Previous Next


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"> 
      <tag name="ENS_UNITS_LABEL" type="str"></tag>
      <tag name="ENS_UNITS_DIMS" type="str">/</tag>
      <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>



      <tag name="ENS_UNITS_QUERY_X_VAR" type="str"></tag>
      <tag name="ENS_UNITS_QUERY_Y_VAR" type="str"></tag>
      <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>


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


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:


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.


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)


Mass (Kilogram)


Length (Meter)


Time (Second)


Temperature (Kelvin)


Current (Ampere)


Angular measure (Radian)


Intensity (Candela)


Substance amount (Mol)



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.  


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


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

Metric SI


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

Metric CGS


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

US ft Consistent


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

US in Consistent


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

Metric MKS


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

Metric MPA


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

Metric uMKS


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

Metric CGSK


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

Metric NMM


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

Metric uMKSS


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



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



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

US ft


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

US in


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

US Engineering


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.


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:


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.