13.3 FieldConvert modules -m

FieldConvert allows the user to manipulate the Nektar++ output binary files (.chk and .fld) by using the flag -m (which stands for module).. Specifically, FieldConvert has these additional functionalities

1. C0Projection: Computes the C0 projection of a given output file;
2. QCriterion: Computes the Q-Criterion for a given output file;
3. addFld: Sum two .fld files;
4. concatenate: Concatenate a Nektar++ binary output (.chk or .fld) field file into single file;
5. equispacedoutput: Write data as equi-spaced output using simplices to represent the data for connecting points;
6. extract: Extract a boundary field;
7. interpfield: Interpolates one field to another, requires fromxml, fromfld to be defined;
8. interppointdatatofld: Interpolates given discrete data using a finite difference approximation to a fld file given an xml file;
9. interppoints: Interpolates a set of points to another, requires fromfld and fromxml to be defined, a line or plane of points can be defined;
10. isocontour: Extract an isocontour of “fieldid” variable and at value “fieldvalue”. Optionally “fieldstr” can be specified for a string defiition or “smooth” for smoothing;
11. jacobianenergy: Shows high frequency energy of Jacobian;
12. printfldnorms: Print L2 and LInf norms to stdout;
13. scalargrad: Computes scalar gradient field;
14. scaleinputfld: Rescale input field by a constant factor;
15. shear: Computes time-averaged shear stress metrics: TAWSS, OSI, transWSS, TAAFI, TACFI, WSSG;
16. surfdistance: Computes height of a prismatic boundary layer mesh and projects onto the surface (for e.g. y⁺ calculation).
17. vorticity: Computes the vorticity field.
18. wss: Computes wall shear stress field.

The module list above can be seen by running the command

In the following we will detail the usage of each module.

13.3.1 Smooth the data: C0Projection module

To smooth the data of a given .fld file one can use the C0Projection module of FieldConvert

where the file test-C0Proj.fld can be processed in a similar way as described in section 13.1 to visualise either in Tecplot or in Paraview the result.

13.3.2 Calculate Q-Criterion: QCriterion module

To perform the Q-criterion calculation and obtain an output data containing the Q-criterion solution, the user can run

where the file test-QCrit.fld can be processed in a similar way as described in section 13.1 to visualise either in Tecplot or in Paraview the result.

13.3.3 Sum two .fld files: addFld module

To sum two .fld files one can use the addFld module of FieldConvert

In this case we use it in conjunction with the command scale which multiply the values of a given .fld file by a constant value. file1.fld is the file multiplied by value, file1.xml is the associated session file, file2.fld is the .fld file which is summed to file1.fld and finally file3.fld is the output which contain the sum of the two .fld files. file3.fld can be processed in a similar way as described in section 13.1 to visualise it either in Tecplot or in Paraview the result.

13.3.4 Concatenate two files: concatenate module

To concatenate file1.fld and file2.fld into file-conc.fld one can run the following command

where the file file-conc.fld can be processed in a similar way as described in section 13.1 to visualise either in Tecplot or in Paraview the result.

13.3.5 Equi-spaced output of data: equispacedoutput module

This module interpolates the output data to an truly equispaced set of points (not equispaced along the collapsed coordinate system). Therefore a tetrahedron is represented by a tetrahedral number of poinst. This produces much smaller output files. The points are then connected together by simplices (triangles and tetrahedrons).

13.3.6 Extract a boundary region: extract module

The boundary region of a domain can be extracted from the output data using the following command line

The option bnd specifies which boundary region to extract. Note this is different to MeshConvert where the parameter surf is specified and corresponds to composites rather boundaries. If bnd is not provided, all boundaries are extracted to different fields. The fldtoboundary is an optional command argument which copies the expansion of test.fld into the boundary region before outputting the .fld file. This option is on by default. If it turned off using fldtoboundary=0 the extraction will only evaluate the boundary condition from the xml file. The output will be placed in test-boundary-b2.fld. If more than one boundary region is specified the extension -b0.fld, -b1.fld etc will be outputted. To process this file you will need an xml file of the same region. This can be generated using the command:

The surface to be extracted in this command is the composite number and so needs to correspond to the boundary region of interest. Finally to process the surface file one can use

This will obviously generate a Tecplot output if a .dat file is specified as last argument. A .vtu extension will produce a Paraview output.

13.3.7 Compute the gradient of a field: gradient module

To compute the spatial gradients of all fields one can run the following command

where the file file-grad.fld can be processed in a similar way as described in section 13.1 to visualise either in Tecplot or in Paraview the result.

13.3.8 Interpolate one field to another: interpfield module

To interpolate one field to another, one can use the following command:

This command will interpolate the field defined by file1.xml and file1.fld to the new mesh defined in file2.xml and output it to file2.fld. The fromxml and fromfld must be specified in this module. In addition there are two optional arguments clamptolowervalue and clamptouppervalue which clamp the interpolation between these two values. Their default values are -10,000,000 and 10,000,000.

13.3.9 Interpolate scattered point data to a field: interppointdatatofld module

To interpolate discrete point data to a field, use the interppointdatatofld module:

This command will interpolate the data from file1.pts to the mesh and expansions defined in file1.xml and output the field to file1.fld. The file file.pts is of the form:

where DIM="1" FIELDS="a,b,c specifies that the field is one-dimensional and contains three variables, a, b, and c. Each line defines a point, while the first column contains its x-coordinate, the second one contains the a-values, the third the b-values and so on. In case of n-dimensional data, the n coordinates are specified in the first n columns accordingly. In order to interpolate 1D data to a nD field, specify the matching coordinate in the output field using the interpcoord argument:

This will interpolate the 1D scattered point data from 1D-file1.pts to the y-coordinate of the 3D mesh defined in 3D-file1.xml. The resulting field will have constant values along the x and z coordinates. For 1D Interpolation, the module implements a quadratic scheme and automatically falls back to a linear method if only two data points are given. A modified inverse distance method is used for 2D and 3D interpolation. Linear and quadratic interpolation require the data points in the .pts-file to be sorted by their location in ascending order. The Inverse Distance implementation has no such requirement.

13.3.10 Interpolate a field to a series of points: interppoints module

You can interpolate one field to a series of given points using the following command:

This command will interpolate the field defined by file1.xml and file1.fld to the points defined in file2.pts and output it to file2.dat. The fromxml and fromfld must be specified in this module. The format of the file file2.pts is of the same form as for the interppointdatatofld module:

There are three optional arguments clamptolowervalue, clamptouppervalue and defaultvalue the first two clamp the interpolation between these two values and the third defines the default value to be used if the point is outside the domain. Their default values are -10,000,000, 10,000,000 and 0.

In addition, instead of specifying the file file2.pts, a module list of the form

can be specified where npts is the number of equispaced points between (x0,y0) to (x1,y1) which can also be used in 3D by specifying (x0,y0,z0) to (x1,y1,z1).

An extraction of a plane can also be specified by

where npts1,npts2 is the number of equispaced points in each direction and (x0,y0,z0), (x1,y1,z1), (x2,y2,z2) and (x3,y3,z3) define the plane of points specified in a clockwise or anticlockwise direction.

13.3.11 Isoncontour extraction: iscontour module

Extract an isocontour from a field file. This option automatically take the field to an equispaced distribution of points connected by linear simplicies of triangles or tetrahedrons. The linear simplices are then inspected to extract the isocontour of interest. To specify the field fieldid can be provided giving the id of the field of interest and fieldvalue provides the value of the isocontour to be extracted.

Alternatively fieldstr=”u+v” can be specified to calculate the field u² and extract its isocontour. You can also specify fieldname=”UplusV” to define the name of the isocontour in the .dat file, i.e.

Optionally smooth can be specified to smooth the isocontour with default values smoothnegdiffusion=0.495, smoothnegdiffusion=0.5 and smoothiter=100. This option automatically calls a globalcondense option which remove multiply defined verties from the simplex definition which arise as isocontour are generated element by element.

In addition to the smooth or globalcondense options you can specify removesmallcontour=100 which will remove separate isocontours of less than 100 triangles. This optin requires smooth or globalcondense to be specified.

13.3.12 Show high frequency energy of the Jacobian: jacobianenergy module

The option topmodes can be used to specify the number of top modes to keep.

The output file jacenergy.fld can be processed in a similar way as described in section 13.1 to visualise it either in Tecplot or in Paraview the result.

13.3.13 Print L2 and LInf norms: printfldnorms module

This module does not create an output file. The L2 and LInf norms for each field variable is printed to the stdout.

13.3.14 Computes the scalar gradient: scalargrad module

The scalar gradient of a field is computed by running:

The option bnd specifies which boundary region to extract. Note this is different to MeshConvert where the parameter surf is specified and corresponds to composites rather boundaries. If bnd is not provided, all boundaries are extracted to different fields. To process this file you will need an xml file of the same region.

13.3.15 Scale a given .fld: scaleinputfld module

To scale a .fld file by a given scalar quantity, the user can run:

The argument scale=value rescales of a factor value test.fld by the factor value. The output file file-conc.fld can be processed in a similar way as described in section 13.1 to visualise it either in Tecplot or in Paraview the result.

13.3.16 Time-averaged shear stress metrics: shear module

Time-dependent wall shear stress derived metrics relevant to cardiovascular fluid dynamics research can be computed using this module. They are

• TAWSS: time-averaged wall shear stress;
• OSI: oscillatory shear index;
• transWSS: transverse wall shear stress;
• TACFI: time-averaged cross-flow index;
• TAAFI: time-averaged aneurysm formation index;
• |WSSG|: wall shear stress gradient.

To compute these, the user can run:

The argument N and fromfld are compulsory arguments that respectively define the number of fld files corresponding to the number of discrete equispaced time-steps, and the first fld file which should have the form of test_id_b0.fld where the first underscore in the name marks the starting time-step file ID.

The input .fld files are the outputs of the wss module. If they do not contain the surface normals (an optional output of the wss modle), then the shear module will not compute the last metric, |WSSG|.

13.3.17 Boundary layer height calculation: surfdistance module

The surface distance module computes the height of a prismatic boundary layer and projects this value onto the surface of the boundary, in a similar fashion to the extract module. In conjunction with a mesh of the surface, which can be obtained with MeshConvert, and a value of the average wall shear stress, one potential application of this module is to determine the distribution of y⁺ grid spacings for turbulence calculations.

To compute the height of the prismatic layer connected to boundary region 3, the user can issue the command:

Note that no .fld file is required, since the mesh is the only input required in order to calculate the element height. This produces a file output_b3.fld, which can be visualised with the appropriate surface mesh from MeshConvert.

13.3.18 Calculate vorticity: vorticity module

To perform the vorticity calculation and obtain an output data containing the vorticity solution, the user can run

where the file test-vort.fld can be processed in a similar way as described in section 13.1.

13.3.19 Computing the wall shear stress: wss module

To obtain the wall shear stres vector and magnitude, the user can run:

The option bnd specifies which boundary region to extract. Note this is different to MeshConvert where the parameter surf is specified and corresponds to composites rather boundaries. If bnd is not provided, all boundaries are extracted to different fields. The addnormals is an optional command argument which, when turned on, outputs the normal vector of the extracted boundary region as well as the shear stress vector and magnitude. This option is off by default. To process the output file(s) you will need an xml file of the same region.

13.3.20 Manipulating meshes with FieldConvert

FieldConvert has support for two modules that can be used in conjunction with the linear elastic solver, as shown in chapter 9. To do this, FieldConvert has an XML output module, in addition to the Tecplot and VTK formats.

The deform module, which takes no options, takes a displacement field and applies it to the geometry, producing a deformed mesh:

The displacement module is designed to create a boundary condition field file. Its intended use is for mesh generation purposes. It can be used to calculate the displacement between the linear mesh and a high-order surface, and then produce a fld file, prescribing the displacement at the boundary, that can be used in the linear elasticity solver.

Presently the process is somewhat convoluted and must be used in conjunction with MeshConvert to create the surface file. However the bash input below describes the procedure. Assume the high-order mesh is in a file called mesh.xml, the linear mesh is mesh-linear.xml that can be generated by removing the CURVED section from mesh.xml, and that we are interested in the surface with ID 123.