LIGGGHTS and STL Transient Conversion Routine

liggghtsDo you have LIGGGHTS data that you’d like to visualize, analyze, or communicate? Do you have similar DEM (Discrete Element Model) type of data? EnSight can used easily to analyze, visualize, and communicate the results from a LIGGGHTS solution. In this particular situation, the user has both LIGGGHTS dataset for each timestep, along with STL data for each timestep which represents the moving geometry. This python routine converts both the LIGGGHTS data file as well as the STL data into EnSight format, allowing you to visualize both the moving geometry and particles at the same time, but also utilize the analysis capabilities within EnSight to quantify the discrete particle solution for such things as mass, center of gravity, particles & mass within a particular geometric region, amount of particles leaving the domain vs. time, etc.

Please visit this site for the up-to-date help and version information regarding this Conversion Routine:

The current release of this tool (version 1.6; 04-Dec-2012) can be downloaded with the following link. Simply place both files into your User Defined Tools directory, re-launch EnSight and start to visualize, analyze, and communicate your LIGGGHTS data within EnSight.

Click here to Download new version 1.6 of LIGGGHTS Conversion Tool

CFx Particle Track Translator

Updated 23-Jan-2013

Users of CFx who utilize discrete particles in their domain were a bit stuck for options for visualizing and analyzing that data in EnSight. The current CFx Export to EnSight format does not include the particle track information, and the Native Reader of CFx files into EnSight did not handle the read of those particle very well (extremely slow for small amount of particle, and unusable for more.). Given some recent inquiries, and bit more investigation on our end, we here at CEI have come up with an alternative approach which seems to work fairly well. We have written a python routine which translates the Particle Traces exported from CFx (to a ascii text file) into EnSight Measured data, which can then be loaded up with your EnSight model. This allows you to now visualize and analyze your CFx particle data in EnSight.

Transient Model Users:
Please note that in order for this routine to work with transient models, the information written to the PT1.trk file for “Traveling Time” must actually be uniquely equal to the Absolute Time (Analysis_Time). According to the CFx usage and documentation, the time written to the PT1.trk file is just the Particle_Traveling time, and therefore is not specifically the unique Analysis_Time (ie the Particle Traveling Time is relative to when that particle started, not a single fixed absolute time (aka Analysis_Time). If your transient model does conform to Traveling_Time == Analysis_Time, then this routine should work. If not, this routine will certainly not work.

The current documentation is kept on our User Defined Tools Help page here:

The translation routine takes existing EnSight Case File exported from CFx, along with a CFx exported Particle Track file (ascii format) (.trk), and translate this into measured data. The routine creates a new .case file with the appropriate additions for the Measured data. The user therefore only has to run this translation routine once, and can directly load the new .case file on his 2nd and subsequent load of the data into EnSight. With the Particle Track information read into EnSight as Measured data, the user can visualize, scale, animate, calculate, and analyze the characteristics of the Particle information.

Please view the Help page link mentioned above before launching the User Defined Tool, as there are a few options to control how the Particle Track information gets translated. Once viewed, please download the python routine below and place it (along with the .png file) into your User Defined Tools area.

Please Click here to download the current Version of this Tool (version 3.0)

Any updates to the routine will be re-posted back here, with appropriate notes/changes. Please feel free to provide feedback and comments back to us so that we can ensure that we provide the most appropriate and useful tool for your visualization needs.

Updated 16-Oct-2012:

Version 2.0 of the routine, with the following changes:

Updated routine to handle different ASCII format (provided by CEI GmbH) (differing number of values per line in file)
Updated routine to handle explicit min and max times provided in the Track files
Updated routine to handle gaps in the ParticleIDs
Updated routine to stop routine if supplied .case file already has Measured Data in it (Information provided in Terminal window)
Updated routine to handle .case file which is already transient (time set += 1)

Updated 23-January-2013:
Version 3.0:
    Updated to handle particles not starting all at the same time (for Transients only)
    Updated to handle Stick & non-existent particles at initial time
    Modified linear interpolation during re-sampling.
    Modified sort algorithm to utilize ‘sorted’ with a lambda.
Please see note at top regarding Transient Model integration.


Create a plane part

This is a simple tool but it may come in handy. Sometimes you just want to create some simple geometry, and probably the most common geometry to make is a plane. EnSight has the capability to create points and mesh them in various ways. This capability is called point parts, but it is cumbersome to specify each point manually.

This tool uses the location of the plane tool to create a point part and mesh the points to create a surface. The resulting part is a plane at the exact size and location of the plane tool. The new part can be colored and textured as desired, but it will have no variable information.

Example: This tool used to create a road for the guard rail demo model.

Just plug and chug with this tool. Don’t try to modify a created plane, just delete it and make a new one. Use the tool repeatedly to create multiple planes.

Download tool and icon. (updated 2012-09-28)

LAMMPS DEM Particles into EnSight

Recently, a user inquired about the ability to read in Discrete Element Model (DEM) data from the LAMMPS program. EnSight has many features used to visualize and analyze DEM particles from other solvers. With a quick look at their format, along with the ability to utilize Python to write a small translation routine, there is a new translation script available here to work with LAMMPS datasets.

This Python routine takes a particular LAMMPS output file containing DEM particles, denoted with a “.dat” extension, and converts this dataset into EnSight Format. The single part in EnSight contains only points (and point elements) representing the DEM particles. The routine will also convert the variable information provided within the .dat file into nodal variables. This routine does not have a lot of testing, but seems to work fairly straight forward.
(1) The provided .dat file is ASCII
(2) Variable names used within the .dat file are provided at the top of the file
(3) Columns 1,2,3 contain the X,Y,Z positions of the particles.
(4) Timestep information is provided in the “Zone” field.

After using the tool to convert the dataset, the user will have an “ensight_files” directory containing the converted information. The user can subsequently just load the “” file within the “ensight_files” directory directly to read the data in (there is no need to convert the data each time). The Tool writes command language back into the Journal File, so that recovery and utilization of the Journal File for scripting is still valid.

Help for this tool is provided from the “Help” button straight in the tool’s GUI, or via the Tool Help in the User Defined Tool Window. Help can b found here :

The current version of the Tool is version 2.0 from September 18, 2012

Any issues or problems should be reported back here, to CEI, or the author (Kevin Colburn:

Download LAMMPS Conversion Tool here

Droplet Claculation Tool

In addition to the Droplet Histogram Tool I was asked for a routine that calculates the penetration depth and the injection cone angle of droplets. The attached tool does these two things. When launched a small GUI pops up which asks the user for the measured particle data, the time step for calculation and the percentage of droplets within the calculated cone angle. The default value here is 80%. With this value the routine tends to stop at a cone angle which comes close to the groplet injection geometry.


This routine is written as a user defined tool. If you have an existing directory for your own tools just put it together with the image into that directory. Otherwise it can be used as a standalone tool as well if line 360 is activated. Please contact me if you have any problems (




Transform a vector or tensor

This tool transforms an existing vector or tensor variable into another reference frame which is specified by the user. Another way to describe it is that the tool rotates the variable. This was requested by a customer because they were interested in the components of vectors and tensors in arbitrary reference frames.

Note that the tool (as-is) does not rotate the variable along with the reference frame (the way EnSight frame mode will rotate objects attached to the frame). The variable is left unchanged, but it’s components are transformed to be in the basis of the new reference frame. For a vector, this is equivalent to taking the dot product of the vector with each of the 3 axes of the new coordinate system. This is also equivalent to rotating the vector in the opposite direction, which is how the vector will look if you visualize it in EnSight. If you would like the tool to rotate the vector WITH the reference frame then you can simply add “.transpose()” to the end of line 216, which transposes the rotation matrix and reverses the direction of rotation.

The new reference frame is determined using 3 points which are specified by the user. Point 1 is the origin of the new frame (the absolute location of this origin is irrelevant as no translations are performed). Point 2 is in the direction of X’, meaning the X’ axis is in the direction of a line from point 1 to point 2. Point 3 is the direction of Y’ (normal to the X’ axis). The image below shows a 2D representation. Points 1 and 2 determine the X’ axis, and point 3 determines the X’-Y’ plane, but Y’ does not necessarily pass through point 3.

These three points can be specified in two ways:

  1. If 3 or more query probes exist, the first 3 probes will be taken as the 3 points.
  2. If 2 or fewer probes exist, then a window will appear for the user to specify the XYZ locations of all 3 points.

The next step is to choose a variable to transform, and which parts to calculate the new variables on. All existing vectors and tensors will appear in the list of variables to select.

The script then runs. The user should see these results:

  • A new axis triad will be displayed (centered at (0,0,0)). The triad consists of three “3D arrow” annotations and they can be edited if desired.
  • Intermediate scalar variables will be created and placed in the group “p_scalars”. 3 scalars will be created for vectors, 18 for tensors. The scalars are needed for the calculation, and removing them (deactivating them) will also remove the final variable.
  • A new vector or tensor will be created with “_p” tagged to the end of the variable name. “p” here stands for “prime” meaning the primed coordinate system. When this variable is created the script is finished (there is no pop-up window indicating the script has completed running).

This tool was designed to meet the specifications of a single customer. Many aspects of how the script operates could be easily changed to make it more suitable for other users. For example, there could be a different way to define the rotation, or the tool could be made to rotate more than one variable at a time.

Limitations and warnings

  • By running the tool repeatedly, any number of vectors can be transformed but rotating a tensor will deactivate the previous tensor.
  • The accuracy of the transformation has not been extensively tested. If errors exist in the calculation they could occur for vectors only, or tensors only, or for both types.
  • EnSight 10 only. It could be adapted to EnSight 9 with little effort, if requested.

Download the tool and icon: (updated 2012-09-18)

Droplet Histogram Tool

I was asked by two customers at the same time if we have a histogram function for droplets or measured parts. In EnSight we can create histograms by looping an isovolume over a 3D part and query the attributes of that isovolume in every loop step. As droplets don’t have a volume this approach will fail.

For droplets we can use EnSight’s capability of exporting geometries. This new routine does that and gets all information from the exported files. The geometry will be exported to the temp file of the operating system. After finishing the script removes all temporary data.

One thing that is typical for droplets is the fact that they usually appear in transient files. Thus this code enables the user to select the time steps to export. By default histogram results for all time steps will be exported. Furthermore the user has to select the desired variable for the histogram. Also the number of value steps has to be selected. This number will define the refinement of the results.

As we usually handle transient files, this routine does not create a x-y plot. This would be unhandy fo several time steps. The results will be written to a text file in two columns. By default this file will be in the working directory and is called histogram_data_pairs.txt.

This routine is written as a user defined tool. If you have an existing directory for your own tools just put it together with the image into that directory. Otherwise it can be used as a standalone tool as well if line 270 is activated. Please contact me if you have any problems (


Moving Clip Plane

In EnSight we can move a clip plane depending on a selected part (e.g. a piston surface) over time. This can be done by this command:

test: special xyz clip

Recently a user asked me to automatize this feature. For this it’s necessary to create a new variable which has to be selected. No problem within the GUI but this was not possible in former EnSight versions by script. Thus this routine will only run on EnSight 10.0.2(f) or later. The result should look like this:


This routine is written as a user defined tool. If you have an existing directory for your own tools just put it together with the image into that directory. Otherwise it can be used as a standalone tool as well if line 156 is activated. Please contact me if you have any problems (

The tool will launch a GUI which asks for the fluid part which is clipped, the piston part surface and the moving direction. The tool is capable to create a new clip plane if toggled. Otherwise the name of an existing clip has to be typed in.


River & Flood Simulation Tools

EnSight is not just used by the typical CFD engineer at a large automotive companies. It is used across a wide variety of industries, specialties and disciplines. In this example today, EnSight is used in the Civil Engineer community for analysis and visualization of River and Flood Simulation results.

We started by taking 2 such solvers (River-FLO and FLO-2D) and created a translation Python script which would convert these formats into EnSight Case Gold files. Key benefits of this data in EnSight are the ability to take clips and graphing values along the clip; changing that clip interactively and seeing the graph update is very powerful; using the calculator to quantify the area affected by different key aspects; how much area is under more than 2 feet of water, or what the temporal max of depth to get an overall envelope of the flood, etc.

We then expanded this capability to other solvers called “MIKE21 Classic” and “MIKE21 FM”. Again, we wrote a python routine to translate these formats into EnSight Case Gold format.

The following short summary on the four different translation routines, along with two accompaning user defined tools to handle Aerial Photo projection/alignment automatically, as well as customer time annotation features.

RiverFLO-2D Translation Routine

This solver ( generates both a “.FED” file, and a series of “.EXP” files. The .fed file contains the geometric mesh. There is one .EXP file for each timestep, with a fixed specification of U & V velocities, water surface elevation, depth, and elevation as a per node variable. The time value is actually written as part of the .EXP filename, so the python routine parses that out and converts it into a time that EnSight can handle. Now, the time unit for the velocity is in seconds, so naturally you would want to specify time in seconds for EnSight. However, the time range for simulations is on the order of days, so reporting it as seconds is awkward. The python routine has a toggle to specify how the time is actually represented in the .case file so that graphs and integrations with time make more sense. By converting to anything other than seconds does mess up the pathline operation, but as that is not used for these models, it is okay.

Each of the translation routines take the incoming file and convert to EnSight Case Gold files. This ensures that the translation only occurs once. Each subsequent load of the model, the user can directly load in the .case file. In addition, items like changing timestep now happen very quickly, and provide the optimal operation of the model results in EnSight. To keep directories as neat and tidy as possible, I create an “ensight_files” directory, and place all of the .geo and variable files there.

The datasets are all 2D elements. They typically lie in the XY plane, with the elevation given as the Z coordinate. Timesteps are typically a few hundred, and dataset sizes are typically 200k to 500k. All of the variables are nodal, and exist for the 2D parts only. As detailed further below, models are originally prescribed in “global” coordinates. There are too many significant digits for EnSight to handle this properly, and thus this routine converts the model into “local” coordinates. The offset between local and global coordinates is referenced in the constant variables “Xref” and “Yref”.

Users will take advantage of the isosurface and isovolume tools in EnSight to restrict and create new parts. Calculator quantities including the EleSize * Water Depth will result in volume quantities like how much water volume is in each element. Querying variables over time, or creating clips and graphs on the clips over time are of significant help in analyzing the flow rates, distributions and temporal information. Use of the TempMean and TempMinMax functions allow the user to see an envelope of flood depth as a great indication of maximum depth reached over time.

To facilitate the time reporting (see below), there are constants per timestep written in the form of days, hours, minutes, seconds so that we can create the appropriate labels for time.

FLO-2D Translation Routine

This solver ( is fairly similar to the RiverFLO-2D in concept. There are a different set of files written with different (but conceptually similar) information. Here, the solver generates several files with the following suffixes: _CADPTS.DAT, _FPLAIN.DAT, and _TIMDEP.OUT. Here, the X & Y coordinates (nodal positions of the grid) are stored in the _CADPTS.DAT file, while the connectivity and elevation (Z coordinate) are stored in the _FPLAIN.DAT file. Using these two files, the python routine creates the .geo file for EnSight. The _TIMDEP.OUT files contain U and V velocity values and Water Depth. These, along with the Z coordinate as elevation are written to per node variable files.

As with the above, the python routine converts this format into EnSight Case Gold format, and saves this into a <casename>_ensight_files  directory. The routine only has to be run once per dataset, with any subsequent load of the dataset done directly as EnSight Case Gold file. As with the above format, the time unit control is provided in the Python so that the user can get the most useful unit for time. As above, reference values for the offset between global and local coordinates is kept track of via the Xref and Yref constants.

MIKE21_Classic Translation Routine

Details about the solver MIKE21_Classic (sometimes referred to as MIKE21C can be found here ( With this solver, it writes out an ascii .asc file output. This is a structured dataset, with nodal data written to a single file for all variables and all times. Header information in the file indicates grid size, position, variable count and names. The python routine converts through this structured information, again generating EnSight Case Gold Format files for all of the information. As with the above routines, the information is placed into an “ensight_files” directory. The bulk of this python is simpler than the other translation routines, but has slightly more complex logic for strides, skipping, and structured nature of implicit information. The conversion routine here can take 15-20 minutes depending upon the amount of variables and timesteps.

One nuance with this format, is that the order of writing the static data is different to that of the time varying (dynamic) data. Therefore, a toggle has been provided in the GUI for assuming that the static data is South to Noth & East to West, rather than the order of the dynamic data (North to South; East to West).

As with the above datasets, time unit specification is important as well the references between global and local coordinates. The same convention is followed here as well to provide a similar setup of information in EnSight.


MIKE21_FM Translation Routine

Another solver in the MIKE21 family is the MIKE21_FM (sometimes called MIKE21FM or just MIKE21) (, the “FM” here stands for Free Mesh. In this triangular unstructured grid solver configuration, information is written on out per element format (different to previous 3 formats). The files associated with this format are the .mesh and *.xyz files. What makes this format tricky is that during the run of the solver, it renumbers and reorganizes the element IDs, and when it writes the elemental result information out, it does so not by element number, but by location in 3D space. Therefore, there is no direct explicit writing of the variable with the elementID in which it exists.

Conversion of the .mesh file into an EnSight .geo file is quite straight forward. However, getting the variable information from the .xyz files back assigned to the elementID was not. I have gone around quite a bit with different methods to achieve one which was reasonably quick. In the end, some smart python loop logic allowed me to this search & find fairly quickly (takes about 40 minutes for 700k element model).

As with the other formats, data gets stored into “ensight_files” directory, and the translation only needs to happen once. Once done, users automatically get the data loaded into EnSight via Case format, and performing standard operations in EnSight from then on out. The same “Xref” and “Yref” values for local to global translations are stored as constant variables allowing users to either report true global positions or to use aerial photo alignment accurately. Time values are also extracted from the filename of the .xyz file, with the appropriate conversion to Analysis_Time information as well as a series of constants to be used for time annotation.


Global vs. Local Coordinates

Typical of this market, the model coordinates are provided in global coordinates. The model may be of a 25 square mile domain in California, but the coordinates are given relative to US reference several thousand miles away. These raw global coordinate values are too large in significant digits for EnSight to handle. So, each of the translation routines find the minimum X and Y location of the model and subtracts this off from each coordinate so that EnSight can handle the coordinates correctly (albeit as “local” coordinates). As a result, I create two model constants (Xref and Yref) which denote this difference between global and local coordinates. Users can then add this to any X or Y location to get back the global coordinates. In addition, the absolute coordinates are typically needed for Aerial Photo Alignment (see next tool). So, having these Xref and Yref constants are required for the aerial photo alignment.


Aerial Alignment Tool

Typical in this market is to utilize GIS type information within the display of the simulation information. As these are geographical simulations, having geographical information to provide context to the location are typically used. Although we can’t utilize most GIS information, we can utilize the texture map capability with aerial photos to give some sense of context. These photos pose a couple of initial “issues”, but were overcome with only a minor amount of work. Firstly, the aerial images are typically much higher resolution that EnSight can handle in the texture map. Aerial photos were typically 21k x 30k pixels. At most, EnSight can handle only 8k x 8k images, and depending upon your graphics card, a more typical limit is closer to 4k x 4k image. So, users must scale down the image to be less than 8k x 8k or 4k x 4k depending upon graphics card. The second issue is that of alignment of the image onto the geometry. Using our typical “use plane tool” to map it “by eye” is not sufficient. However, in this segment, the aerial photo image is typically accompanied by a “world coordinates” file. This word coordinate file describes how the pixels map to physical space (their width, length, orientation and position). This file is quite straight forward, and can be used to provide the appropriate S & T values in EnSight. So, I created a very small Python routine which asked the user for the Image file, World Coordinates file, and the Xref & Yref EnSight offsets (see previous). With this information, we can read the World Coordinates file and correctly create the S & T values for the image projection. The result is an immediate, exact projection of the aerial image onto the model.


Time Notation Tool

One interesting side note about this market segment is how time is best reported or annotated. In the normal CFD world, we annotate just the “Analysis_Time” field in seconds, and all is fine. Apart from having long timescales which denote using non-consistent Analysis_Time in hours or days, the user also does not want just this single string used for annotation. The annotation for time should roll up through seconds until it hits 1 minute, then the seconds reset back to zero, while the counter is bumped up on minutes. Same process for minutes to hours, hours to days, days to months, and months to years. Ideally what the user wants to see is a time annotation which looks something like :



So, there is a python tool which takes the constants written out from the above mentioned translation routines and creates the appropriate annotation string like above. This worked great for the end user to be able to see a more practical display of the current time than just “Analysis_Time”.


The current version of these River/Flood Analysis User Defined Tools can be downloaded below. This includes all four translation routines, time annotation tool, and aerial photo alignment. Should there be any questions, please do not hesitate to contact CEI.

Updated Toolset on 31-May 2012 for Command Record capability and Help Documentation

Updated Toolset on 14-Aug 2012 for TUFLOW translation routine & basic Triad tool (change triad labels from xyz to E,N,Elevation)

Updated Toolset periodically during Sept/Oct/Nov for robustness, handling of more variations of datasets and explicitly exporting out elevation variable. Latest update (04-Dec) contains updates to MIKE21_FM routine to tolerance variable locations not within element centroid (alternative search).


Click here to Download current Flood Simulation Toolset

You can view a tutorial on using these particular tools within EnSight here:


Spatial Probability Density Function (PDF) in EnSight

In analyzing the variable distribution within a solution, it is quite helpful to look at some type of Probability Density Function for the variable. There are a few interpretations of this function depending upon whether you are looking at the probability across time, space, or different datasets. In essence, the spatial probability density function indicates to the engineer how much of the domain (% of total volume in this case) which contains particular variable range. “How much of the domain has Species 1 near 0.01, or How much of the domain has Temperature near 900 degrees K”.

This particular tool I wrote is to analyze the distribution of a function spatially, sometimes referred to a volumetric probability density function, or a volumetric histogram. In a very basic interpretation, it is similar to the histogram display in the Color Palette Editor, normalized based on element volume.

This routine takes the parent part(s) that you have selected along with the variable that you’d to interrogate, and a user specified number of bins (or bars) in the histogram. The routine automatically finds the minimum and maximum variable range for the part(s). Based on this range, it then divides the volume into N number of IsoVolumes (number of bins) based on this variable range. The routine then determines the fraction of the total volume which is contained within each of these variable constrained ranges. The result is placed into a query register and automatically plotted on the screen.

The Tool presents the user with the simple Window to select the variable, and number of bins (or bars) for the distribution function.


After executing, you will then get a graph of distribution of the variable within the parent part(s) selected.

The values on the graph should always sum to 1.0, as it is presented as a fraction of the domain which contains that variable.

Note: As users increase the number of bars( or bins) for the graph, the shape of the curve will increase in resolution, although values on the Y-axis of the graph will adjust (as more bins used will still sum to 1.0).

This Tool can be downloaded from the link below. Please unzip the file and place both the Python Script and Icon PNG file into your UserDefinedTools area and restart EnSight. You should see a “PDF Graph” icon available in your UDT area, and you can double click to execute. Note, in EnSight 10, you can now place these UDT

Update 16-April-2012:

Based on User Requests, I’ve updated the routine to create a Stair-Stepped Graph rather than the smooth graph to represent the “binning” concept further in the graph.

Updated 22-April-2012:

Based on User Requests, I’ve updated the routine to handle transient models now. It does this by exporting out each timestep as a 1D bar part that is then automatically read back into EnSight at the end. This results in the PDF function correctly sitting in the time domain, and allows the user to normally control the timestep & all other features of EnSight while the PDF Graph correctly dove-tailed into the heirarchy of EnSight. This also allows the user to further interrogate and  and operate with the data as though it were normal Elemental Data (filtering, elevated surfaces, coloring, etc.)

I also updated the routine to correctly work with 2D parent parts (using the EleSize() and StatMoment() together rather than Vol().)

In addition, I also updated the routine to select the original Parent Parts for ease of repeat usage (rather than leaving the IsoVolume part selected).

Here is a example movie made from the Transient PDF function:



Update 05-Nov-2013: Updated routine for bug regarding the variable used for the IsoVolume. Previously, the variable selected in the GUI might not have been the variable used in the IsoVolume. Fixed in version 2.3

Update 03-Nov-2015 : Updated the explicit setting for the IsoVolume to “Band”, rather than default (not explicitly set). This would cause problems if previous IsoVolumes were not of type == Band.

Full Change log within header of Python File


Click here to Download PDF Tool v2.3 (pdf_graph_v2.3) Dated 05-Nov-2013

Click here to Download PDF Tool v 2.6 (pdf_graph_v2.6) Dated 03-Nov-2015