-
Notifications
You must be signed in to change notification settings - Fork 0
Sandia Unstructured Triangle Table Generator
License
sandialabs/SUTTG
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This is the Sandia Unstructured Triangle Table Generator
(SUTTG). SUTTG is distributed under the BSD License, see LICENSE.
SUTTG tabulates thermodynamic functions in an unstructured triangular
format suitable for reading by the UTri library. The resulting tables
represent the functions to a specified level of accuracy. This version
of SUTTG includes the SESML library with thermodynamic models for
water.
For any questions related to this software, email jhcarpe@sandia.gov
This file is broken down into the following sections:
1. Building
2. Usage
-----------
1. Building
-----------
This section contains the following parts:
1.1 Requirements
1.2 Configuring and Building
1.3 Testing
1.4 Installing
----------------
1.1 Requirements
----------------
The following are required for building:
CMake (version 2.8.6 or later)
C/C++/FORTRAN compilers
Posix threads
MPI
NetCDF (version 4 specific features are not used)
Expat
Additionally, the following packages are included in the tree:
Google C++ Testing Framework (GTest)
Quad Double computation package
Sandia Unstructured Triangle Interpolation Package (UTri)
Sandia Equation of State Model Library (SESML)
SUTTG has been tested on Linux with the GCC suite >= 4.4, OpenMPI >=
1.4, and NetCDF 3.6 and 4.2.1.1. Use of other platforms, compiler,
and/or library versions may require additional porting.
----------------------------
1.2 Configuring and Building
----------------------------
One must first set up a config file, 'config.cmake', in the 'config'
directory. A template is provided in that directory. The library and
include directories must be set for finding NetCDF. If the Expat
library is in a non-standard location its include path and library
must also be specified, otherwise these variables may be left empty.
Out-of-tree building is recommended for SUTTG. To configure, one may
then do:
> mkdir build; cd build
> cmake <path to SUTTG root>
By default SUTTG is build with optimizations. One may change the
CMAKE_BUILD_TYPE from Release to Debug for a debug enabled
build. Also, one may set CMAKE_INSTALL_PREFIX to override the default
install location.
To build, simply run make.
-----------
1.4 Testing
-----------
There are some basic tests included with SUTTG. These may be run with
the command 'make test'. This will run the SESML test suite as well as
the native SUTTG tests.
--------------
1.5 Installing
--------------
> make install
The executables will be installed to CMAKE_INSTALL_PREFIX/bin.
Example input decks will be installed to
CMAKE_INSTALL_PREFIX/share/suttg/examples
and pre-generated tables to
CMAKE_INSTALL_PREFIX/share/suttg/data.
--------
2. Usage
--------
This section contains the following parts:
2.1 Table Generator
2.2 Table Visualization Dump
-------------------
2.1 Table Generator
-------------------
Tables are generated in the UTri format using the 'utriTableBuilder'
program. This program takes as input a single XML input deck. Examples
of this input deck are included in the examples directory. The
features of this input deck are given below.
The EOSInference element is the root element. It must contain three
child elements, RunSettings, EOSModel, and Tabulation.
RunSettings element:
The RunSettings element lists the desired model and type of
tabulation. In particular it must contain two attributes, "model"
and "tabulation". The string values of these attributes must be the
name of child elements in the EOSModel and Tabulation elements,
respectively. For example,
<RunSettings model="water" tabulation="utri"/>
EOSModel element:
The EOSModel element contains the specification of the thermodynamic
models and their parameters. The name of child elements may be
arbitrary. Each child element must contain a "type" attribute whose
string value is the name of a model from the SESML library. This
child's children elements give the parameter values for the
model. Parameter elements may be of type "DParam", "IParam", and
"SParam", for floating point, integer, and string parameters,
respectively. Each parameter element must contain the "name" and
"value" attributes. The string value of name must correspond with the
name of the type model's parameter in the SESML library.
For the water models in SESML, only one integer parameter is
available, TEMP_EXTRAP, and it is recommended to set this to 1. For
the IAPWS95 model an entry in the EOSModel element might look like the
following:
<water type="IAPWS95"><IParam name="TEMP_EXTRAP" value="1"/></water>
Tabulation element:
The Tabulation element contains the details for how the
utriTableBuilder program should generate the tabulation of the model
requested in the RunSettings element. There are four attributes for
the Tabulation element that set default values in the tables. In
particular, "A", "Z", "RRef", and "TRef", which respectively give the
average atomic weight and number, and reference density and
temperature for the model.
The Tabulation element must contain a child element named by the
value of the "tabulation" attribute of RunSettings. This child element
describes the details of the tabulation process and has attributes
as listed in the following with more detailed description below.
attribute name | need | default | short description
--------------------------------------------------------
type | required | --- | specify table type
basename | required | --- | base file name for table
tolerance | required | --- | requested table accuracy
boundarySamples | optional | 2 | samples along a boundary side
regionSamples | optional | 2 | samples on a triangle
meshvars | optional | RX | independent variables for table
logvars | optional | 1 | whether to tabulate in the log space
numthreads | optional | 0 | threads used for error evaluations
algorithm | optional | optimize | node optimization algorithm
stepmultiplier | optional | 0.1 | reduction factor for max Markov steps
steperrorlevel | optional | 1.0 | multiplier ignored below this error
addNodes | optional | 1 | number of nodes to add each iteration
type: currently this must be "utri"
basename: the output table takes this basename appended with a
string denoting the table type
tolerance: the relative accuracy requested for the table. The
smaller the number, the longer the table generation
process will take. Some models contain discontinuities,
not along phase boundaries, that can cause the table
generation to fail if the tolerance is set too small. For
example, the IAPWS-IF97 model contains such
discontinuities in its formulation and has an effective
minimum tolerance of approximately 0.003.
boundarySamples: The number of samples at which to evaluate the
error along each segment of the boundary. This
should be set much higher than regionSamples to
ensure that the boundary is properly refined for
the interior meshing algorithms.
regionSamples: The number of samples at which to evaluate the error
on a triangle along each edge. The center of the
triangle is sampled at points given by the
barycentric mesh of the edge points. For example,
regionSamples = 2 implies having a single evaluation
of the triangle in its center in addition to the 2
along each edge, for a total of 7 samples. One should
take care to set boundarySamples to a multiple of
regionSamples so that the exact same points along a
boundary are tested for error in both triangles and
the boundary curves.
meshvars: The type of independent variables for the table. For the
water models, currently one must choose "PE".
logvars: If non-zero, then meshing is done in the log space of the
independent variables.
numthreads: The number of computation threads with which to evaluate
errors in the optimization algorithms. If set to 0, then
a non-threaded algorithm is used. If 1 or greater, a
threaded error evaluation is used. One should not set
the number of threads to a value greater than the number
of cores for the node on which the tabulation is computed.
algorithm: The optimization algorithm to use when meshing the
interiors of phase regions. There are two choices, either
"fast" or "optimize".
The fast algorithm places new nodes at the sampled mesh
location with the highest error. While this is quicker
than putting new nodes in a more optimal position, it
can lead to meshes with much more nodes than are
necessary for meeting the desired accuracy goal.
The optimize algorithm uses a Markov chain to attempt to
minimize the error of a set of triangles around the
triangle with maximum error. Nodes may be added in the
process. This algorithm can generate meshes with much
fewer nodes than the fast algorithm, at the price of a
possibly much longer generation time.
stepmultiplier: This variable only is used in the optimize
algorithm. The maximum number of steps in a Markov
chain when optimizing a set of nodes is multiplied
by this value. It can only be less than or equal to
one. When less than one it allows a more crude
computation of the optimal node locations but at a
faster pace. This typically results in meshes with
more nodes than optimal for a given accuracy, but
may take less time to generate them.
steperrorlevel: This variable only is used in the optimize
algorithm. When the maximum error, normalized to the
desire tolerance is larger than this value, then the
above stepmultiplier is applied. When greater than
one, this can be used to try to quickly add nodes to
the mesh until a certain error level is reached and
then try to minimize the remaining error with a more
accurate placement of nodes. This is a compromise
between turning on or off the stepmultiplier.
addNodes: When adding new nodes to the interior of the mesh, this
specifies how many to add at once. When using the fast
algorithm, addNodes number of nodes are placed at the
first addNodes number of largest errors in the mesh. In
the optimize algorithm, this many nodes are added to the
next Markov chain minimization of the largest error
triangle.
Setting this value greater than one may speed up the time
to generate the interior meshes, particularly for the fast
algorithm, as it reduces the number of error evaluations
to reach a given number of nodes. However, it may lead to
many more nodes to be in the mesh than otherwise would
have been placed by the algorithm.
Children of the Tabulation element must also define the bounds for
the table. This is done with two child elements of their own to
specify a rectangular region in density-temperature or
pressure-temperature space. When tabulating with independent
variables PX, such as for the water models, only pressure-temperature
bounds are necessary. The bound elements have the form <XBounds
lower="" upper=""/> where X is T or P. The upper and lower bound
attributes are in SI units. When using pressure bounds, one must
ensure that any phase boundaries do not intersect with the upper or
lower pressure boundaries. This would create a discontinuity along
that boundary which the tabulation code currently does not support.
The utriTableBuilder program produces some diagnostic output while it
is running to allow tracking of the progress in tabulation. The type
of output depends on the interior node optimization algorithm.
First, nodes are placed along the boundaries of the tabulation
region. Output from this optimization is quite succinct and has the
form:
boundary 0 nodes 6 accuracy 0.9 time 0.45894
The boundary number is given, followed by the number of nodes placed
on the boundary, the target accuracy and the time in seconds required
to place the nodes.
The diagnostic output from the interior node placement algorithms
occurs more frequently, with every iteration of the algorithm. For the
fast algorithm, a typical line is:
region 1 nodes 1126 err 4.4553 berr 3.46664
This lists the current region being optimized, the number of nodes
placed in the region, the current error for the region and the best
error sampled for the region. Note that the current error may be
larger than the best error, as shown in the example, due to two
reasons. Placement of additional nodes may cause the Delaunay
triangulation to switch a triangle edge in a direction that has a
higher error than the prior direction. Also, dividing triangles with
new nodes may improve the sampling coverage to pick up a region of
space that had not been well characterized.
For the optimize algorithm, a more detailed output is given. A typical
line is shown below:
UTriTables::optimize_nodes: nn 117 sme 1.54866 fme 1.57755 tini 0.000208139 tmin 3.37052 tmov 0.000926971 terr 0.00703192 bme 1.55445 ttri 1.28746e-05 tset 0.000132084 topt 3.37901
The number following "nn" is the number of nodes placed in the mesh,
"sme" gives the sub-mesh error, "fme" gives the full mesh error, and
"bme" gives the best mesh error. As for the fast algorithm, the fme
value may at times be larger than the bme value, as shown in the above
example. The sme denotes the error of the region being optimized in
the current iteration. This is only a subset of nodes and triangles of
the full mesh. As seen in the above example, the sme may be smaller
than the fme. This simply indicates that the optimization reduced the
error on the submesh enough that the maximum error in the full mesh is
no longer in that sub-region.
The remaining entries of the output are timing information. In
particular, "topt" gives the total time for that iteration of the
optimization. The other times break down specific parts of the
iteration. The "tmin" is the minimization time to find sme, and "terr"
is the time to find fme. These should be the two dominant times
contributing to topt.
At completion of the optimization, the program will output some final
statistics and print the name of the table that was generated. For
example,
btimes: 0 = 0.0830629 1 = 0.00344491 2 = 0.26112 3 = 0.00615096 4 = 0.225798 5 = 0.102147 6 = 36.1141 7 = 33.6019
rtimes: 0 = 411.414 1 = 4710
btime = 70.3977 rtime = 5121.41 total time = 5191.81
Building table h2o97-1p0optb-pe.nc
Saving table h2o97-1p0optb-pe.nc
The first three lines redisplay the timing information for meshing the
boundaries and regions. The final two lines show the name of the table
output file.
Several example input decks are given in the "examples" directory.
Refer to the README in that directory for more information.
----------------------------
2.2 Table Visualization Dump
----------------------------
Once a table has been created, it resides in a NetCDF file. A helper
program (utriTableDump) is generated that aids in visualizing the
table by dumping its contents into a text file. The program has the
following usage:
> utriTableDump <tablefile> <tabletype>
The desired NetCDF table is specified as <tablefile> and the type of
the table in <tabletype>. The allowed table types are specified as
integers corresponding to the following independent variable spaces:
type | X | Y
---------------------------------
1 | density | temperature
2 | density | internal energy
3 | pressure | enthalpy
4 | pressure | entropy
5 | pressure | internal energy
The utriTableDump program then reads in the table and dumps to
standard output two sections. First, an evaluation of the table on a
uniform 100x100 grid covering the bounds of the table. Second it
prints out all triangles in the table, including the data at each
triangle vertex. The resulting output may then be displayed using
various plotting programs.
About
Sandia Unstructured Triangle Table Generator
Topics
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published