setup
Each user-defined application must supply a setup file. The setup file
defines:
- user defined parameters
- evolved gridfunctions and any needed spatial derivatives
- auxiliary gridfunctions and any needed spatial derivatives
- infrastructure gridfunctions
- surface extraction gridfunctions
- point-wise derivatives
- right-hand-side call function type
- alternative coordinate system options
- which functions can have dissipation applied to them
- C interface requirements
- whether a mask is needed for excision
- groupings of gridfunctions for easy reference
The setup file is parsed by a perl script in had/sbin.
Comments in the setup file are specified using the hashmark "#".
Example:
# This is a comment in the setup file.
The basic format of this file is a series of KEYWORDS followed by a
function list in braces ( { } ):
Example:
keyword
{
word list
}
The word list is delimited by commas, and may extend over several
lines. The opening brace "{" and closing brace "}" must be the first
characters on a line not containing the word list. The keywords may
appear in any order.
The function keywords are:
- ufuncs -- the evolved functions
- vfuncs -- the equation functions. Functions required for the equations, in particular functions that are differentiated, but not evolved. In numerical relativity, these could include the hamiltonian and momentum constraints.
- wfuncs - -"everything else". In particular functions not used to
evaluate the equations. If the pragma Use Mask (see below) is used,
other grid functions needed for excision will automatically be added
to this list.
- dufuncs -- A list of u functions to be differentiated. If this keyword
is missing, then the default is to include all spatial
derivatives (dx, dy, dz) of all u functions.
- dvfuncs -- Same as dufuncs, but for the v functions.
- asurface -- 2-D gridfunctions for surface 'A' extraction. See also surface extraction
- bsurface -- 2-D gridfunctions for surface 'B' extraction.
- csurface -- 2-D gridfunctions for surface 'C' extraction.
- par -- All parameters needed for the equation thorn.
- Point-wise Derivatives -- This keyword does not take a list.
It indicates that all derivatives should be evaluated point-wise, without
storage in a 3-D array.
- Use Mask -- This keyword is deprecated.
- NoHyperRHS1 -- This keyword does not take a list. It indicates
to not call routine calcrhs (for pointwise computation) when evolving.
See also calcrhs
- NoHyperRHS2 -- This keyword does not take a list. It indicates
to not call routine calcrhs2 when evolving.
- Need C Files -- This keyword does not take a list. It will
create header files for C code. This is necessary when the user developed
application is in C or C++ instead of fortran.
- Enable Alternative Coordinates -- This keyword does not take
a list. It allows the physical coordinates to be different from the
computational coordinates. The actual coordinate transformation and
Jacobian must be coded into the hyper part of the code.
- No HyperDerivs -- This keyword does not take
a list. If this keyword is placed in the setup file, the driver
will not take any finite difference derivatives.
The capitalization of keywords is important, but spacing is not.
For example,
Point-wise Derivatives may be given as:
- Point-wiseDerivatives
- Point - wise Derivatives
However, point-wisederivatives would not be recognized.
Keywords which do not require lists
(Point-wise Derivatives,Use Mask,
NoHyperRHS1,NoHyperRHS2,Need C Files,
Enable Alternative Coordinates,No HyperDerivs) are
off by default if they do not appear in the
setup file. They can also be turned off by putting arbitrary statements
before the keyword, such as "DO NOT USE".
Example:
DO NOT USE Point-wise Derivatives
The par keyword: user defined parameters
User defined parameters can be integers or doubles, scalars or arrays.
The user must specify the name of the parameter, type, size, minimum
allowed value, maximum allowed value, and default. Parameters
are specified in a colon delineated list, as follows:
Example:
par
{
# Name
: type
: size
: min
: max
: default
idtype
: int
: 1
: -17
:102
: 1
lftype
: double
: 1
: *
: *
: 2.0
}
If
the user does not wish to specify a minimum or maximum value, that field
can be replace with an asterisk '*', as seen above. This example defines two parameters:
an integer 'idtype' and a double 'lftype'. The command line parameter file
supplied to the executable will be parsed looking for these two parameters.
If they are not found in that parameter file, they
will be given the default values. If they are found but the values given are
outside the bounds specified in the setup file, the executable will abort.
Evolved functions -- ufuncs
The functions which are to be evolved in time are called "ufuncs".
They exist at two time levels. Each ufunc can take two additional
keywords: diss and FV. By default, dissipation is enabled
for all ufuncs (see
dissipation for more details).
Also by default, all ufuncs are vertex-centered. These two aspects
can be changed using the diss and FV keywords:
Example:
ufuncs
{
D[diss=0], T[diss=0], P
}
In the above example, the ufuncs D and T have dissipation disabled, while dissipation
could potentially be applied to ufunc P.
Example:
ufuncs
{
D[FV][diss=0], T[FV][diss=0], P[FV],Q
}
In the above example ufuncs D, T, and P are cell-centered while Q
is vertex-centered. All mesh refinement and interpolation are
treated accordingly. Dissipation is disabled for ufuncs D and T in this example.
The number of ufuncs declared in the setup file is placed in preprocessor
declaration "NU". In the above example, NU would be 4 (there are 4 ufuncs declared).
Multiple declarations of ufuncs groups
are possible:
Example:
ufuncs [G]
{
g11,g12,g13
}
ufuncs [F]
{
D[FV][diss=0], T[FV][diss=0], P[FV], Q
}
In the case of multiple declarations of ufuncs, the total number
of ufuncs declared is still counted and referenced as "NU". In the
above example, NU would be 7. Also declared, however, are statements
"NU_F" and "NU_G" ( the characters following the ufuncs keyword are appended
to the preprocessor declaration "NU_" ). NU_F would be 4 while NU_G would be 3.
See also NU,NV,NW
dufuncs
The list of the ufuncs that need to be differentiated are called dufuncs.
Derivatives in the x direction should prepend
"dx_" to the ufunc name; likewise, the y and z directions should prepend
"dy_" and "dz_", respectively.
Example:
dufuncs
{
dx_g00,dx_g01,
dy_g00,dy_g01,
dz_g00,dz_g01
}
In this example, x, y, and z derivatives
of ufuncs g00 and g01 are supplied by the driver. If
all derivatives of all ufuncs are needed,
simply omit the dufuncs keyword
from the setup file. If no derivatives are needed, then
specify dufuncs to be empty.
Example:
dufuncs
{
}
No derivatives of the ufuncs will be calculated by the driver in this case.
If the keyword No HyperDerivs is placed in the setup file, no spatial
derivatives will be calculated by the driver, regardless of what may be
found in the dufuncs brackets.
vfuncs and dvfuncs
Most of the same instructions apply to vfuncs and dvfuncs as apply to ufuncs
and dvfuncs. The differences are:
- Only 1 time level of vfuncs exist
- The diss keyword has no impact on vfuncs -- dissipation is never applied to a vfunc ( it is not evolved ).
Like ufuncs, vfuncs can be declared in multiple groups:
Example:
vfuncs [G]
{
Tmunu00,Tmunu01
}
vfuncs [M]
{
divB
}
The total number of vfuncs is counted by the driver and accessed
using the "NV" statement. Individual groupings, as in the example above,
result, append the characters in the bracket to "NV_". In the
example above, NV_M is 1, NV_G is 2, and NV is 3.
Like dufuncs, dvfuncs list the vfuncs for which the driver
should provide spatial derivatives. If the dvfuncs keyword
is missing, the driver will
calculate derivatives of all vfuncs. If they derivatives are
listed explicitly, only those listed will be calculated. Like dufuncs, the list
associated with dvfuncs should prepend either "dx_", "dy_", or "dz_" to each
vfunc for which a derivative is needed.
wfuncs
wfuncs contain all other necessary gridfunctions for evolution.
Some driver level gridfunctions are required to be defined in the
user defined setup file. These include:
- flag : gridfunction for flagging points for refinement
- error : gridfunction containing the results of AMR refinement criteria
- chr : gridfunction containing grid flags (See had/include/chr.inc for the meaning of the grid flags found in chr )
The number of wfuncs is specified by the driver and called "NW".
asurface, bsurface, csurface
The asurface, bsurface, and csurface keywords
allocate 2-D functions used in surface extraction. The size of the 2-D
grid functions is determined by the extraction surface parameters specified
in the surface extraction documentation.
Notes
See Also
surface extraction,
NU,NV,NW,
chr gridfunction
Index of all manual pages
Examples
had/src/hyperCurvedWave/setup