ugtsg_interpolator

UTS Interpolator

UTS Interpolator is a software used for automating the process of interpolating data from an unstructured grid to a structured grid. It uses the Paraview python libraries. It can be used as a pre/post processing tool in many computational applications benefitting from the use of structured grid over unstructured grid. E.g Deep-learning based PDE solvers : If the training data consists of numerical simulations on unstructured grids, it's very expensive in terms of computations and memory to use it for training. Plus, it's hard to train using convolutional nets which are tailor-made for structured data.

Features

• High-level user interface: helps in automating the interpolation process driven by parameters declared in a configuration file('config/UTS_Interpolator.ini').

     -  For a detailed documentation on how to set the parameters, please refer to the config file.

• Dynamic and static geometries: Supports interpolations from unstructured grids based on static as well as dynamic(time-varying) geometries.

• Multiple interpolation kernels: Supports the following interpolation kernels-

     -  Gaussian kernel
     -  Ellipsoidal Gaussian kernel
     -  Linear kernel
     -  Voronoi kernel
     -  Probabilistic Voronoi kernel
     -  Shepard kernel

• Multiple output formats: The following output formats are supported-

     -  VTK
     -  CSV
     -  NPY

• Multiple ways of creating structured grids: Structured grids can be created based on-

      -  Cell-size of a single cell of the unctructured grid
       -  Resolution (number of cells in each dimension) 

• Easy to set coordinates and length of the structured grid in each dimension:

        Supports automatic as well as manual bounding box creation: 
     -  Automatic:  Creates the smallest bounding box based on the minimum and maximum coordinates of the geometry. 
     -  Manual   :  Origin( min coordinates in x, y, and z dimensions) and lengths in each dimension can be specified explicitly.  
     -  Padding:    Additionally, padding can be specified in each direction.

• Supports parallel workflow especially useful for large datasets that cannot be stored locally:

     - Bash scripts to automate this process on multiple CPUs (Check the directory bash_scripts/ )
     - Workflow of parallelism:
     - Shell script (bash_scripts/interpolate_single.sh) executes the following processes for 1 timestep: Transfer the input 
    data (data on unstructured grid) for the current time-step from a remote server, interpolate it on the chosen 
    structured grid, and then send the data back to the remote server. 
    -  Shell script (bash_scripts/parallel_workflow.sh) executes the above shell script in a loop concurrently for 
    different timesteps so that multiple CPUs work on different time-steps concurrently.

• Supports a utility to incorporate the Signed Distance Field(SDF) for better interpolations near boundary:

  • This software supports the use of SSDF. With the help of SDF, a binary mask can be created to be able to distinguish points within the geometry from those outside.
  • The binary mask stores the values of the structured grid points inside the geometry as 1, and those outside as 0.
  • Multiplying the interpolated data with this binary mask only keeps the interpolated data for the points inside the geometry. This helps in much better interpolations near the boundaries.

• Easy to modify:

  • The implementation is in an object-oriented and modular fashion. Each function and class has been documented. So it would be easy to change or add features based on the current implementation.

How it works?

• The UTS interpolator uses Paraview module simple which has the interpolation routines. The interpolation proceeds in two stages:

  1. Cell data (unstructured grid)-> point data(unstructured grid): First, if the unstructured data is in the form of 'cell data', it's converted into 'point data' using the CellDatatoPointData filter.

  2. Point data(unstructured grid) -> point data(structured grid): The point data on the unstructured grid is then interpolated to the the point data on the desired structured grid. For this interpolation, one of the following methods can be used:

     • Voronoi Kernel:

        -  An interpolation kernel that simply returns the closest point to a point to be interpolated.
        -  A single weight is returned with value=1.0.

     • Linear Kernel:

         -  An interpolation kernel that averages the contributions of all points in the basis.

     • Gaussian Kernel:

         -  A spherical Gaussian interpolation kernel that simply returns the weights for all points found in the 
            sphere defined by radius R.
         -  The weights are computed as: exp(-(s*r/R)^2) where r is the distance from the point to be interpolated to a 
            neighboring point within R. The sharpness 's' simply affects the rate of fall off of the Gaussian.
         -  A more general kernel - Ellipsoidal_Gaussian_Kernel.

     • Ellipsoidal_Gaussian_Kernel:

         -  An interpolation kernel that returns the weights for all points found in the ellipsoid defined by radius R 
            in combination with local data (normals and/or scalars). For example, "pancake" weightings (the local 
            normal parallel to the minimum ellipsoidal axis); or "needle" weightings (the local normal parallel to the 
            maximum ellipsoidal axis) are possible. (Note that spherical Gaussian weightings are more efficiently 
            computed using Gaussian_Kernel.
       
         -  The ellipsoidal Gaussian can be described by: W(x) = S * exp( -( Sharpness^2 * ((rxy/E)**2 + z**2)/R**2)
            where S is the local scalar value; E is a user-defined eccentricity factor that controls the elliptical 
            shape of the splat; z is the distance of the current voxel sample point along the local normal N; and rxy 
            is the distance to neighbor point x in the direction perpendicular to N.

     • Shepard_Kernel:

         -  An interpolation kernel that uses the method of Shepard to perform interpolation.
         -  The weights are computed as: 1/(r^p), 
            where r is the distance to a neighbour point within the kernel radius and p (power parameter) is a positive 
            exponent (typically p=2).

     • Probabilistic Voronoi Kernel:

         -  An interpolation kernel that interpolates from the closest weighted point from a neighborhood of points. 

Installation

UTS_Interpolator requires the installation of pvpython. It needs paraview 5.9+ to work.

Plugins

UTS interpolator is currently extended with the following plugins:

1. [evtk]: Used to export the numpy arrays in VTK format. For UTS_Interpolator, it's needed only if the output is to be stored in vts format while using the binary mask created from the Signed Distance Field(SDF). It's not necessary otherwise.