feenox.1

.\" Automatically generated by Pandoc 3.2
.\"
.TH "FEENOX" "1" "2025\-04\-02" "FeenoX" "FeenoX User Manual"
.SH NAME
FeenoX \- a cloud\-first free no\-X uniX\-like finite\-element(ish)
computational engineering tool
.SH SYNOPSIS
The basic usage is to execute the \f[B]feenox\f[R] binary passing a path
to an input file that defines the problem, along with other options and
command\-line replacement arguments which are explained below:
.PP
\f[B]feenox\f[R] [\f[I]options\f[R] \&...]
\f[I]input\-file\f[R]
[\f[I]optional_commandline_replacement_arguments\f[R] \&...]
.PP
For large problems that do not fit in a single computer, a parallel run
using \f[B]mpirun\f[R]\f[CR](1)\f[R] will be needed:
.PP
\f[B]mpirun\f[R] \f[B]\-n\f[R] \f[I]number_of_threads\f[R]
\f[B]feenox\f[R] [\f[I]options\f[R] \&...]
\f[I]input\-file\f[R]
[\f[I]optional_commandline_replacement_arguments\f[R] \&...]
.SH DESCRIPTION
FeenoX is a computational tool that can solve engineering problems which
are usually casted as differential\-algebraic equations (DAEs) or
partial differential equations (PDEs).
It is to finite elements programs and libraries what Markdown is to Word
and TeX, respectively.
In particular, it can solve
.IP \[bu] 2
dynamical systems defined by a set of user\-provided DAEs (such as plant
control dynamics for example)
.IP \[bu] 2
mechanical elasticity
.IP \[bu] 2
heat conduction
.IP \[bu] 2
structural modal analysis
.IP \[bu] 2
neutron diffusion
.IP \[bu] 2
neutron transport
.PP
FeenoX reads a plain\-text input file which contains the problem
definition and writes 100%\-user defined results in ASCII (through
\f[CR]PRINT\f[R] or other user\-defined output instructions within the
input file).
For PDE problems, it needs a reference to at least one Gmsh mesh file
for the discretization of the domain.
It can write post\-processing views in either \f[CR].msh\f[R],
\f[CR].vtu\f[R] or \f[CR].vtk\f[R] formats.
.PP
Keep in mind that FeenoX is just a back end reading a set of input files
and writing a set of output files following the design philosophy of
Unix (separation, composition, representation, economy, extensibility,
etc).
Think of it as a transfer function (or a filter in computer\-science
jargon) between input files and output files:
.IP
.EX
                             +\-\-\-\-\-\-\-\-\-\-\-\-+
 mesh (*.msh)  }             |            |             { terminal
 data (*.dat)  } input \-\-\-\-> |   FeenoX   |\-\-\-\-> output { data files
 input (*.fee) }             |            |             { post (vtk/msh)
                             +\-\-\-\-\-\-\-\-\-\-\-\-+
.EE
.PP
Following the Unix programming philosophy, there are no graphical
interfaces attached to the FeenoX core, although a wide variety of pre
and post\-processors can be used with FeenoX.
To illustrate the transfer\-function approach, consider the following
input file that solves Laplace\[cq]s equation ∇^2^\f[I]ϕ\f[R] = 0 on a
square with some space\-dependent boundary conditions:
.PP
\f[I]ϕ\f[R](\f[I]x\f[R], \f[I]y\f[R]) = +\f[I]y\f[R]   for
\f[I]x\f[R] = −1 (left)
.PP
\f[I]ϕ\f[R](\f[I]x\f[R], \f[I]y\f[R]) = −\f[I]y\f[R]   for
\f[I]x\f[R] = +1 (right)
.PP
∇\f[I]ϕ\f[R] ⋅ \f[I]n̂\f[R] = sin (\f[I]π\f[R]/2\f[I]x\f[R])   for
\f[I]y\f[R] = −1 (bottom)
.PP
∇\f[I]ϕ\f[R] ⋅ \f[I]n̂\f[R] = 0   for \f[I]y\f[R] = +1 (top)
.IP
.EX
PROBLEM laplace 2d
READ_MESH square\-centered.msh # [\-1:+1]x[\-1:+1]

# boundary conditions
BC left    phi=+y
BC right   phi=\-y
BC bottom  dphidn=sin(pi/2*x)
BC top     dphidn=0

SOLVE_PROBLEM

# same output in .msh and in .vtk formats
WRITE_MESH laplace\-square.msh phi VECTOR dphidx dphidy 0
WRITE_MESH laplace\-square.vtk phi VECTOR dphidx dphidy 0
.EE
.PP
\
.PP
Laplace\[cq]s equation solved with FeenoX
.PP
The \f[CR].msh\f[R] file can be post\-processed with Gmsh, and the
\f[CR].vtu\f[R]/\f[CR].vtk\f[R] file can be post\-processed with
Paraview.
See https://www.caeplex.com for a mobile\-friendly web\-based interface
for solving finite elements in the cloud directly from the browser.
.SH OPTIONS
.IP
.EX
feenox [options] inputfile [replacement arguments] [petsc options]  
.EE
.TP
\f[CR]\-h\f[R], \f[CR]\-\-help\f[R]
display options and detailed explanations of command\-line usage
.TP
\f[CR]\-v\f[R], \f[CR]\-\-version\f[R]
display brief version information and exit
.TP
\f[CR]\-V\f[R], \f[CR]\-\-versions\f[R]
display detailed version information
.TP
\f[CR]\-c\f[R], \f[CR]\-\-check\f[R]
validates if the input file is sane or not
.TP
\f[CR]\-\-pdes\f[R]
list the types of \f[CR]PROBLEM\f[R]s that FeenoX can solve, one per
line
.TP
\f[CR]\-\-elements_info\f[R]
output a document with information about the supported element types
.TP
\f[CR]\-\-ast\f[R]
dump an abstract syntax tree of the input
.TP
\f[CR]\-\-linear\f[R]
force FeenoX to solve the PDE problem as linear
.TP
\f[CR]\-\-non\-linear\f[R]
force FeenoX to solve the PDE problem as non\-linear
.TP
\f[CR]\-\-progress\f[R]
print ASCII progress bars when solving PDEs
.TP
\f[CR]\-\-mumps\f[R]
ask PETSc to use the direct linear solver MUMPS
.PP
Instructions will be read from standard input if \[lq]\-\[rq] is passed
as \f[CR]inputfile\f[R], i.e.
.IP
.EX
$ echo \[aq]PRINT 2+2\[aq] | feenox \-
4
.EE
.PP
The optional \f[CR][replacement arguments]\f[R] part of the command line
mean that each argument after the input file that does not start with an
hyphen will be expanded verbatim in the input file in each occurrence of
\f[CR]$1\f[R], \f[CR]$2\f[R], etc.
For example
.IP
.EX
$ echo \[aq]PRINT $1+$2\[aq] | feenox \- 3 4
7
.EE
.PP
PETSc and SLEPc options can be passed in \f[CR][petsc options]\f[R] (or
\f[CR][options]\f[R]) as well, with the difference that two hyphens have
to be used instead of only once.
For example, to pass the PETSc option \f[CR]\-ksp_view\f[R] the actual
FeenoX invocation should be
.IP
.EX
$ feenox input.fee \-\-ksp_view
.EE
.PP
For PETSc options that take values, en equal sign has to be used:
.IP
.EX
$ feenox input.fee \-\-mg_levels_pc_type=sor
.EE
.PP
See https://www.seamplex.com/feenox/examples for annotated examples.
.SH EXAMPLES
.SH EXIT STATUS
.SH ENVIRONMENT
.SH FILES
.SH CONFORMING TO
.SH INPUT\-FILE KEYWORDS
.SS GENERIC KEYWORDS
.SS \f[CR]ABORT\f[R]
.PP
Catastrophically abort the execution and quit FeenoX.
.IP
.EX
ABORT  
.EE
.PP
Whenever the instruction \f[CR]ABORT\f[R] is executed, FeenoX quits with
a non\-zero error leve.
It does not close files nor unlock shared memory objects.
The objective of this instruction is to either debug complex input files
by using only parts of them or to conditionally abort the execution
using \f[CR]IF\f[R] clauses.
.SS \f[CR]ALIAS\f[R]
.PP
Define a scalar alias of an already\-defined identifier.
.IP
.EX
ALIAS { <new_var_name> IS <existing_object> | <existing_object> AS <new_name> }  
.EE
.PP
The existing object can be a variable, a vector element or a matrix
element.
In the first case, the name of the variable should be given as the
existing object.
In the second case, to alias the second element of vector \f[CR]v\f[R]
to the new name \f[CR]new\f[R], \f[CR]v(2)\f[R] should be given as the
existing object.
In the third case, to alias second element (2,3) of matrix \f[CR]M\f[R]
to the new name \f[CR]new\f[R], \f[CR]M(2,3)\f[R] should be given as the
existing object.
.SS \f[CR]CLOSE\f[R]
.PP
Explicitly close a file after input/output.
.IP
.EX
CLOSE <name>  
.EE
.PP
The given \f[CR]<name>\f[R] can be either a fixed\-string path or an
already\-defined \f[CR]FILE\f[R].
.SS \f[CR]DEFAULT_ARGUMENT_VALUE\f[R]
.PP
Give a default value for an optional commandline argument.
.IP
.EX
DEFAULT_ARGUMENT_VALUE <constant> <string>  
.EE
.PP
If a \f[CR]$n\f[R] construction is found in the input file but the
commandline argument was not given, the default behavior is to fail
complaining that an extra argument has to be given in the commandline.
With this keyword, a default value can be assigned if no argument is
given, thus avoiding the failure and making the argument optional.
The \f[CR]<constant>\f[R] should be 1, 2, 3, etc.
and \f[CR]<string>\f[R] will be expanded character\-by\-character where
the \f[CR]$n\f[R] construction is.
Whether the resulting expression is to be interpreted as a string or as
a numerical expression will depend on the context.
.SS \f[CR]FILE\f[R]
.PP
Define a file with a particularly formatted name to be used either as
input or as output.
.IP
.EX
< FILE | OUTPUT_FILE | INPUT_FILE > <name> PATH <format> expr_1 expr_2 ... expr_n [ INPUT | OUTPUT | APPEND | MODE <fopen_mode> ]  
.EE
.PP
For reading or writing into files with a fixed path, this instruction is
usually not needed as the \f[CR]FILE\f[R] keyword of other instructions
(such as \f[CR]PRINT\f[R] or \f[CR]MESH\f[R]) can take a fixed\-string
path as an argument.
However, if the file name changes as the execution progresses (say
because one file for each step is needed), then an explicit
\f[CR]FILE\f[R] needs to be defined with this keyword and later
referenced by the given name.
.PD 0
.P
.PD
The path should be given as a \f[CR]printf\f[R]\-like format string
followed by the expressions which should be evaluated in order to obtain
the actual file path.
The expressions will always be floating\-point expressions, but the
particular integer specifier \f[CR]%d\f[R] is allowed and internally
transformed to \f[CR]%.0f\f[R].
The file can be explicitly defined and \f[CR]INPUT\f[R],
\f[CR]OUTPUT\f[R] or a certain \f[CR]fopen()\f[R] mode can be given
(i.e.\ \[lq]a\[rq]).
If not explicitly given, the nature of the file will be taken from
context, i.e.\ \f[CR]FILE\f[R]s in \f[CR]PRINT\f[R] will be
\f[CR]OUTPUT\f[R] and \f[CR]FILE\f[R]s in \f[CR]FUNCTION\f[R] will be
\f[CR]INPUT\f[R].
This keyword just defines the \f[CR]FILE\f[R], it does not open it.
The file will be actually opened (and eventually closed) automatically.
In the rare case where the automated opening and closing does not fit
the expected workflow, the file can be explicitly opened or closed with
the instructions \f[CR]FILE_OPEN\f[R] and \f[CR]FILE_CLOSE\f[R].
.SS \f[CR]FIT\f[R]
.PP
Find parameters to fit an analytical function to a pointwise\-defined
function.
.IP
.EX
FIT <function_to_be_fitted>  TO <function_with_data> VIA <var_1> <var_2> ... <var_n>
 [ GRADIENT <expr_1> <expr_2> ... <expr_n> ]
 [ RANGE_MIN <expr_1> <expr_2> ... <expr_j> ]
 [ RANGE_MAX <expr_1> <expr_2> ... <expr_n> ]
 [ TOL_REL <expr> ] [ TOL_ABS <expr> ] [ MAX_ITER <expr> ]
 [ VERBOSE ]  
.EE
.PP
The function with the data has to be point\-wise defined (i.e.\ a
\f[CR]FUNCTION\f[R] read from a file, with inline \f[CR]DATA\f[R] or
defined over a mesh).
The function to be fitted has to be parametrized with at least one of
the variables provided after the \f[CR]USING\f[R] keyword.
For example to
fit\ \f[I]f\f[R](\f[I]x\f[R], \f[I]y\f[R]) = \f[I]a\f[R]\f[I]x\f[R]^2^ + \f[I]b\f[R]\f[I]s\f[R]\f[I]q\f[R]\f[I]r\f[R]\f[I]t\f[R](\f[I]y\f[R])
to a pointwise\-defined function\ \f[I]g\f[R](\f[I]x\f[R], \f[I]y\f[R])
one gives \f[CR]FIT f TO g VIA a b\f[R].
Only the names of the functions have to be given, not the arguments.
Both functions have to have the same number of arguments.
The initial guess of the solution is given by the initial value of the
variables after the \f[CR]VIA\f[R] keyword.
Analytical expressions for the gradient of the function to be fitted
with respect to the parameters to be fitted can be optionally given with
the \f[CR]GRADIENT\f[R] keyword.
If none is provided, the gradient will be computed numerically using
finite differences.
A range over which the residuals are to be minimized can be given with
\f[CR]RANGE_MIN\f[R] and \f[CR]RANGE_MAX\f[R].
The expressions give the range of the arguments of the functions, not of
the parameters.
For multidimensional fits, the range is an hypercube.
If no range is given, all the definition points of the function with the
data are used for the fit.
Convergence can be controlled by giving the relative and absolute
tolreances with \f[CR]TOL_REL\f[R] (default
\f[CR]DEFAULT_NLIN_FIT_EPSREL\f[R]) and \f[CR]TOL_ABS\f[R] (default
\f[CR]DEFAULT_NLIN_FIT_EPSABS\f[R]), and with the maximum number of
iterations \f[CR]MAX_ITER\f[R] (default DEFAULT_NLIN_FIT_MAX_ITER).
If the optional keyword \f[CR]VERBOSE\f[R] is given, some data of the
intermediate steps is written in the standard output.
.SS \f[CR]FUNCTION\f[R]
.PP
Define a scalar function of one or more variables.
.IP
.EX
FUNCTION <function_name>(<var_1>[,var2,...,var_n]) { 
   = <expr> | 
   FILE { <file> } | 
   VECTORS <vector_1> <vector_2> ... <vector_n> <vector_data> | 
   MESH <mesh> | 
   DATA <num_1> <num_2> ... <num_N> 
 } 
 [ COLUMNS <expr_1> <expr_2> ... <expr_n> <expr_n+1> ] 
 [ INTERPOLATION { linear | polynomial | spline | spline_periodic | akima | akima_periodic | steffen | 
 nearest | shepard | shepard_kd | bilinear } ] 
 [ INTERPOLATION_THRESHOLD <expr> ] [ SHEPARD_RADIUS <expr> ] [ SHEPARD_EXPONENT <expr> ]  
.EE
.PP
The number of variables \f[I]n\f[R] is given by the number of arguments
given between parenthesis after the function name.
The arguments are defined as new variables if they had not been already
defined explicitly as scalar variables.
If the function is given as an algebraic expression, the short\-hand
operator \f[CR]=\f[R] (or \f[CR]:=\f[R] for compatibility with Maxima)
can be used.
That is to say, \f[CR]FUNCTION f(x) = x\[ha]2\f[R] is equivalent to
\f[CR]f(x) = x\[ha]2\f[R] (or \f[CR]f(x) := x\[ha]2\f[R]).
If a \f[CR]FILE\f[R] is given, an ASCII file containing at least
\f[I]n\f[R] + 1 columns is expected.
By default, the first \f[I]n\f[R] columns are the values of the
arguments and the last column is the value of the function at those
points.
The order of the columns can be changed with the keyword
\f[CR]COLUMNS\f[R], which expects \f[I]n\f[R] + 1 expressions
corresponding to the column numbers.
If \f[CR]VECTORS\f[R] is given, a set of \f[I]n\f[R] + 1 vectors of the
same size is expected.
The first \f[I]n\f[R] correspond to the arguments and the last one to
the function values.
If \f[CR]MESH\f[R] is given, the function is point\-wise defined over
the mesh topology.
That is to say, the independent variables (i.e.\ the spatial
coordinates) coincide with the mesh nodes.
The dependent variable (i.e.\ the function value) is set by
\[lq]filling\[rq] a vector named \f[CR]vec_f\f[R] (where \f[CR]f\f[R]
has to be replaced with the function name) of size equal to the number
of nodes.
.PD 0
.P
.PD
The function can be pointwise\-defined inline in the input using
\f[CR]DATA\f[R].
This should be the last keyword of the line, followed by
\f[I]N\f[R] = \f[I]k\f[R] ⋅ (\f[I]n\f[R] + 1) expressions
giving\ \f[I]k\f[R] definition points: \f[I]n\f[R] arguments and the
value of the function.
Multiline continuation using brackets \f[CR]{\f[R] and \f[CR]}\f[R] can
be used for a clean data organization.
Interpolation schemes can be given for either one or multi\-dimensional
functions with \f[CR]INTERPOLATION\f[R].
Available schemes for \f[I]n\f[R] = 1 are:
.IP \[bu] 2
linear
.IP \[bu] 2
polynomial, the grade is equal to the number of data minus one
.IP \[bu] 2
spline, cubic (needs at least 3 points)
.IP \[bu] 2
spline_periodic
.IP \[bu] 2
akima (needs at least 5 points)
.IP \[bu] 2
akima_periodic (needs at least 5 points)
.IP \[bu] 2
steffen, always\-monotonic splines\-like interpolator
.PP
Default interpolation scheme for one\-dimensional functions is
\f[CR]DEFAULT_INTERPOLATION\f[R].
.PP
Available schemes for \f[I]n\f[R] > 1 are:
.IP \[bu] 2
nearest, \f[I]f\f[R](\f[I]x⃗\f[R]) is equal to the value of the closest
definition point
.IP \[bu] 2
shepard, inverse distance weighted average definition points (might lead
to inefficient evaluation)
.IP \[bu] 2
shepard_kd, average of definition points within a kd\-tree (more
efficient evaluation provided \f[CR]SHEPARD_RADIUS\f[R] is set to a
proper value)
.IP \[bu] 2
bilinear, only available if the definition points configure an
structured hypercube\-like grid.
If \f[I]n\f[R] > 3, \f[CR]SIZES\f[R] should be given.
.PP
For \f[I]n\f[R] > 1, if the euclidean distance between the arguments and
the definition points is smaller than
\f[CR]INTERPOLATION_THRESHOLD\f[R], the definition point is returned and
no interpolation is performed.
Default value is square root of
\f[CR]DEFAULT_MULTIDIM_INTERPOLATION_THRESHOLD\f[R].
.PP
The initial radius of points to take into account in
\f[CR]shepard_kd\f[R] is given by \f[CR]SHEPARD_RADIUS\f[R].
If no points are found, the radius is double until at least one
definition point is found.
The radius is doubled until at least one point is found.
Default is \f[CR]DEFAULT_SHEPARD_RADIUS\f[R].
The exponent of the \f[CR]shepard\f[R] method is given by
\f[CR]SHEPARD_EXPONENT\f[R].
Default is \f[CR]DEFAULT_SHEPARD_EXPONENT\f[R].
.SS \f[CR]IF\f[R]
.PP
Execute a set of instructions if a condition is met.
.IP
.EX
IF expr 
  <block_of_instructions_if_expr_is_true> 
 [ ELSE  
  <block_of_instructions_if_expr_is_false> ] 
 ENDIF  
.EE
.SS \f[CR]IMPLICIT\f[R]
.PP
Define whether implicit definition of variables is allowed or not.
.IP
.EX
IMPLICIT { NONE | ALLOWED }  
.EE
.PP
By default, FeenoX allows variables (but not vectors nor matrices) to be
implicitly declared.
To avoid introducing errors due to typos, explicit declaration of
variables can be forced by giving \f[CR]IMPLICIT NONE\f[R].
Whether implicit declaration is allowed or explicit declaration is
required depends on the last \f[CR]IMPLICIT\f[R] keyword given, which by
default is \f[CR]ALLOWED\f[R].
.SS \f[CR]INCLUDE\f[R]
.PP
Include another FeenoX input file.
.IP
.EX
INCLUDE <file_path> [ FROM <num_expr> ] [ TO <num_expr> ]  
.EE
.PP
Includes the input file located in the string \f[CR]file_path\f[R] at
the current location.
The effect is the same as copying and pasting the contents of the
included file at the location of the \f[CR]INCLUDE\f[R] keyword.
The path can be relative or absolute.
Note, however, that when including files inside \f[CR]IF\f[R] blocks
that instructions are conditionally\-executed but all definitions (such
as function definitions) are processed at parse\-time independently from
the evaluation of the conditional.
The included file has to be an actual file path (i.e.\ it cannot be a
FeenoX \f[CR]FILE\f[R]) because it needs to be resolved at parse time.
Yet, the name can contain a commandline replacement argument such as
\f[CR]$1\f[R] so \f[CR]INCLUDE $1.fee\f[R] will include the file
specified after the main input file in the command line.
The optional \f[CR]FROM\f[R] and \f[CR]TO\f[R] keywords can be used to
include only portions of a file.
.SS \f[CR]MATRIX\f[R]
.PP
Define a matrix.
.IP
.EX
MATRIX <name> ROWS <expr> COLS <expr> [ DATA <expr_1> <expr_2> ... <expr_n> |  
.EE
.PP
A new matrix of the prescribed size is defined.
The number of rows and columns can be an expression which will be
evaluated the very first time the matrix is used and then kept at those
constant values.
All elements will be initialized to zero unless \f[CR]DATA\f[R] is given
(which should be the last keyword of the line), in which case the
expressions will be evaluated the very first time the matrix is used and
row\-major\-assigned to each of the elements.
If there are less elements than the matrix size, the remaining values
will be zero.
If there are more elements than the matrix size, the values will be
ignored.
.SS \f[CR]OPEN\f[R]
.PP
Explicitly open a file for input/output.
.IP
.EX
OPEN <name> [ MODE <fopen_mode> ]  
.EE
.PP
The given \f[CR]<name>\f[R] can be either a fixed\-string path or an
already\-defined \f[CR]FILE\f[R].
The mode is only taken into account if the file is not already defined.
Default is write \f[CR]w\f[R].
.SS \f[CR]PRINT\f[R]
.PP
Write plain\-text and/or formatted data to the standard output or into
an output file.
.IP
.EX
PRINT [ <object_1> <object_2> ... <object_n> ] [ TEXT <string_1> ... TEXT <string_n> ] 
 [ FILE { <file_path> | <file_id> } ] [ HEADER ] [ NONEWLINE ] [ SEP <string> ] 
 [ SKIP_STEP <expr> ] [ SKIP_STATIC_STEP <expr> ] [ SKIP_TIME <expr> ] [ SKIP_HEADER_STEP <expr> ] 
  
.EE
.PP
Each argument \f[CR]object\f[R] which is not a keyword of the
\f[CR]PRINT\f[R] instruction will be part of the output.
Objects can be either a matrix, a vector or any valid scalar algebraic
expression.
If the given object cannot be solved into a valid matrix, vector or
expression, it is treated as a string literal if \f[CR]IMPLICIT\f[R] is
\f[CR]ALLOWED\f[R], otherwise a parser error is raised.
To explicitly interpret an object as a literal string even if it
resolves to a valid numerical expression, it should be prefixed with the
\f[CR]TEXT\f[R] keyword such as \f[CR]PRINT TEXT 1+1\f[R] that would
print \f[CR]1+1\f[R] instead of \f[CR]2\f[R].
Objects and string literals can be mixed and given in any order.
Hashes \f[CR]#\f[R] appearing literal in text strings have to be quoted
to prevent the parser to treat them as comments within the FeenoX input
file and thus ignoring the rest of the line, like
\f[CR]PRINT \[dq]\[rs]# this is a printed comment\[dq]\f[R].
Whenever an argument starts with a porcentage sign \f[CR]%\f[R], it is
treated as a C \f[CR]printf\f[R]\-compatible format specifier and all
the objects that follow it are printed using the given format until a
new format definition is found.
The objects are treated as double\-precision floating point numbers, so
only floating point formats should be given.
See the \f[CR]printf(3)\f[R] man page for further details.
The default format is \f[CR]DEFAULT_PRINT_FORMAT\f[R].
Matrices, vectors, scalar expressions, format modifiers and string
literals can be given in any desired order, and are processed from left
to right.
Vectors are printed element\-by\-element in a single row.
See \f[CR]PRINT_VECTOR\f[R] to print one or more vectors with one
element per line (i.e.\ vertically).
Matrices are printed element\-by\-element in a single line using
row\-major ordering if mixed with other objects but in the natural row
and column fashion if it is the only given object in the
\f[CR]PRINT\f[R] instruction.
If the \f[CR]FILE\f[R] keyword is not provided, default is to write to
\f[CR]stdout\f[R].
If the \f[CR]HEADER\f[R] keyword is given, a single line containing the
literal text given for each object is printed at the very first time the
\f[CR]PRINT\f[R] instruction is processed, starting with a hash
\f[CR]#\f[R] character.
.PD 0
.P
.PD
If the \f[CR]NONEWLINE\f[R] keyword is not provided, default is to write
a newline \f[CR]\[rs]n\f[R] character after all the objects are
processed.
Otherwise, if the last token to be printed is a numerical value, a
separator string will be printed but not the newline \f[CR]\[rs]n\f[R]
character.
If the last token is a string, neither the separator nor the newline
will be printed.
The \f[CR]SEP\f[R] keyword expects a string used to separate printed
objects.
To print objects without any separation in between give an empty string
like \f[CR]SEP \[dq]\[dq]\f[R].
The default is a tabulator character `DEFAULT_PRINT_SEPARATOR'
character.
To print an empty line write \f[CR]PRINT\f[R] without arguments.
By default the \f[CR]PRINT\f[R] instruction is evaluated every step.
If the \f[CR]SKIP_STEP\f[R] (\f[CR]SKIP_STATIC_STEP\f[R]) keyword is
given, the instruction is processed only every the number of transient
(static) steps that results in evaluating the expression, which may not
be constant.
The \f[CR]SKIP_HEADER_STEP\f[R] keyword works similarly for the optional
\f[CR]HEADER\f[R] but by default it is only printed once.
The \f[CR]SKIP_TIME\f[R] keyword use time advancements to choose how to
skip printing and may be useful for non\-constant time\-step problems.
.SS \f[CR]PRINTF\f[R]
.PP
Instruction akin to C\[cq]s \f[CR]printf\f[R].
Instruction akin to C\[cq]s \f[CR]printf\f[R] executed locally from all
MPI ranks.
.IP
.EX
PRINTF PRINTF_ALL format_string [ expr_1 [ expr_2 [ ... ] ] ]  
.EE
.PP
The \f[CR]format_string\f[R] should be a \f[CR]printf\f[R]\-like string
containing double\-precision format specifiers.
A matching number of expressions should be given.
No newline is written if not explicitly asked for in the format string
with \f[CR]\[rs]n\f[R].
.PD 0
.P
.PD
Do not ask for string literals \f[CR]%s\f[R].
.PD 0
.P
.PD
As always, to get a literal \f[CR]%\f[R] use \f[CR]%%\f[R] in the format
string.
.SS \f[CR]PRINT_FUNCTION\f[R]
.PP
Print one or more functions as a table of values of dependent and
independent variables.
.IP
.EX
PRINT_FUNCTION <function_1> [ { function | expr } ... { function | expr } ] 
 [ FILE { <file_path> | <file_id> } ] [ HEADER ] 
 [ MIN <expr_1> <expr_2> ... <expr_k> ] [ MAX <expr_1> <expr_2> ... <expr_k> ] 
 [ STEP <expr_1> <expr_2> ... <expr_k> ] [ NSTEPs <expr_1> <expr_2> ... <expr_k> ] 
 [ FORMAT <print_format> ] <vector_1> [ { vector | expr } ... { vector | expr } ]  
.EE
.PP
Each argument should be either a function or an expression.
The output of this instruction consists of\ \f[I]n\f[R] + \f[I]k\f[R]
columns, where\ \f[I]n\f[R] is the number of arguments of the first
function of the list and\ \f[I]k\f[R] is the number of functions and
expressions given.
The first\ \f[I]n\f[R] columns are the arguments (independent variables)
and the last\ \f[I]k\f[R] one has the evaluated functions and
expressions.
The columns are separated by a tabulator, which is the format that most
plotting tools understand.
Only function names without arguments are expected.
All functions should have the same number of arguments.
Expressions can involve the arguments of the first function.
If the \f[CR]FILE\f[R] keyword is not provided, default is to write to
\f[CR]stdout\f[R].
If \f[CR]HEADER\f[R] is given, the output is prepended with a single
line containing the names of the arguments and the names of the
functions, separated by tabs.
The header starts with a hash\ \f[CR]#\f[R] that usually acts as a
comment and is ignored by most plotting tools.
If there is no explicit range where to evaluate the functions and the
first function is point\-wise defined, they are evalauted at the points
of definition of the first one.
The range can be explicitly given as a product of\ \f[I]n\f[R]
ranges\ [\f[I]x\f[R]~\f[I]i\f[R], min ~, \f[I]x\f[R]~\f[I]i\f[R], max ~]
for \f[I]i\f[R] = 1, \&..., \f[I]n\f[R].
.PD 0
.P
.PD
The values \f[I]x\f[R]~\f[I]i\f[R], min ~ and
\f[I]x\f[R]~\f[I]i\f[R], max ~ are given with the \f[CR]MIN\f[R]
\f[I]and\f[R] \f[CR]MAX\f[R] keywords.
The discretization steps of the ranges are given by either
\f[CR]STEP\f[R] that gives\ \f[I]δ\f[R]\f[I]x\f[R] \f[I]or\f[R]
\f[CR]NSTEPS\f[R] that gives the number of steps.
If the first function is not point\-wise defined, the ranges are
mandatory.
.SS \f[CR]PRINT_VECTOR\f[R]
.PP
Print the elements of one or more vectors, one element per line.
.IP
.EX
PRINT_VECTOR 
 [ FILE { <file_path> | <file_id> } ] [ HEADER ] 
 [ SEP <string> ]  
.EE
.PP
Each argument should be either a vector or an expression of the
integer\ \f[CR]i\f[R].
If the \f[CR]FILE\f[R] keyword is not provided, default is to write to
\f[CR]stdout\f[R].
If \f[CR]HEADER\f[R] is given, the output is prepended with a single
line containing the names of the arguments and the names of the
functions, separated by tabs.
The header starts with a hash\ \f[CR]#\f[R] that usually acts as a
comment and is ignored by most plotting tools.
The \f[CR]SEP\f[R] keyword expects a string used to separate printed
objects.
To print objects without any separation in between give an empty string
like \f[CR]SEP \[dq]\[dq]\f[R].
The default is a tabulator character `DEFAULT_PRINT_SEPARATOR'
character.
.SS \f[CR]SOLVE\f[R]
.PP
Solve a (small) system of non\-linear equations.
.IP
.EX
SOLVE FOR <n> UNKNOWNS <var_1> <var_2> ... <var_n> [ METHOD { dnewton | hybrid | hybrids | broyden } ]
 [ EPSABS <expr> ] [ EPSREL <expr> ] [ MAX_ITER <expr> ]  
.EE
.SS \f[CR]SORT_VECTOR\f[R]
.PP
Sort the elements of a vector, optionally making the same rearrangement
in another vector.
.IP
.EX
SORT_VECTOR <vector> [ ASCENDING | DESCENDING ] [ <other_vector> ]  
.EE
.PP
This instruction sorts the elements of \f[CR]<vector>\f[R] into either
ascending or descending numerical order.
If \f[CR]<other_vector>\f[R] is given, the same rearrangement is made on
it.
Default is ascending order.
.SS \f[CR]VAR\f[R]
.PP
Explicitly define one or more scalar variables.
.IP
.EX
VAR <name_1> [ <name_2> ] ... [ <name_n> ]  
.EE
.PP
When implicit definition is allowed (see \f[CR]IMPLICIT\f[R]), scalar
variables need not to be defined before being used if from the context
FeenoX can tell that an scalar variable is needed.
For instance, when defining a function like \f[CR]f(x) = x\[ha]2\f[R] it
is not needed to declare \f[CR]x\f[R] explicitly as a scalar variable.
But if one wants to define a function like
\f[CR]g(x) = integral(f(x\[aq]), x\[aq], 0, x)\f[R] then the variable
\f[CR]x\[aq]\f[R] needs to be explicitly defined as
\f[CR]VAR x\[aq]\f[R] before the integral.
.SS \f[CR]VECTOR\f[R]
.PP
Define a vector.
.IP
.EX
VECTOR <name> SIZE <expr> [ FUNCTION_DATA <function> ] [ DATA <expr_1> <expr_2> ... <expr_n> |  
.EE
.PP
A new vector of the prescribed size is defined.
The size can be an expression which will be evaluated the very first
time the vector is used and then kept at that constant value.
If the keyword \f[CR]FUNCTION_DATA\f[R] is given, the elements of the
vector will be synchronized with the inpedendent values of the function,
which should be point\-wise defined.
The sizes of both the function and the vector should match.
All elements will be initialized to zero unless \f[CR]DATA\f[R] is given
(which should be the last keyword of the line), in which case the
expressions will be evaluated the very first time the vector is used and
assigned to each of the elements.
If there are less elements than the vector size, the remaining values
will be zero.
If there are more elements than the vector size, the values will be
ignored.
.SS DAE\-RELATED KEYWORDS
.SS \f[CR]INITIAL_CONDITIONS\f[R]
.PP
Define how initial conditions of DAE problems are computed.
.IP
.EX
INITIAL_CONDITIONS { AS_PROVIDED | FROM_VARIABLES | FROM_DERIVATIVES }  
.EE
.PP
In DAE problems, initial conditions may be either:
.IP \[bu] 2
equal to the provided expressions (\f[CR]AS_PROVIDED\f[R])
.IP \[bu] 2
the derivatives computed from the provided phase\-space variables
(\f[CR]FROM_VARIABLES\f[R])
.IP \[bu] 2
the phase\-space variables computed from the provided derivatives
(\f[CR]FROM_DERIVATIVES\f[R])
.PP
In the first case, it is up to the user to fulfill the DAE system
at\ \f[I]t\f[R] = 0.
If the residuals are not small enough, a convergence error will occur.
The \f[CR]FROM_VARIABLES\f[R] option means calling IDA\[cq]s
\f[CR]IDACalcIC\f[R] routine with the parameter
\f[CR]IDA_YA_YDP_INIT\f[R].
The \f[CR]FROM_DERIVATIVES\f[R] option means calling IDA\[cq]s
\f[CR]IDACalcIC\f[R] routine with the parameter IDA_Y_INIT.
Wasora should be able to automatically detect which variables in
phase\-space are differential and which are purely algebraic.
However, the \f[CR]DIFFERENTIAL\f[R] keyword may be used to explicitly
define them.
See the SUNDIALS documentation for further information.
.SS \f[CR]PHASE_SPACE\f[R]
.PP
Ask FeenoX to solve a set of algebraic\-differntial equations and define
the variables, vectors and/or matrices that span the phase space.
.IP
.EX
PHASE_SPACE PHASE_SPACE <vars> ... <vectors> ... <matrices> ...   
.EE
.SS \f[CR]TIME_PATH\f[R]
.PP
Force time\-dependent problems to pass through specific instants of
time.
.IP
.EX
TIME_PATH <expr_1> [ <expr_2>  [ ... <expr_n> ] ]  
.EE
.PP
The time step \f[CR]dt\f[R] will be reduced whenever the distance
between the current time \f[CR]t\f[R] and the next expression in the
list is greater than \f[CR]dt\f[R] so as to force \f[CR]t\f[R] to
coincide with the expressions given.
The list of expressions should evaluate to a sorted list of values for
all times.
.SS PDE\-RELATED KEYWORDS
.SS \f[CR]BC\f[R]
.PP
Define a boundary condition to be applied to faces, edges and/or
vertices.
.IP
.EX
BC <name> [ MESH <name> ] [ GROUP <name_1>  GROUP <name_2> ... ] [ <bc_data1> <bc_data2> ... ] [ GROUPS <name_1>  <name_2> ... ]  
.EE
.PP
If the name of the boundary condition matches a physical group in the
mesh, and neither \f[CR]GROUP\f[R] nor \f[CR]GROUPS\f[R] are given, it
is automatically linked to that physical group.
If there are many meshes, the mesh this keyword refers to has to be
given with \f[CR]MESH\f[R].
If the boundary condition applies to more than one physical group in the
mesh, they can be added using as many \f[CR]GROUP\f[R] keywords as
needed.
Each \f[CR]<bc_data>\f[R] argument is a single string whose meaning
depends on the type of problem being solved.
For instance \f[CR]T=150*sin(x/pi)\f[R] prescribes the temperature to
depend on space as the provided expression in a thermal problem and
\f[CR]fixed\f[R] fixes the displacements in all the directions in a
mechanical or modal problem.
See the particular section on boundary conditions for further details.
If the keyword \f[CR]GROUPS\f[R] is given, then the rest of the tokens
are parsed as group names where the boundary condition is applied.
If either \f[CR]GROUP\f[R] or \f[CR]GROUPS\f[R] are given explicitly,
then the \f[CR]BC\f[R] name is not used to try to implicitly link it to
a physical group in the mesh.
.SS \f[CR]COMPUTE_REACTION\f[R]
.PP
Compute the reaction (force, moment, power, etc.)
at selected face, edge or vertex.
.IP
.EX
COMPUTE_REACTION <physical_group> [ MOMENT [ X0 <expr> ] [ Y0 <expr> ] [ Z0 <expr> ] ] RESULT { <variable> | <vector> }  
.EE
.PP
If the \f[CR]MOMENT\f[R] keyword is not given, the zero\-th order
reaction is computed, i.e.\ force in elasticity and power in thermal.
If the \f[CR]MOMENT\f[R] keyword is given, then the coordinates of the
center can be given with \f[CR]X0\f[R], \f[CR]Y0\f[R] and \f[CR]Z0\f[R].
If they are not, the moment is computed about the barycenter of the
physical group.
The resulting reaction will be stored in the variable (thermal) or
vector (elasticity) provided.
If the variable or vector does not exist, it will be created.
.SS \f[CR]DUMP\f[R]
.PP
Dump raw PETSc objects used to solve PDEs into files.
.IP
.EX
DUMP [ FORMAT { binary | ascii | octave } ] [ K |   K_bc |   b |   b_bc |   M |   M_bc |  
.EE
.SS \f[CR]FIND_EXTREMA\f[R]
.PP
Find and/or compute the absolute extrema of a function or expression
over a mesh (or a subset of it).
.IP
.EX
FIND_EXTREMA { <expression> | <function> } [ OVER <physical_group> ] [ MESH <mesh_identifier> ] [ NODES | CELLS | GAUSS ]
 [ MIN <variable> ] [ MAX <variable> ] [ X_MIN <variable> ] [ X_MAX <variable> ] [ Y_MIN <variable> ] [ Y_MAX <variable> ] [ Z_MIN <variable> ] [ Z_MAX <variable> ] [ I_MIN <variable> ] [ I_MAX <variable> ]  
.EE
.PP
Either an expression or a function of space \f[I]x\f[R], \f[I]y\f[R]
and/or \f[I]z\f[R] should be given.
By default the search is performed over the highest\-dimensional
elements of the mesh, i.e.\ over the whole volume, area or length for
three, two and one\-dimensional meshes, respectively.
If the search is to be carried out over just a physical group, it has to
be given in \f[CR]OVER\f[R].
If there are more than one mesh defined, an explicit one has to be given
with \f[CR]MESH\f[R].
If neither \f[CR]NODES\f[R], \f[CR]CELLS\f[R] or \f[CR]GAUSS\f[R] is
given then the search is performed over the three of them.
With \f[CR]NODES\f[R] only the function or expression is evalauted at
the mesh nodes.
With \f[CR]CELLS\f[R] only the function or expression is evalauted at
the element centers.
With \f[CR]GAUSS\f[R] only the function or expression is evalauted at
the Gauss points.
The value of the absolute minimum (maximum) is stored in the variable
indicated by \f[CR]MIN\f[R] (\f[CR]MAX\f[R]).
If the variable does not exist, it is created.
The value of the \f[I]x\f[R]\-\f[I]y\f[R]\-\f[I]z\f[R]\ coordinate of
the absolute minimum (maximum) is stored in the variable indicated by
\f[CR]X_MIN\f[R]\-\f[CR]Y_MIN\f[R]\-\f[CR]Z_MIN\f[R]
(\f[CR]X_MAX\f[R]\-\f[CR]Y_MAX\f[R]\-\f[CR]Z_MAX\f[R]).
If the variable does not exist, it is created.
The index (either node or cell) where the absolute minimum (maximum) is
found is stored in the variable indicated by \f[CR]I_MIN\f[R]
(\f[CR]I_MAX\f[R]).
.SS \f[CR]INTEGRATE\f[R]
.PP
Spatially integrate a function or expression over a mesh (or a subset of
it).
.IP
.EX
INTEGRATE { <expression> | <function> } [ OVER <physical_group> ] [ MESH <mesh_identifier> ] [ GAUSS | CELLS ]
 RESULT <variable>
  
.EE
.PP
Either an expression or a function of space \f[I]x\f[R], \f[I]y\f[R]
and/or \f[I]z\f[R] should be given.
If the integrand is a function, do not include the arguments,
i.e.\ instead of \f[CR]f(x,y,z)\f[R] just write \f[CR]f\f[R].
The results should be the same but efficiency will be different (faster
for pure functions).
By default the integration is performed over the highest\-dimensional
elements of the mesh, i.e.\ over the whole volume, area or length for
three, two and one\-dimensional meshes, respectively.
If the integration is to be carried out over just a physical group, it
has to be given in \f[CR]OVER\f[R].
If there are more than one mesh defined, an explicit one has to be given
with \f[CR]MESH\f[R].
Either \f[CR]GAUSS\f[R] or \f[CR]CELLS\f[R] define how the integration
is to be performed.
With \f[CR]GAUSS\f[R] the integration is performed using the Gauss
points and weights associated to each element type.
With \f[CR]CELLS\f[R] the integral is computed as the sum of the product
of the integrand at the center of each cell (element) and the cell\[cq]s
volume.
Do expect differences in the results and efficiency between these two
approaches depending on the nature of the integrand.
The scalar result of the integration is stored in the variable given by
the mandatory keyword \f[CR]RESULT\f[R].
If the variable does not exist, it is created.
.SS \f[CR]MATERIAL\f[R]
.PP
Define a material its and properties to be used in volumes.
.IP
.EX
MATERIAL <name> [ MESH <name> ] [ LABEL <name_1>  [ LABEL <name_2> [ ... ] ] ] 
 [ <property_name_1>=<expr_1> [ <property_name_2>=<expr_2> [ ... ] ] ]  
.EE
.PP
If the name of the material matches a physical group in the mesh, it is
automatically linked to that physical group.
If there are many meshes, the mesh this keyword refers to has to be
given with \f[CR]MESH\f[R].
If the material applies to more than one physical group in the mesh,
they can be added using as many \f[CR]LABEL\f[R] keywords as needed.
The names of the properties in principle can be arbitrary, but each
problem type needs a minimum set of properties defined with particular
names.
For example, steady\-state thermal problems need at least the
conductivity which should be named\ \f[CR]k\f[R].
If the problem is transient, it will also need heat
capacity\ \f[CR]rhocp\f[R] or diffusivity\ \f[CR]alpha\f[R].
Mechanical problems need Young modulus\ \f[CR]E\f[R] and Poisson\[cq]s
ratio\ \f[CR]nu\f[R].
Modal also needs density\ \f[CR]rho\f[R].
Check the particular documentation for each problem type.
Besides these mandatory properties, any other one can be defined.
For instance, if one mandatory property depended on the concentration of
boron in the material, a new per\-material property can be added named
\f[CR]boron\f[R] and then the function \f[CR]boron(x,y,z)\f[R] can be
used in the expression that defines the mandatory property.
.SS \f[CR]PETSC_OPTIONS\f[R]
.PP
Pass verbatim options to PETSc.
.IP
.EX
PETSC_OPTIONS \[dq]command\-line options for PETSc\[dq]  
.EE
.PP
Options for PETSc can be passed either in at run time in the command
line (run with \f[CR]\-h\f[R] to see how) or they can be set in the
input file with \f[CR]PETSC_OPTIONS\f[R].
This is handy when a particular problem is best suited to be solved
using a particular set of options which can the be embedded into the
problem definition.
\[at]
.PD 0
.P
.PD
The string is passed verbatim to PETSc as if the options were set in the
command line.
Note that in this case, the string is passed verbatim to PETSc.
This means that they are non\-POSIX options but they have to be in the
native PETSc format.
That is to say, while in the command line one would give
\f[CR]\-\-ksp_view\f[R], here one has to give \f[CR]\-ksp_view\f[R].
Conversely, instead of \f[CR]\-\-mg_levels_pc_type=sor\f[R] one has to
give \f[CR]\-mg_levels_pc_type sor\f[R].
.SS \f[CR]PHYSICAL_GROUP\f[R]
.PP
Explicitly defines a physical group of elements on a mesh.
.IP
.EX
PHYSICAL_GROUP <name> [ MESH <name> ] [ DIMENSION <expr> ] [ ID <expr> ]
 [ MATERIAL <name> | | BC <name> [ BC ... ] ]
  
.EE
.PP
This keyword should seldom be needed.
Most of the times, a combination of \f[CR]MATERIAL\f[R] and
\f[CR]BC\f[R] ought to be enough for most purposes.
The name of the \f[CR]PHYSICAL_GROUP\f[R] keyword should match the name
of the physical group defined within the input file.
If there is no physical group with the provided name in the mesh, this
instruction has no effect.
If there are many meshes, an explicit mesh can be given with
\f[CR]MESH\f[R].
Otherwise, the physical group is defined on the main mesh.
An explicit dimension of the physical group can be provided with
\f[CR]DIMENSION\f[R].
An explicit id can be given with \f[CR]ID\f[R].
Both dimension and id should match the values in the mesh.
For volumetric elements, physical groups can be linked to materials
using \f[CR]MATERIAL\f[R].
Note that if a material is created with the same name as a physical
group in the mesh, they will be linked automatically, so there is no
need to use \f[CR]PHYSCAL_GROUP\f[R] for this.
The \f[CR]MATERIAL\f[R] keyword in \f[CR]PHYSICAL_GROUP\f[R] is used to
link a physical group in a mesh file and a material in the feenox input
file with different names.
.PP
Likewise, for non\-volumetric elements, physical groups can be linked to
boundary using \f[CR]BC\f[R].
As in the preceding case, if a boundary condition is created with the
same name as a physical group in the mesh, they will be linked
automatically, so there is no need to use \f[CR]PHYSCAL_GROUP\f[R] for
this.
The \f[CR]BC\f[R] keyword in \f[CR]PHYSICAL_GROUP\f[R] is used to link a
physical group in a mesh file and a boundary condition in the feenox
input file with different names.
Note that while there can be only one \f[CR]MATERIAL\f[R] associated to
a physical group, there can be many \f[CR]BC\f[R]s associated to a
physical group.
.SS \f[CR]PROBLEM\f[R]
.PP
Ask FeenoX to solve a partial differential equation problem.
.IP
.EX
PROBLEM { laplace | mechanical | modal | neutron_diffusion | neutron_sn | thermal }
 [ 1D | 2D | 3D | DIM <expr> ] [ AXISYMMETRIC { x | y } ] 
 [ MESH <identifier> ] [ PROGRESS ] [ DO_NOT_DETECT_HANGING_NODES | DETECT_HANGING_NODES | HANDLE_HANGING_NODES ]
 [ DETECT_UNRESOLVED_BCS | ALLOW_UNRESOLVED_BCS ]
 [ PREALLOCATE ] [ ALLOW_NEW_NONZEROS ] [ CACHE_J ] [ CACHE_B ] 
 [ TRANSIENT | QUASISTATIC ] [ LINEAR | NON_LINEAR ] 
 [ MODES <expr> ] 
 [ PRECONDITIONER { gamg | mumps | lu | hypre | sor | bjacobi | cholesky | ... } ]
 [ LINEAR_SOLVER { gmres | mumps | bcgs | bicg | richardson | chebyshev | ... } ]
 [ NONLINEAR_SOLVER { newtonls | newtontr | nrichardson | ngmres | qn | ngs | ... } ]
 [ TRANSIENT_SOLVER { bdf | beuler | arkimex | rosw | glee | ... } ]
 [ TIME_ADAPTATION { basic | none | dsp | cfl | glee | ... } ]
 [ EIGEN_SOLVER { krylovschur | lanczos | arnoldi | power | gd | ... } ]
 [ SPECTRAL_TRANSFORMATION { shift | sinvert | cayley | ... } ]
 [ EIGEN_FORMULATION { omega | lambda } ]
 [ DIRICHLET_SCALING { absolute <expr> | relative <expr> } ]
  
.EE
.PP
Currently, FeenoX can solve the following types of PDE\-casted problems:
.IP \[bu] 2
\f[CR]neutron_diffusion\f[R] multi\-group core\-level neutron diffusion
with a FEM formulation
.IP \[bu] 2
\f[CR]neutron_sn\f[R] multi\-group core\-level neutron transport using
.RS 2
.IP \[bu] 2
discrete ordinates \f[I]S\f[R]~\f[I]N\f[R]~ for angular discretization,
and
.IP \[bu] 2
isoparametric finite elements for spatial discretization.
.RE
.RS
.PP
If you are a programmer and want to contribute with another problem
type, please do so!
Check out the programming guide in the FeenoX repository.
.RE
.PP
The number of spatial dimensions of the problem needs to be given either
as \f[CR]1d\f[R], \f[CR]2d\f[R], \f[CR]3d\f[R] or after the keyword
\f[CR]DIM\f[R].
Alternatively, one can define a \f[CR]MESH\f[R] with an explicit
\f[CR]DIMENSIONS\f[R] keyword before \f[CR]PROBLEM\f[R].
Default is 3D.
If the \f[CR]AXISYMMETRIC\f[R] keyword is given, the mesh is expected to
be two\-dimensional in the \f[I]x\f[R]\-\f[I]y\f[R] plane and the
problem is assumed to be axi\-symmetric around the given axis.
If there are more than one \f[CR]MESH\f[R]es defined, the one over which
the problem is to be solved can be defined by giving the explicit mesh
name with \f[CR]MESH\f[R].
By default, the first mesh to be defined in the input file with
\f[CR]READ_MESH\f[R] (which can be defined after the \f[CR]PROBLEM\f[R]
keyword) is the one over which the problem is solved.
If the keyword \f[CR]PROGRESS\f[R] is given, three ASCII lines will show
in the terminal the progress of the ensamble of the stiffness matrix (or
matrices), the solution of the system of equations and the computation
of gradients (stresses, heat fluxes, etc.), if applicable.
If either \f[CR]DETECT_HANGING_NODES\f[R] or
\f[CR]HANDLE_HANGING_NODES\f[R] are given, an intermediate check for
nodes without any associated elements will be performed.
For well\-behaved meshes this check is redundant so by default it is not
done (\f[CR]DO_NOT_DETEC_HANGING_NODES\f[R]).
With \f[CR]DETECT_HANGING_NODES\f[R], FeenoX will report the tag of the
hanging nodes and stop.
With \f[CR]HANDLE_HANGING_NODES\f[R], FeenoX will fix those nodes and
try to solve the problem anyway.
By default, FeenoX checks that all physical groups referred to in the
\f[CR]BC\f[R] keywords exists (\f[CR]DETECT_UNRESOLVED_BCS\f[R]).
If \f[CR]ALLOW_UNRESOLVED_BCS\f[R] is given, FeenoX will ignore
unresolved boundary conditions instead of complaining.
This is handy when using the same input for different meshes which might
have different groups, for example solving the same problem using a full
geometry or a symmetric geometry.
The latter should have at least one symmetry BC whilst the former does
not.
If the special variable \f[CR]end_time\f[R] is zero, FeenoX solves a
static problem\[em]although the variable \f[CR]static_steps\f[R] is
still honored.
If \f[CR]end_time\f[R] is non\-zero, FeenoX solves a transient or
quasi\-static problem.
This can be controlled by \f[CR]TRANSIENT\f[R] or
\f[CR]QUASISTATIC\f[R].
By default FeenoX tries to detect whether the computation should be
linear or non\-linear.
An explicit mode can be set with either \f[CR]LINEAR\f[R] on
\f[CR]NON_LINEAR\f[R].
The number of modes to be computed when solving eigenvalue problems is
given by \f[CR]MODES\f[R].
The default value is problem dependent.
The preconditioner (\f[CR]PC\f[R]), linear (\f[CR]KSP\f[R]), non\-linear
(\f[CR]SNES\f[R]) and time\-stepper (\f[CR]TS\f[R]) solver types be any
of those available in PETSc (first option is the default):
.IP \[bu] 2
List of \f[CR]PRECONDITIONER\f[R]s
https://petsc.org/release/manualpages/PC/PCType/.
.IP \[bu] 2
List of \f[CR]LINEAR_SOLVER\f[R]s
https://petsc.org/release/manualpages/KSP/KSPType/.
.IP \[bu] 2
List of \f[CR]NONLINEAR_SOLVER\f[R]s
https://petsc.org/release/manualpages/SNES/SNESType/.
.IP \[bu] 2
List of \f[CR]TRANSIENT_SOLVER\f[R]s
http://petsc.org/release/docs/manualpages/TS/TSType.html.
.IP \[bu] 2
List of \f[CR]TIME_ADAPTATION\f[R]s
https://petsc.org/release/manualpages/TS/TSType/.
.IP \[bu] 2
List of \f[CR]EIGEN_SOLVER\f[R]s
https://slepc.upv.es/documentation/current/docs/manualpages/EPS/EPSType.html.
.IP \[bu] 2
List of \f[CR]SPECTRAL_TRANSFORMATION\f[R]s
https://slepc.upv.es/documentation/current/docs/manualpages/ST/STType.html.
.PP
If the \f[CR]EIGEN_FORMULATION\f[R] is \f[CR]omega\f[R] then
\f[I]K\f[R]\f[I]ϕ\f[R] = \f[I]ω\f[R]^2^\f[I]M\f[R]\f[I]ϕ\f[R] is solved,
and \f[I]M\f[R]\f[I]ϕ\f[R] = \f[I]λ\f[R]\f[I]K\f[R]\f[I]ϕ\f[R] if it is
\f[CR]lambda\f[R].
Default is \f[CR]lambda\f[R], although some particular PDEs might change
it (for example free\-free modal switches to \f[CR]omega\f[R]).
The \f[CR]EIGEN_DIRICHLET_ZERO\f[R] keyword controls which of the
matrices has a zero and which one has a non\-zero in the diagonal when
setting Dirichlet boundary conditions.
Default is \f[CR]M\f[R], i.e.\ matrix\ \f[I]K\f[R] has a non\-zero and
matrix\ \f[I]M\f[R] has a zero.
This setting, along with \f[CR]EIGEN_FORMULATION\f[R] determines which
spectral transforms can a cannot be used: you cannot invert the matrix
with the zero in the diagonal.
The \f[CR]DIRICHLET_SCALING\f[R] keyword controls the way Dirichlet
boundary conditions are scaled when computing the residual.
Roughly, it defines how to compute the parameter\ \f[I]α\f[R].
If \f[CR]absolute\f[R], then \f[I]α\f[R] is equal to the given
expression.
If \f[CR]relative\f[R], then \f[I]α\f[R] is equal to the given fraction
of the average diagonal entries in the stiffness matrix.
Default is\ \f[I]α\f[R] = 1.
.SS \f[CR]READ_MESH\f[R]
.PP
Read an unstructured mesh and (optionally) functions of space\-time from
a file.
.IP
.EX
READ_MESH { <file_path> | <file_id> } [ DIM <num_expr> ]
 [ SCALE <expr> ] [ OFFSET <expr_x> <expr_y> <expr_z> ]
 [ INTEGRATION { full | reduced } ]
 [ MAIN ] [ UPDATE_EACH_STEP ]
 [ READ_FIELD <name_in_mesh> AS <function_name> ] [ READ_FIELD ... ] 
 [ READ_FUNCTION <function_name> ] [READ_FUNCTION ...] 
  
.EE
.PP
Either a file identifier (defined previously with a \f[CR]FILE\f[R]
keyword) or a file path should be given.
The format is read from the extension, which should be either
.IP \[bu] 2
\f[CR].msh\f[R], \f[CR].msh2\f[R] or \f[CR].msh4\f[R] Gmsh ASCII format,
versions 2.2, 4.0 or 4.1
.IP \[bu] 2
\f[CR].vtk\f[R] ASCII legacy VTK
.IP \[bu] 2
\f[CR].frd\f[R] CalculiX\[cq]s FRD ASCII output
.PP
Note than only MSH is suitable for defining PDE domains, as it is the
only one that provides physical groups (a.k.a labels) which are needed
in order to define materials and boundary conditions.
The other formats are primarily supported to read function data
contained in the file and eventually, to operate over these functions
(i.e.\ take differences with other functions contained in other files to
compare results).
The file path or file id can be used to refer to a particular mesh when
reading more than one, for instance in a \f[CR]WRITE_MESH\f[R] or
\f[CR]INTEGRATE\f[R] keyword.
If a file path is given such as \f[CR]cool_mesh.msh\f[R], it can be
later referred to as either \f[CR]cool_mesh.msh\f[R] or just
\f[CR]cool_mesh\f[R].
.PD 0
.P
.PD
The spatial dimensions can be given with \f[CR]DIM\f[R].
If material properties are uniform and given with variables, the number
of dimensions are not needed and will be read from the file at runtime.
But if either properties are given by spatial functions or if functions
are to be read from the mesh with \f[CR]READ_DATA\f[R] or
\f[CR]READ_FUNCTION\f[R], then the number of dimensions ought to be
given explicitly because FeenoX needs to know how many arguments these
functions take.
If either \f[CR]OFFSET\f[R] and/or \f[CR]SCALE\f[R] are given, the node
locations are first shifted and then scaled by the provided values.
When defining several meshes and solving a PDE problem, the mesh used as
the PDE domain is the one marked with \f[CR]MAIN\f[R].
If none of the meshes is explicitly marked as main, the first one is
used.
If \f[CR]UPDATE_EACH_STEP\f[R] is given, then the mesh data is re\-read
from the file at each time step.
Default is to read the mesh once, except if the file path changes with
time.
For each \f[CR]READ_FIELD\f[R] keyword, a point\-wise defined scalar
function of space named \f[CR]<function_name>\f[R] is defined and filled
with the scalar data named \f[CR]<name_in_mesh>\f[R] contained in the
mesh file.
The \f[CR]READ_FUNCTION\f[R] keyword is a shortcut when the scalar name
and the to\-be\-defined function are the same.
If no mesh is marked as \f[CR]MAIN\f[R], the first one is the main one.
.SS \f[CR]SOLVE_PROBLEM\f[R]
.PP
Explicitly solve the PDE problem.
.IP
.EX
SOLVE_PROBLEM  
.EE
.PP
Whenever the instruction \f[CR]SOLVE_PROBLEM\f[R] is executed, FeenoX
solves the PDE problem.
For static problems, that means solving the equations and filling in the
result functions.
For transient or quasisstatic problems, that means advancing one time
step.
.SS \f[CR]WRITE_MESH\f[R]
.PP
Write a mesh and/or generic functions of space\-time to a
post\-processing file.
.IP
.EX
WRITE_MESH <file> [ MESH <mesh_identifier> ] [ FILE_FORMAT { gmsh | vtk } ] [ NO_MESH ] [ NO_PHYSICAL_NAMES ]
  [ NODE | CELL ] [ <printf_specification> ]
 [ <scalar_field_1> ] [ <scalar_field_2> ] [...] 
 [ VECTOR [ NAME <name> ] <field_x> <field_y> <field_z> ] [...] 
 [ SYMMETRIC_TENSOR [ NAME <name> ] <field_xx> <field_yy> <field_zz> <field_xy> <field_yz> <field_zx> ] [...] 
  
.EE
.PP
The format is automatically detected from the extension, which should be
either \f[CR]msh\f[R] (version 2.2 ASCII) or \f[CR]vtk\f[R] (legacy
ASCII).
Otherwise, the keyword \f[CR]FILE_FORMAT\f[R] has to be given to set the
format explicitly.
If there are several meshes defined by \f[CR]READ_MESH\f[R], the mesh
used to write the data has be given explicitly with \f[CR]MESH\f[R].
If the \f[CR]NO_MESH\f[R] keyword is given, only the results are written
into the output file without any mesh data.
Depending on the output format, this can be used to avoid repeating data
and/or creating partial output files which can the be latter assembled
by post\-processing scripts.
When targeting the \f[CR].msh\f[R] output format, if
\f[CR]NO_PHYSICAL_NAMES\f[R] is given then the section that sets the
actual names of the physical entities is not written.
.PD 0
.P
.PD
This might be needed in some cases to avoid name clashes when dealing
with multiple \f[CR].msh\f[R] files.
The output is node\-based by default.
This can be controlled with both the \f[CR]NODE\f[R] and \f[CR]CELL\f[R]
keywords.
All fields that come after a \f[CR]NODE\f[R] (\f[CR]CELL\f[R]) keyword
will be written at the node (cells).
These keywords can be used several times and mixed with fields.
For example
\f[CR]CELL k(x,y,z) NODE T sqrt(x\[ha]2+y\[ha]2) CELL 1+z\f[R] will
write the conductivity and the expression 1 + \f[I]z\f[R] as cell\-based
and the temperature \f[I]T\f[R](\f[I]x\f[R], \f[I]y\f[R], \f[I]z\f[R])
and the expression $\[rs]sqrt{x\[ha]2+y\[ha]2}$ as a node\-based fields.
If a printf\-like format specifier starting with \f[CR]%\f[R] is given,
that format is used for the fields that follow.
Make sure the format reads floating\-point data, i.e.\ do not use
\f[CR]%d\f[R].
Default is \f[CR]%g\f[R].
The data to be written has to be given as a list of fields,
i.e.\ distributions (such as \f[CR]k\f[R] or \f[CR]E\f[R]), functions of
space (such as \f[CR]T\f[R]) and/or expressions (such as
\f[CR]T(x,y,z)*sqrt(x\[ha]2+y\[ha]2+z\[ha]2)\f[R]).
Each field is written as a scalar, unless either the keywords
\f[CR]VECTOR\f[R] or \f[CR]SYMMETRIC_TENSOR\f[R] are given.
In the first case, the next three fields following the \f[CR]VECTOR\f[R]
keyword are taken as the vector elements.
In the latter, the next six fields following the
\f[CR]SYMMETRIC_TENSOR\f[R] keyword are taken as the tensor elements.
.SS \f[CR]WRITE_RESULTS\f[R]
.PP
Write the problem mesh and problem results to a file for
post\-processing.
.IP
.EX
WRITE_RESULTS [ FORMAT { gmsh | vtu | vtk } ] [ FILE <file> ]
 [ NO_PHYSICAL_NAMES ] [ <printf_specification> ]
  
.EE
.PP
Default format is \f[CR]gmsh\f[R].
If no \f[CR]FILE\f[R] is provided, the output file is the same as the
input file replacing the \f[CR].fee\f[R] extension with the format
extension, i.e.\ \f[CR]$0.msh\f[R].
If there are further optional command line arguments, they are added
prepending a dash, i.e.\ \f[CR]$0\-[$1\-[$2...]].msh\f[R] Otherwise the
given \f[CR]FILE\f[R] is used.
If no explicit \f[CR]FORMAT\f[R] is given, the format is read from the
\f[CR]FILE\f[R] extension.
When targeting the \f[CR].msh\f[R] output format, if
\f[CR]NO_PHYSICAL_NAMES\f[R] is given then the section that sets the
actual names of the physical entities is not written.
.PD 0
.P
.PD
This might be needed in some cases to avoid name clashes when dealing
with multiple \f[CR].msh\f[R] files.
If a printf\-like format specifier starting with \f[CR]%\f[R] is given,
that format is used for the fields that follow.
Make sure the format reads floating\-point data, i.e.\ do not use
\f[CR]%d\f[R].
Default is \f[CR]%g\f[R].
.SH SPECIAL VARIABLES
.SS \f[CR]done\f[R]
.PP
Flag that indicates whether the overall calculation is over.
.PP
This variable is set to true by FeenoX when the computation finished so
it can be checked in an \f[CR]IF\f[R] block to do something only in the
last step.
But this variable can also be set to true from the input file,
indicating that the current step should also be the last one.
For example, one can set \f[CR]end_time = infinite\f[R] and then finish
the computation at \f[I]t\f[R] = 10 by setting \f[CR]done = t > 10\f[R].
This \f[CR]done\f[R] variable can also come from (and sent to) other
sources, like a shared memory object for coupled calculations.
.SS \f[CR]done_static\f[R]
.PP
Flag that indicates whether the static calculation is over or not.
.PP
It is set to true (i.e.\  ≠ 0) by feenox if \f[CR]step_static\f[R] ≥
\f[CR]static_steps\f[R].
If the user sets it to true, the current step is marked as the last
static step and the static calculation ends after finishing the step.
It can be used in \f[CR]IF\f[R] blocks to check if the static step is
finished or not.
.SS \f[CR]done_transient\f[R]
.PP
Flag that indicates whether the transient calculation is over or not.
.PP
It is set to true (i.e.\  ≠ 0) by feenox if \f[CR]t\f[R] ≥
\f[CR]end_time\f[R].
If the user sets it to true, the current step is marked as the last
transient step and the transient calculation ends after finishing the
step.
It can be used in \f[CR]IF\f[R] blocks to check if the transient steps
are finished or not.
.SS \f[CR]dt\f[R]
.PP
Actual value of the time step for transient calculations.
.PP
When solving DAE systems, this variable is set by feenox.
It can be written by the user for example by importing it from another
transient code by means of shared\-memory objects.
Care should be taken when solving DAE systems and overwriting
\f[CR]t\f[R].
Default value is DEFAULT_DT, which is a power of two and roundoff errors
are thus reduced.
.SS \f[CR]end_time\f[R]
.PP
Final time of the transient calculation, to be set by the user.
.PP
The default value is zero, meaning no transient calculation.
.SS \f[CR]i\f[R]
.PP
Dummy index, used mainly in vector and matrix row subindex expressions.
.SS \f[CR]infinite\f[R]
.PP
A very big positive number.
.PP
It can be used as \f[CR]end_time = infinite\f[R] or to define improper
integrals with infinite limits.
Default is 2^50^ ≈ 1 × 10^15^.
.SS \f[CR]in_static\f[R]
.PP
Flag that indicates if FeenoX is solving the iterative static
calculation.
.PP
This is a read\-only variable that is non zero if the static
calculation.
.SS \f[CR]in_static_first\f[R]
.PP
Flag that indicates if feenox is in the first step of the iterative
static calculation.
.SS \f[CR]in_static_last\f[R]
.PP
Flag that indicates if feenox is in the last step of the iterative
static calculation.
.SS \f[CR]in_time_path\f[R]
.PP
Flag that indicates if feenox is in a time belonging to a
\f[CR]TIME_PATH\f[R] keyword.
.SS \f[CR]in_transient\f[R]
.PP
Flag that indicates if feenox is solving transient calculation.
.SS \f[CR]in_transient_first\f[R]
.PP
Flag that indicates if feenox is in the first step of the transient
calculation.
.SS \f[CR]in_transient_last\f[R]
.PP
Flag that indicates if feenox is in the last step of the transient
calculation.
.SS \f[CR]j\f[R]
.PP
Dummy index, used mainly in matrix column subindex expressions.
.SS \f[CR]max_dt\f[R]
.PP
Maximum bound for the time step that feenox should take when solving DAE
systems.
.SS \f[CR]min_dt\f[R]
.PP
Minimum bound for the time step that feenox should take when solving DAE
systems.
.SS \f[CR]mpi_rank\f[R]
.PP
The current rank in an MPI execution.
Mind the \f[CR]PRINTF_ALL\f[R] instruction.
.SS \f[CR]mpi_size\f[R]
.PP
The number of total ranks in an MPI execution.
.SS \f[CR]on_gsl_error\f[R]
.PP
This should be set to a mask that indicates how to proceed if an error
ir raised in any routine of the GNU Scientific Library.
.SS \f[CR]on_ida_error\f[R]
.PP
This should be set to a mask that indicates how to proceed if an error
ir raised in any routine of the SUNDIALS Library.
.SS \f[CR]on_nan\f[R]
.PP
This should be set to a mask that indicates how to proceed if
Not\-A\-Number signal (such as a division by zero) is generated when
evaluating any expression within feenox.
.SS \f[CR]pi\f[R]
.PP
A double\-precision floating point representation of the number
\f[I]π\f[R]
.PP
It is equal to the \f[CR]M_PI\f[R] constant in \f[CR]math.h\f[R] .
.SS \f[CR]pid\f[R]
.PP
The Unix process id of the FeenoX instance.
.SS \f[CR]static_steps\f[R]
.PP
Number of steps that ought to be taken during the static calculation, to
be set by the user.
.PP
The default value is one, meaning only one static step.
.SS \f[CR]step_static\f[R]
.PP
Indicates the current step number of the iterative static calculation.
.PP
This is a read\-only variable that contains the current step of the
static calculation.
.SS \f[CR]step_transient\f[R]
.PP
Indicates the current step number of the transient static calculation.
.PP
This is a read\-only variable that contains the current step of the
transient calculation.
.SS \f[CR]t\f[R]
.PP
Actual value of the time for transient calculations.
.PP
This variable is set by FeenoX, but can be written by the user for
example by importing it from another transient code by means of
shared\-memory objects.
Care should be taken when solving DAE systems and overwriting
\f[CR]t\f[R].
.SS \f[CR]zero\f[R]
.PP
A very small positive number.
.PP
It is taken to avoid roundoff errors when comparing floating point
numbers such as replacing \f[I]a\f[R] ≤ \f[I]a\f[R]~max~ with
\f[I]a\f[R] < \f[I]a\f[R]~max~+ \f[CR]zero\f[R].
Default is (1/2)^−50^ ≈ 9 × 10^−16^ .
.SH MATERIAL PROPERTIES
TBD.
.SH BOUNDARY CONDITIONS
TBD.
.SH RESULTING DISTRIBUTIONS
TBD.
.SH BUILT\-IN FUNCTIONS
.SS \f[CR]abs\f[R]
.PP
Returns the absolute value of the argument\ \f[I]x\f[R].
.IP
.EX
abs(x)  
.EE
.PP
\ 
.SS \f[CR]acos\f[R]
.PP
Computes the arc in radians whose cosine is equal to the
argument\ \f[I]x\f[R].
A NaN error is raised if\ |\f[I]x\f[R]| > 1.
.IP
.EX
acos(x)  
.EE
.PP
\ 
.SS \f[CR]asin\f[R]
.PP
Computes the arc in radians whose sine is equal to the
argument\ \f[I]x\f[R].
A NaN error is raised if\ |\f[I]x\f[R]| > 1.
.IP
.EX
asin(x)  
.EE
.PP
\ 
.SS \f[CR]atan\f[R]
.PP
Computes, in radians, the arc tangent of the argument\ \f[I]x\f[R].
.IP
.EX
atan(x)  
.EE
.PP
\ 
.SS \f[CR]atan2\f[R]
.PP
Computes, in radians, the arc tangent of
quotient\ \f[I]y\f[R]/\f[I]x\f[R], using the signs of the two arguments
to determine the quadrant of the result, which is in the range
[−\f[I]π\f[R], \f[I]π\f[R]].
.IP
.EX
atan2(y,x)  
.EE
.SS \f[CR]ceil\f[R]
.PP
Returns the smallest integral value not less than the
argument\ \f[I]x\f[R].
.IP
.EX
ceil(x)  
.EE
.PP
\ 
.SS \f[CR]clock\f[R]
.PP
Returns the value of a certain clock in seconds measured from a certain
(but specific) milestone.
The kind of clock and the initial milestone depend on the optional
integer argument\ \f[I]f\f[R].
It defaults to one, meaning \f[CR]CLOCK_MONOTONIC\f[R].
The list and the meanings of the other available values for\ \f[I]f\f[R]
can be checked in the \f[CR]clock_gettime (2)\f[R] system call manual
page.
.IP
.EX
clock([f])  
.EE
.SS \f[CR]cos\f[R]
.PP
Computes the cosine of the argument\ \f[I]x\f[R], where\ \f[I]x\f[R] is
in radians.
A cosine wave can be generated by passing as the argument\ \f[I]x\f[R] a
linear function of time such as\ \f[I]ω\f[R]\f[I]t\f[R] + \f[I]ϕ\f[R],
where \f[I]ω\f[R] controls the frequency of the wave and \f[I]ϕ\f[R]
controls its phase.
.IP
.EX
cos(x)  
.EE
.PP
\ 
.SS \f[CR]cosh\f[R]
.PP
Computes the hyperbolic cosine of the argument\ \f[I]x\f[R],
where\ \f[I]x\f[R] is in radians.
.IP
.EX
cosh(x)  
.EE
.PP
\ 
.SS \f[CR]cpu_time\f[R]
.PP
Returns the CPU time used by the local FeenoX rank, in seconds.
If the optional argument \f[CR]f\f[R] is not provided or it is zero
(default), the sum of times for both user\-space and kernel\-space usage
is returned.
For \f[CR]f=1\f[R] only user time is returned.
For \f[CR]f=2\f[R] only system time is returned.
.IP
.EX
cpu_time([f])  
.EE
.SS \f[CR]d_dt\f[R]
.PP
Computes the time derivative of the expression given in the
argument\ \f[I]x\f[R] during a transient problem using the difference
between the value of the signal in the previous time step and the actual
value divided by the time step\ \f[I]δ\f[R]\f[I]t\f[R] stored in
\f[CR]dt\f[R].
The argument\ \f[I]x\f[R] does not need to be a variable, it can be an
expression involving one or more variables that change in time.
For \f[I]t\f[R] = 0, the return value is zero.
Unlike the functional \f[CR]derivative\f[R], the full dependence of
these variables with time does not need to be known beforehand,
i.e.\ the expression \f[CR]x\f[R] might involve variables read from a
shared\-memory object at each time step.
.IP
.EX
d_dt(x)  
.EE
.SS \f[CR]deadband\f[R]
.PP
Filters the first argument\ \f[I]x\f[R] with a deadband centered at zero
with an amplitude given by the second argument \f[I]a\f[R].
.IP
.EX
deadband(x, a)  
.EE
.SS \f[CR]equal\f[R]
.PP
Checks if the two first expressions \f[I]a\f[R] and \f[I]b\f[R] are
equal, up to the tolerance given by the third optional argument
\f[I]ϵ\f[R].
If either |\f[I]a\f[R]| > 1 or |\f[I]b\f[R]| > 1, the arguments are
compared using GSL\[cq]s \f[CR]gsl_fcmp\f[R], otherwise the absolute
value of their difference is compared against \f[I]ϵ\f[R].
This function returns zero if the arguments are not equal and one
otherwise.
Default value for \f[I]ϵ\f[R] = 10^−9^.
.IP
.EX
equal(a, b, [eps])  
.EE
.SS \f[CR]exp\f[R]
.PP
Computes the exponential function the argument\ \f[I]x\f[R], i.e.\ the
base of the natural logarithm\ \f[I]e\f[R] raised to
the\ \f[I]x\f[R]\-th power.
.IP
.EX
exp(x)  
.EE
.PP
\ 
.SS \f[CR]expint1\f[R]
.PP
Computes the first exponential integral function of the
argument\ \f[I]x\f[R].
If\ \f[I]x\f[R] is zero, a NaN error is issued.
.IP
.EX
expint1(x)  
.EE
.PP
\ 
.SS \f[CR]expint2\f[R]
.PP
Computes the second exponential integral function of the
argument\ \f[I]x\f[R].
.IP
.EX
expint2(x)  
.EE
.PP
\ 
.SS \f[CR]expint3\f[R]
.PP
Computes the third exponential integral function of the
argument\ \f[I]x\f[R].
.IP
.EX
expint3(x)  
.EE
.PP
\ 
.SS \f[CR]expintn\f[R]
.PP
Computes the \f[I]n\f[R]\-th exponential integral function of the
argument\ \f[I]x\f[R].
If\ \f[I]n\f[R] is zero or one and\ \f[I]x\f[R] is zero, a NaN error is
issued.
.IP
.EX
expintn(n,x)  
.EE
.SS \f[CR]floor\f[R]
.PP
Returns the largest integral value not greater than the
argument\ \f[I]x\f[R].
.IP
.EX
floor(x)  
.EE
.PP
\ 
.SS \f[CR]gammaf\f[R]
.PP
Computes the Gamma function\ \f[I]Γ\f[R](\f[I]x\f[R]).
.IP
.EX
gammaf(x)  
.EE
.PP
\ 
.SS \f[CR]heaviside\f[R]
.PP
Computes the zero\-centered Heaviside step function of the
argument\ \f[I]x\f[R].
If the optional second argument \f[I]δ\f[R] is provided, the
discontinuous step at\ \f[I]x\f[R] = 0 is replaced by a ramp starting
at\ \f[I]x\f[R] = 0 and finishing at\ \f[I]x\f[R] = \f[I]δ\f[R].
.IP
.EX
heaviside(x, [delta])  
.EE
.PP
\ 
.SS \f[CR]if\f[R]
.PP
Performs a conditional testing of the first argument \f[I]a\f[R], and
returns either the second optional argument \f[I]b\f[R] if \f[I]a\f[R]
is different from zero or the third optional argument \f[I]c\f[R] if
\f[I]a\f[R] evaluates to zero.
The comparison of the condition \f[I]a\f[R] with zero is performed
within the precision given by the optional fourth argument \f[I]ϵ\f[R].
If the second argument \f[I]c\f[R] is not given and \f[I]a\f[R] is not
zero, the function returns one.
If the third argument \f[I]c\f[R] is not given and \f[I]a\f[R] is zero,
the function returns zero.
The default precision is \f[I]ϵ\f[R] = 10^−9^.
Even though \f[CR]if\f[R] is a logical operation, all the arguments and
the returned value are double\-precision floating point numbers.
.IP
.EX
if(a, [b], [c], [eps])  
.EE
.SS \f[CR]integral_dt\f[R]
.PP
Computes the time integral of the expression given in the
argument\ \f[I]x\f[R] during a transient problem with the trapezoidal
rule using the value of the signal in the previous time step and the
current value.
At \f[I]t\f[R] = 0 the integral is initialized to zero.
Unlike the functional \f[CR]integral\f[R], the full dependence of these
variables with time does not need to be known beforehand, i.e.\ the
expression \f[CR]x\f[R] might involve variables read from a
shared\-memory object at each time step.
.IP
.EX
integral_dt(x)  
.EE
.SS \f[CR]integral_euler_dt\f[R]
.PP
Idem as \f[CR]integral_dt\f[R] but uses the backward Euler rule to
update the instantaenous integral value.
This function is provided in case this particular way of approximating
time integrals is needed, for instance to compare FeenoX solutions with
other computer codes.
In general, it is recommended to use \f[CR]integral_dt\f[R].
.IP
.EX
integral_euler_dt(x)  
.EE
.SS \f[CR]is_even\f[R]
.PP
Returns one if the argument\ \f[I]x\f[R] rounded to the nearest integer
is even.
.IP
.EX
is_even(x)  
.EE
.SS \f[CR]is_in_interval\f[R]
.PP
Returns true if the argument\ \f[I]x\f[R] is in the
interval\ [\f[I]a\f[R], \f[I]b\f[R]), i.e.\ including\ \f[I]a\f[R] but
excluding\ \f[I]b\f[R].
.IP
.EX
is_in_interval(x, a, b)  
.EE
.SS \f[CR]is_odd\f[R]
.PP
Returns one if the argument\ \f[I]x\f[R] rounded to the nearest integer
is odd.
.IP
.EX
is_odd(x)  
.EE
.SS \f[CR]j0\f[R]
.PP
Computes the regular cylindrical Bessel function of zeroth order
evaluated at the argument\ \f[I]x\f[R].
.IP
.EX
j0(x)  
.EE
.PP
\ 
.SS \f[CR]lag\f[R]
.PP
Filters the first argument\ \f[I]x\f[R](\f[I]t\f[R]) with a first\-order
lag of characteristic time \f[I]τ\f[R], i.e.\ this function applies the
transfer function\ $G(s) = \[rs]frac{1}{1 + s\[rs]tau}$ to the
time\-dependent signal\ \f[I]x\f[R](\f[I]t\f[R]) to obtain a filtered
signal\ \f[I]y\f[R](\f[I]t\f[R]), by assuming that it is constant during
the time interval\ [\f[I]t\f[R] − \f[I]Δ\f[R]\f[I]t\f[R], \f[I]t\f[R]]
and using the analytical solution of the differential equation for that
case at\ \f[I]t\f[R] = \f[I]Δ\f[R]\f[I]t\f[R] with the initial
condition\ \f[I]y\f[R](0) = \f[I]y\f[R](\f[I]t\f[R] − \f[I]Δ\f[R]\f[I]t\f[R]).
.IP
.EX
lag(x, tau)  
.EE
.SS \f[CR]lag_bilinear\f[R]
.PP
Filters the first argument\ \f[I]x\f[R](\f[I]t\f[R]) with a first\-order
lag of characteristic time \f[I]τ\f[R] to the time\-dependent
signal\ \f[I]x\f[R](\f[I]t\f[R]) by using the bilinear transformation
formula.
.IP
.EX
lag_bilinear(x, tau)  
.EE
.SS \f[CR]lag_euler\f[R]
.PP
Filters the first argument\ \f[I]x\f[R](\f[I]t\f[R]) with a first\-order
lag of characteristic time \f[I]τ\f[R] to the time\-dependent
signal\ \f[I]x\f[R](\f[I]t\f[R]) by using the Euler forward rule.
.IP
.EX
lag_euler(x, tau)  
.EE
.SS \f[CR]last\f[R]
.PP
Returns the value the variable\ \f[I]x\f[R] had in the previous time
step.
This function is equivalent to the\ \f[I]Z\f[R]\-transform operator
\[lq]delay\[rq] denoted by\ \f[I]z\f[R]^−1^[\f[I]x\f[R]].
For\ \f[I]t\f[R] = 0 the function returns the actual value
of\ \f[I]x\f[R].
The optional flag\ \f[I]p\f[R] should be set to one if the reference to
\f[CR]last\f[R] is done in an assignment over a variable that already
appears inside expression\ \f[I]x\f[R] such as \f[CR]x = last(x)\f[R].
See example number 2.
.IP
.EX
last(x,[p])  
.EE
.SS \f[CR]limit\f[R]
.PP
Limits the first argument\ \f[I]x\f[R] to the interval
[\f[I]a\f[R], \f[I]b\f[R]].
The second argument \f[I]a\f[R] should be less than the third argument
\f[I]b\f[R].
.IP
.EX
limit(x, a, b)  
.EE
.SS \f[CR]limit_dt\f[R]
.PP
Limits the value of the first argument\ \f[I]x\f[R](\f[I]t\f[R]) so to
that its time derivative is bounded to the interval
[\f[I]a\f[R], \f[I]b\f[R]].
The second argument \f[I]a\f[R] should be less than the third argument
\f[I]b\f[R].
.IP
.EX
limit_dt(x, a, b)  
.EE
.SS \f[CR]log\f[R]
.PP
Computes the natural logarithm of the argument\ \f[I]x\f[R].
If\ \f[I]x\f[R] is zero or negative, a NaN error is issued.
.IP
.EX
log(x)  
.EE
.PP
\ 
.SS \f[CR]mark_max\f[R]
.PP
Returns the integer index \f[I]i\f[R] of the maximum of the
arguments\ \f[I]x\f[R]~\f[I]i\f[R]~ provided.
Currently only maximum of ten arguments can be provided.
.IP
.EX
mark_max(x1, x2, [...], [x10])  
.EE
.SS \f[CR]mark_min\f[R]
.PP
Returns the integer index \f[I]i\f[R] of the minimum of the
arguments\ \f[I]x\f[R]~\f[I]i\f[R]~ provided.
Currently only maximum of ten arguments can be provided.
.IP
.EX
mark_max(x1, x2, [...], [x10])  
.EE
.SS \f[CR]max\f[R]
.PP
Returns the maximum of the arguments\ \f[I]x\f[R]~\f[I]i\f[R]~ provided.
Currently only maximum of ten arguments can be given.
.IP
.EX
max(x1, x2, [...], [x10])  
.EE
.SS \f[CR]memory\f[R]
.PP
Returns the maximum memory (resident set size) used by FeenoX, in
Gigabytes.
.IP
.EX
memory()  
.EE
.SS \f[CR]min\f[R]
.PP
Returns the minimum of the arguments\ \f[I]x\f[R]~\f[I]i\f[R]~ provided.
Currently only maximum of ten arguments can be given.
.IP
.EX
min(x1, x2, [...], [x10])  
.EE
.SS \f[CR]mod\f[R]
.PP
Returns the remainder of the division between the first
argument\ \f[I]a\f[R] and the second one\ \f[I]b\f[R].
Both arguments may be non\-integral.
.IP
.EX
mod(a, b)  
.EE
.SS \f[CR]mpi_memory_local\f[R]
.PP
Returns the memory usage as reported by PETSc in the give rank, in
Gigabytes.
If no rank is given, each rank returns a local value which should be
printed with \f[CR]PRINTF_ALL\f[R].
Returns the memory global usage as reported by PETSc summing over all
ranks, in Gigabytes.
.IP
.EX
mpi_memory_local([rank]) mpi_memory_global()  
.EE
.SS \f[CR]not\f[R]
.PP
Returns one if the first argument\ \f[I]x\f[R] is zero and zero
otherwise.
The second optional argument \f[I]ϵ\f[R] gives the precision of the
\[lq]zero\[rq] evaluation.
If not given, default is \f[I]ϵ\f[R] = 10^−9^.
.IP
.EX
not(x, [eps])  
.EE
.SS \f[CR]random\f[R]
.PP
Returns a random real number uniformly distributed between the first
real argument\ \f[I]x\f[R]~1~ and the second one\ \f[I]x\f[R]~2~.
If the third integer argument \f[I]s\f[R] is given, it is used as the
seed and thus repetitive sequences can be obtained.
If no seed is provided, the current time (in seconds) plus the internal
address of the expression is used.
Therefore, two successive calls to the function without seed (hopefully)
do not give the same result.
This function uses a second\-order multiple recursive generator
described by Knuth in Seminumerical Algorithms, 3rd Ed., Section 3.6.
.IP
.EX
random(x1, x2, [s])  
.EE
.SS \f[CR]random_gauss\f[R]
.PP
Returns a random real number with a Gaussian distribution with a mean
equal to the first argument\ \f[I]x\f[R]~1~ and a standard deviation
equatl to the second one\ \f[I]x\f[R]~2~.
If the third integer argument \f[I]s\f[R] is given, it is used as the
seed and thus repetitive sequences can be obtained.
If no seed is provided, the current time (in seconds) plus the internal
address of the expression is used.
Therefore, two successive calls to the function without seed (hopefully)
do not give the same result.
This function uses a second\-order multiple recursive generator
described by Knuth in Seminumerical Algorithms, 3rd Ed., Section 3.6.
.IP
.EX
random_gauss(x1, x2, [s])  
.EE
.SS \f[CR]round\f[R]
.PP
Rounds the argument\ \f[I]x\f[R] to the nearest integer.
Halfway cases are rounded away from zero.
.IP
.EX
round(x)  
.EE
.PP
\ 
.SS \f[CR]sawtooth_wave\f[R]
.PP
Computes a sawtooth wave between zero and one with a period equal to
one.
As with the sine wave, a sawtooh wave can be generated by passing as the
argument\ \f[I]x\f[R] a linear function of time such
as\ \f[I]ω\f[R]\f[I]t\f[R] + \f[I]ϕ\f[R], where\ \f[I]ω\f[R] controls
the frequency of the wave and \f[I]ϕ\f[R] controls its phase.
.IP
.EX
sawtooth_wave(x)  
.EE
.PP
\ 
.SS \f[CR]sech\f[R]
.PP
Computes the hyperbolic secant of the argument\ \f[I]x\f[R],
where\ \f[I]x\f[R] is in radians.
.IP
.EX
sech(x)  
.EE
.PP
\ 
.SS \f[CR]sgn\f[R]
.PP
Returns minus one, zero or plus one depending on the sign of the first
argument\ \f[I]x\f[R].
The second optional argument \f[I]ϵ\f[R] gives the precision of the
\[lq]zero\[rq] evaluation.
If not given, default is \f[I]ϵ\f[R] = 10^−9^.
.IP
.EX
sgn(x, [eps])  
.EE
.PP
\ 
.SS \f[CR]sin\f[R]
.PP
Computes the sine of the argument\ \f[I]x\f[R], where\ \f[I]x\f[R] is in
radians.
A sine wave can be generated by passing as the argument\ \f[I]x\f[R] a
linear function of time such as\ \f[I]ω\f[R]\f[I]t\f[R] + \f[I]ϕ\f[R],
where\ \f[I]ω\f[R] controls the frequency of the wave and\ \f[I]ϕ\f[R]
controls its phase.
.IP
.EX
sin(x)  
.EE
.PP
\ 
.SS \f[CR]sinh\f[R]
.PP
Computes the hyperbolic sine of the argument\ \f[I]x\f[R],
where\ \f[I]x\f[R] is in radians.
.IP
.EX
sinh(x)  
.EE
.PP
\ 
.SS \f[CR]sqrt\f[R]
.PP
Computes the positive square root of the argument\ \f[I]x\f[R].
If\ \f[I]x\f[R] is negative, a NaN error is issued.
.IP
.EX
sqrt(x)  
.EE
.PP
\ 
.SS \f[CR]square_wave\f[R]
.PP
Computes a square function between zero and one with a period equal to
one.
The output is one for 0 < \f[I]x\f[R] < 1/2 and zero for
1/2 ≤ \f[I]x\f[R] < 1.
As with the sine wave, a square wave can be generated by passing as the
argument\ \f[I]x\f[R] a linear function of time such
as\ \f[I]ω\f[R]\f[I]t\f[R] + \f[I]ϕ\f[R], where\ \f[I]ω\f[R] controls
the frequency of the wave and\ \f[I]ϕ\f[R] controls its phase.
.IP
.EX
square_wave(x)  
.EE
.PP
\ 
.SS \f[CR]tan\f[R]
.PP
Computes the tangent of the argument\ \f[I]x\f[R], where\ \f[I]x\f[R] is
in radians.
.IP
.EX
tan(x)  
.EE
.PP
\ 
.SS \f[CR]tanh\f[R]
.PP
Computes the hyperbolic tangent of the argument\ \f[I]x\f[R],
where\ \f[I]x\f[R] is in radians.
.IP
.EX
tanh(x)  
.EE
.PP
\ 
.SS \f[CR]threshold_max\f[R]
.PP
Returns one if the first argument\ \f[I]x\f[R] is greater than the
threshold given by the second argument \f[I]a\f[R], and  zero otherwise.
If the optional third argument \f[I]b\f[R] is provided, an hysteresis of
width \f[I]b\f[R] is needed in order to reset the function value.
Default is no hysteresis, i.e.\ \f[I]b\f[R] = 0.
.IP
.EX
threshold_max(x, a, [b])  
.EE
.SS \f[CR]threshold_min\f[R]
.PP
Returns one if the first argument\ \f[I]x\f[R] is less than the
threshold given by the second argument \f[I]a\f[R], and  zero otherwise.
If the optional third argument \f[I]b\f[R] is provided, an hysteresis of
width \f[I]b\f[R] is needed in order to reset the function value.
Default is no hysteresis, i.e.\ \f[I]b\f[R] = 0.
.IP
.EX
threshold_min(x, a, [b])  
.EE
.SS \f[CR]triangular_wave\f[R]
.PP
Computes a triangular wave between zero and one with a period equal to
one.
As with the sine wave, a triangular wave can be generated by passing as
the argument\ \f[I]x\f[R] a linear function of time such
as\ \f[I]ω\f[R]\f[I]t\f[R] + \f[I]ϕ\f[R], where\ \f[I]ω\f[R] controls
the frequency of the wave and\ \f[I]ϕ\f[R] controls its phase.
.IP
.EX
triangular_wave(x)  
.EE
.PP
\ 
.SS \f[CR]wall_time\f[R]
.PP
Returns the time elapsed since the invocation of FeenoX, in seconds.
.IP
.EX
wall_time()  
.EE
.SH BUILT\-IN FUNCTIONALS
TBD.
.SH BUILT\-IN VECTOR FUNCTIONS
TBD.
.SH NOTES
TBD.
.SH BUGS
Report on GitHub https://github.com/seamplex/feenox or at
jeremy\[at]seamplex.com
.SH SEE ALSO
\f[B]gmsh\f[R]\f[CR](1)\f[R], \f[B]mpirun\f[R]\f[CR](1)\f[R],
\f[B]paraview\f[R]\f[CR](1)\f[R]
.PP
The FeenoX web page contains links to the full source code, binary
versions, updates, examples, verification & validation cases and full
documentation: https://www.seamplex.com/feenox.
.SH AUTHORS
Jeremy Theler jeremy\[at]seamplex.com.