# Wasora reference sheet

This reference sheet is for wasora v0.5.160-g53c190f .

$wasora wasora v0.5.159-g4df4130 wasora’s an advanced suite for optimization & reactor analysis$

# 1 Keywords

## 1.1=

<var>[ [<expr_tmin>, <expr_tmax>] | @<expr_t> ] = <expr> <vector>(<expr_i>)[<expr_i_min, expr_i_max>] [ [<expr_tmin>, <expr_tmax>] | @<expr_t> ] = <expr> <matrix>(<expr_i>,<expr_j>)[<expr_i_min, expr_i_max; expr_j_min, expr_j_max>] [ [<expr_tmin>, <expr_tmax>] | @<expr_t> ] = <expr>

## 1.2.=

{ 0[(i[,j]][<imin:imax[;jmin:jmax]>] | <expr1> } .= <expr2>

## 1.3ABORT

Catastrophically abort the execution and quit wasora.

ABORT

Whenever the instruction ABORT is executed, wasora quits without closing files or unlocking shared memory objects. The objective of this instruction is, as illustrated in the examples, either to debug complex input files and check the values of certain variables or to conditionally abort the execution using IF clauses.

## 1.4ALIAS

Defines a scalar alias of an already-defined indentifier.

ALIAS { <new_var_name> IS <existing_object> | <existing_object> AS <new_name> }

## 1.5CALL

Executes a previously dynamically-loaded user-provided routine.

CALL <name> [ expr_1 expr_2 ... expr_n ]

## 1.6CLOSE

CLOSE

## 1.7CONST

Marks a scalar variable, vector or matrix as a constant.

CONST name_1 [ <name_2> ] ... [ <name_n> ]

## 1.8DEFAULT_ARGUMENT_VALUE

Give a default value for an optional commandline argument.

DEFAULT_ARGUMENT_VALUE <constant> <string>

If a $n 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. ## 1.9DIFFERENTIAL DIFFERENTIAL { <vars> | <vectors> | <matrices> } ## 1.10FILE Defines a file, either as input or as output, for further reference. < FILE | OUTPUT_FILE | INPUT_FILE > <name> <printf_format> [ expr_1 expr_2 ... expr_n ] [ INPUT | OUTPUT | MODE <fopen_mode> ] [ OPEN | DO_NOT_OPEN ] ## 1.11FIT 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_n> ] [ RANGE_MAX <expr_1> <expr_2> ... <expr_n> ] [ DELTAEPSREL <expr> ] [ DELTAEPSABS <expr> ] [ MAX_ITER <expr> ] [ VERBOSE ] [ RERUN | DO_NOT_RERUN ] ## 1.12FUNCTION Defines a function of one or more variables. FUNCTION <name>(<var_1>[,var2,...,var_n]) { [ = <expr> | FILE_PATH <file_path> | ROUTINE <name> | | MESH <name> { DATA <data> | VECTOR <vector> { NODES | CELLS } } | [ VECTOR_DATA <vector_1> <vector_2> ... <vector_n> <vector_n+1> ] } [COLUMNS <num_expr_1> <num_expr_2> ... <num_expr_n> <num_expr_n+1> ] [ INTERPOLATION { linear | polynomial | spline | spline_periodic | akima | akima_periodic | steffen | nearest | shepard | modified_shepard | bilinear } ] [ INTERPOLATION_THRESHOLD <expr> ] [ SHEPARD_RADIUS <expr> ] [ SHEPARD_EXPONENT <expr> ] [ SIZES <expr_1> <expr_2> ... <expr_n> ] [ X_INCREASES_FIRST <expr> ] [ DATA <num_expr_1> <num_expr_2> ... <num_expr_N> ] ## 1.13HISTORY Record the time history of a variable as a function of time. HISTORY <variable> <function> ## 1.14IF Begins a conditional block. IF expr <block_of_instructions_if_expr_is_true> [ ELSE ] [block_of_instructions_if_expr_is_false] ENDIF ## 1.15IMPLICIT Defines whether implicit declaration of variables is allowed or not. Asks wasora not to evaluate assignments at parse time. IMPLICIT { NONE | ALLOWED } By default, wasora 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 IMPLICIT NONE. Whether implicit declaration is allowed or explicit declaration is required depends on the last IMPLICIT keyword given, which by default is ALLOWED. ## 1.16INCLUDE Include another wasora input file. INCLUDE <file_path> [ FROM <num_expr> ] [ TO <num_expr> ] Includes the input file located in the string file_path at the current location. The effect is the same as copying and pasting the contents of the included file at the location of the INCLUDE keyword. The path can be relative or absolute. Note, however, that when including files inside IF 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 optional FROM and TO keywords can be used to include only portions of a file. ## 1.17INITIAL_CONDITIONS_MODE Defines how initial conditions of DAE problems are computed. INITIAL_CONDITIONS_MODE { AS_PROVIDED | FROM_VARIABLES | FROM_DERIVATIVES } In DAE problems, initial conditions may be either: • equal to the provided expressions (AS_PROVIDED) • the derivatives computed from the provided phase-space variables (FROM_VARIABLES) • the phase-space variables computed from the provided derivatives (FROM_DERIVATIVES) In the first case, it is up to the user to fulfill the DAE system at $$t = 0$$. If the residuals are not small enough, a convergence error will occur. The FROM_VARIABLES option means calling IDA’s IDACalcIC routine with the parameter IDA_YA_YDP_INIT. The FROM_DERIVATIVES option means calling IDA’s IDACalcIC 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 DIFFERENTIAL keyword may be used to explicitly define them. See the “SUNDIALS documentation”: “https://computation.llnl.gov/casc/sundials/documentation/ida_guide.pdf” for further information. ## 1.18LOAD_PLUGIN Loads a wasora plug-in from a dynamic shared object. LOAD_PLUGIN { <file_path> | <plugin_name> } A wasora plugin in the form of a dynamic shared object (i.e. .so) can be loaded either with the LOAD_PLUGIN keyword or from the command line with the -p option. Either a file path or a plugin name can be given. The following locations are tried: • the current directory ./ • the parent directory ../ • the user’s LD_LIBRARY_PATH • the cache file /etc/ld.so.cache • the directories /lib, /usr/lib, /usr/local/lib If a wasora plugin was compiled and installed following the make install procedure, the plugin should be loaded by just passing the name to LOAD_PLUGIN. ## 1.19LOAD_ROUTINE Loads one or more routines from a dynamic shared object. LOAD_ROUTINE <file_path> <routine_1> [ <routine_2> ... <routine_n> ] ## 1.20M4 Calls the m4 macro processor with definitions from wasora variables. M4 { INPUT_FILE <file_id> | FILE_PATH <file_path> } { OUTPUT_FILE <file_id> | OUTPUT_FILE_PATH <file_path> } [ MACRO <name> [ <format> ] <definition> ] } ## 1.21MATRIX Defines a matrix. MATRIX <name> ROWS <expr> COLS <expr> [ DATA num_expr_1 num_expr_2 ... num_expr_n ] ## 1.22MINIMIZE MINIMIZE <function> [ METHOD { conjugate_fr | conjugate_pr | vector_bfgs2 | vector_bfgs | steepest_descent | nmsimplex2 | nmsimplex | nmsimplex2rand } [ GRADIENT <expr_1> <expr_2> ... <expr_n> ] [ GUESS <expr_1> <expr_2> ... <expr_n> ] [ MIN <expr_1> <expr_2> ... <expr_n> ] [ MAX <expr_1> <expr_2> ... <expr_n> ] [ STEP <expr_1> <expr_2> ... <expr_n> ] [ VERBOSE ] [ NORERUN ] [ MAX_ITER <expr> ] [ TOL <expr> ] [ GRADTOL <expr> ] ## 1.23PARAMETRIC Sistematically sweeps a zone of the parameter space. PARAMETRIC <var_1> [ ... <var_n> ] [ TYPE { linear | logarithmic | random | gaussianrandom | sobol | niederreiter | halton | reversehalton } ] [ MIN <num_expr_1> ... <num_expr_n> ] [ MAX <num_expr_1> ... <num_expr_n> ] [ STEP <num_expr_1> ... <num_expr_n> ] [ NSTEPS <num_expr_1> ... <num_expr_n> ] [ OUTER_STEPS <num_expr> ] [ MAX_DAUGHTERS <num_expr> ] [ OFFSET <num_expr> ] [ ADIABATIC ] ## 1.24PHASE_SPACE PHASE_SPACE { <vars> | <vectors> | <matrices> } ## 1.25PRINT Prints plaint-text data to the standard output or to an output file. PRINT [ FILE <file_id> | FILE_PATH <file_path> ] [ NONEWLINE ] [ SEP <string> ] [ NOSEP ] [ HEADER ] [ SKIP_STEP <expr> ] [ SKIP_STATIC_STEP <expr> ] [ SKIP_TIME <expr> ] [ SKIP_HEADER_STEP <expr> ] [ <object_1> <object_2> ... <object_n> ] [ TEXT <string_1> ... TEXT <string_n> ] Each argument object that is not a keyword is expected to be part of the output, can be either a matrix, a vector, an 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 IMPLICIT is ALLOWED, 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 TEXT keyword. Hashes~# appearing literal strings have to be quoted to prevent the parser to treat them as comments within the wasora input file. Whenever an argument starts with a porcentage sign ‘%’, it is treated as a printf-compatible format definition and all the objects that follow it are printed using the given format until a new format definition is found. All the objects are treated as double-precision floating point numbers, so only floating point formats should be given. The default format is ‘%e’. Matrices, vectors, scalar expressions, format modifiers and string literals can be given in the desired order, and are processed from left to right. Vectors are printed element-by-element in a single row. See PRINT_VECTOR to print vectors column-wise. Matrices are printed element-by-element in a row-major fashion if mixed with other objects but in the natural row and column fashion if it is the only given object. If the FILE keyword is not provided, default is to write to stdout. If the NONEWLINE keyword is not provided, default is to write a newline ‘\n’ character after all the objects are processed. The SEP keywords expects a string used to separate printed objects, the default is a tab ‘\t’ character. Use the NOSEP keyword to define an empty string as object separator. If the HEADER keyword is given, a single line containing the literal text given for each object is printed at the very first time the PRINT instruction is processed, starting with a hash # character. If the SKIP_STEP (SKIP_STATIC_STEP)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. By default the PRINT instruction is evaluated every step. The SKIP_HEADER_STEP keyword works similarly for the optional HEADER but by default it is only printed once. The SKIP_TIME keyword use time advancements to choose how to skip printing and may be useful for non-constant time-step problems. Prints one or more functions as a table of values of dependent and independent variables. PRINT_FUNCTION <function_1> [ { function_2 | expr_1 } ... { function_n | expr_n-1 } ] [ FILE <file_id> | FILE_PATH <file_path> ] [ HEADER ] [ MIN <expr_1> <expr_2> ... <expr_m> ] [ MAX <expr_1> <expr_2> ... <expr_m> ] [ STEP <expr_1> <expr_2> ... <expr_m> ] [ NSTEPs <expr_1> <expr_2> ... <expr_m> ] [ FORMAT <print_format> ] [ PHYSICAL_ENTITY <name> ] Prints one or more vectors. PRINT_VECTOR [ FILE <file_id> ] FILE_PATH <file_path> ] [ { VERTICAL | HORIZONTAL } ] [ ELEMS_PER_LINE <expr> ] [ FORMAT <print_format> ] <vector_1> [ vector_2 ... vector_n ] ## 1.28READ Reads data (variables, vectors o matrices) from external objects. [ READ | WRITE ] [ SHM <name> ] [ { ASCII_FILE_PATH | BINARY_FILE_PATH } <file_path> ] [ { ASCII_FILE | BINARY_FILE } <identifier> ] ///kw+READ+usage [ IGNORE_NULL ] [ object_1 object_2 ... object_n ] ## 1.29SEMAPHORE Performs either a wait or a post operation on a named shared semaphore. [ SEMAPHORE | SEM ] <name> { WAIT | POST } ## 1.30SHELL Executes a shell command. SHELL <print_format> [ expr_1 expr_2 ... expr_n ] ## 1.31SOLVE Solves a non-linear system of~$$n$$ equations with~$$n$$ unknowns. SOLVE <n> UNKNOWNS <var_1> <var_2> ... <var_n> RESIDUALS <expr_1> <expr_2> ... <expr_n> ] GUESS <expr_1> <expr_2> ... <expr_n> ] [ METHOD { dnewton | hybrid | hybrids | broyden } ] [ EPSABS <expr> ] [ EPSREL <expr> ] [ MAX_ITER <expr> ] [ VERBOSE ] ## 1.32TIME_PATH Forces transient problems to pass through specific instants of time. TIME_PATH [ expr_1 ] [ expr_2 ] ... [ expr_n ] The time step dt will be reduced whenever the distance between the current time t and the next expression in the list is greater than dt so as to force t to coincide with the expressions given. The list of expresssions should evaluate to a sorted list of values. ## 1.33VAR Defines one or more scalar variables. VAR <name_1> [ <name_2> ] ... [ <name_n> ] ## 1.34VECTOR Defines a vector. VECTOR <name> SIZE <expr> [ DATA <expr_1> <expr_2> ... <expr_n> | FUNCTION_DATA <function> ] ## 1.35WRITE Writes data (variables, vectors o matrices) to external objects. See the READ keyword for usage details. # 2 Mesh-related keywords ## 2.1MATERIAL MATERIAL <name> [ INCREMENTAL <material> ] [ <property_name> <expr> ] ## 2.2MESH MESH [ NAME <name> ] [ FILE <file_id> | FILE_PATH <file_path> ] [ STRUCTURED ] [ DIMENSIONS <num_expr> ] [ ORDERING { unknown | node } ] [ SCALE_FACTOR <expr> ] [ OFFSET_X <expr> ] [ OFFSET_Y <expr> ] [ OFFSET_Z <expr> ] [ DEGREES <num_expr> ] [ NCELLS_X <expr> ] [ NCELLS_Y <expr> ] [ NCELLS_Z <expr> ] [ LENGTH_X <expr> ] [ LENGTH_Y <expr> ] [ LENGTH_Z <expr> ] [ DELTA_X <expr> ] [ DELTA_Y <expr> ] [ DELTA_Z <expr> ] [ READ_DATA <name_in_mesh> AS <function_name> ... ] ## 2.3MESH_FILL_VECTOR MESH_FILL_VECTOR [ MESH <mesh_identifier> ] [ NODES | CELLS ] VECTOR <vector> { FUNCTION <function> | EXPRESSION <expr> } ## 2.4MESH_FIND_MAX MESH_FIND_MAX { FUNCTION <function> | EXPRESSION <expr> } [ MESH <mesh_identifier> ] [ NODES | CELLS ] [ MAX <variable> ] [ I_MAX <variable> ] [ X_MAX <variable> ] [ Y_MAX <variable> ] [Z_MAX <variable> ] ## 2.5MESH_INTEGRATE MESH_INTEGRATE { FUNCTION <function> | EXPRESSION <expr> } OVER <physical_entity> RESULT <variable> [ MESH <mesh_identifier> ] [ NODES | CELLS ] [ GAUSS_POINTS <num_expr> ] ## 2.6MESH_MAIN MESH_MAIN [ <mesh_identifier> ] ## 2.7MESH_POST MESH_POST [ MESH <mesh_identifier> ] { FILE <name> | FILE_PATH <file_path> } [ NO_MESH ] [ FORMAT { gmsh | vtk } ] [ CELLS | ] NODE ] [ NO_PHYSICAL_NAMES ] [ VECTOR <component_1> <component_2> <component_3> ] [ <scalar_1> ] [ <scalar_2> ] ... ## 2.8PHYSICAL_ENTITY PHYSICAL_ENTITY [ NAME <name> ] [ ID <expr> ] [ MESH <identifier> ] [ MATERIAL <name> ] [ X_MIN <expr> ] [ X_MAX <expr> ] [ Y_MIN <expr> ] [ Y_MAX <expr> ] [ Z_MIN <expr> ] [ Z_MAX <expr> ] [ BC { <problem_dependent_expressions> } ] ## 2.9PHYSICAL_PROPERTY PHYSICAL_PROPERTY <name> [ <material_name1> <expr1> [ <material_name2> <expr2> ] ... ] # 3 Variables ## 3.1done Flag that indicates whether the overall calculation is over. ## 3.2done_outer Flag that indicates whether the parametric, optimization of fit calculation is over or not. It is set to true (i.e. $$\neq 0$$) by wasora whenever the outer calculation is considered to be finished, which can be that the parametric calculation swept the desired parameter space or that the optimization algorithm reached the desired convergence criteria. If the user sets it to true, the current step is marked as the last outer step and the transient calculation ends after finishing the step. ## 3.3done_static Flag that indicates whether the static calculation is over or not. It is set to true (i.e. $$\neq 0$$) by wasora if step_static $$\ge$$ static_steps. 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. ## 3.4done_transient Flag that indicates whether the transient calculation is over or not. It is set to true (i.e. $$\neq 0$$) by wasora if t $$\ge$$ end_time. 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. ## 3.5dt Actual value of the time step for transient calculations. When solving DAE systems, this variable is set by wasora. 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 t. Default value is 1/16, which is a power of two and roundoff errors are thus reduced. ## 3.6end_time Final time of the transient calculation, to be set by the user. The default value is zero, meaning no transient calculation. ## 3.7i Dummy index, used mainly in vector and matrix row subindex expressions. ## 3.8infinite A very big positive number, which can be used as end_time = infinite or to define improper integrals with infinite limits. Default is $$2^{50} \approx 1 \times 10^{15}$$. ## 3.9in_outer_initial Flag that indicates if the current step is the initial step of an optimization of fit run. ## 3.10in_static Flag that indicates if wasora is solving the iterative static calculation. Flag that indicates if wasora is in the first step of the iterative static calculation. Flag that indicates if wasora is in the last step of the iterative static calculation. ## 3.11in_transient Flag that indicates if wasora is solving transient calculation. ## 3.12in_transient_first Flag that indicates if wasora is in the first step of the transient calculation. ## 3.13in_transient_last Flag that indicates if wasora is in the last step of the transient calculation. ## 3.14j Dummy index, used mainly in matrix column subindex expressions. ## 3.15max_dt Maximum bound for the time step that wasora should take when solving DAE systems. ## 3.16min_dt Minimum bound for the time step that wasora should take when solving DAE systems. ## 3.17ncores The number of online available cores, as returned by sysconf(_SC_NPROCESSORS_ONLN). This value can be used in the MAX_DAUGHTERS expression of the PARAMETRIC keyword (i.e ncores/2). ## 3.18on_gsl_error 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. ## 3.19on_ida_error This should be set to a mask that indicates how to proceed if an error ir raised in any routine of the SUNDIALS IDA Library. ## 3.20on_nan 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 wasora. ## 3.21pi A double-precision floating point representaion of the number $$\pi$$, equal to math.h ’s M_PI constant. ## 3.22pid The UNIX process id of wasora (or the plugin). ## 3.23realtime_scale If this variable is not zero, then the transient problem is run trying to syncrhonize the problem time with realtime, up to a scale given. For example, if the scale is set to one, then wasora will advance the problem time at the same pace that the real wall time advances. If set to two, wasora’s time wil advance twice as fast as real time, and so on. If the calculation time is slower than real time modified by the scale, this variable has no effect on the overall behavior and execution will proceed as quick as possible with no delays. ## 3.24rel_error Maximum allowed relative error for the solution of DAE systems. Default value is is $$1 \times 10^{-6}$$. If a fine per-variable error control is needed, special vector abs_error should be used. ## 3.25static_steps Number of steps that ought to be taken during the static calculation, to be set by the user. The default value is one, meaning only one static step. ## 3.26step_outer Indicates the current step number of the iterative outer calculation (parametric, optimization or fit). Indicates the current step number of the iterative inner calculation (optimization or fit). ## 3.27step_static Indicates the current step number of the iterative static calculation. ## 3.28step_transient Indicates the current step number of the transient static calculation. ## 3.29t Actual value of the time for transient calculations. This variable is set by wasora, 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 t. ## 3.30zero A very small positive number, which is taken to avoid roundoff errors when comparing floating point numbers such as replacing $$a \leq a_\text{max}$$ with $$a < a_\text{max} +$$ zero. Default is $$(1/2)^{-50} \approx 9\times 10^{-16}$$ . # 4 Mesh-related variables ## 4.1cells Number of cells of the unstructured grid. This number is the actual quantity of volumetric elements in which the domain was discretized. ## 4.2elements Number of total elements of the unstructured grid. This number include those surface elements that belong to boundary physical entities. ## 4.3eps Small value. Default is $$10^{-6}$$. ## 4.4nodes Number of nodes of the unstructured grid. ## 4.5x Holder variable for spatial dependance of functions, such spatial distribution of physical properties or results of partial differential equations. ## 4.6y Idem as x. ## 4.7z Idem as x. # 5 Functions ## 5.1abs Returns the absolute value of the argument $$x$$. y = abs(x) ## 5.2acos Computes arc in radians whose cosine is equal to the argument $$x$$. A NaN error is raised if $$|x|>1$$. y = acos(x) ## 5.3asin Computes arc in radians whose sine is equal to the argument $$x$$. A NaN error is raised if $$|x|>1$$. y = asin(x) ## 5.4atan Computes, in radians, the arc tangent of the argument $$x$$. atan(x) ## 5.5atan2 Computes, in radians, the arc tangent of quotient $$y/x$$, using the signs of the two arguments to determine the quadrant of the result, which is in the range $$[-\pi,\pi]$$. atan(y,x) ## 5.6ceil Returns the smallest integral value not less than the argument $$x$$. ceil(x) ## 5.7clock Returns the value of a certain clock in seconds measured from a certain (but specific) milestone. The kind of clock and the initial milestone depends on the optional flag $$f$$. It defaults to zero, meaning wall time since the UNIX Epoch. The list and the meanings of the other available values for $$f$$ can be checked in the clock_gettime (2) system call manual page. clock([f]) ## 5.8cos Computes the cosine of the argument $$x$$, where $$x$$ is in radians. A cosine wave can be generated by passing as the argument $$x$$ a linear function of time such as $$\omega t+\phi$$, where $$\omega$$ controls the frequency of the wave and $$\phi$$ controls its phase. cos(x) ## 5.9cosh Computes the hyperbolic cosine of the argument $$x$$, where $$x$$ is in radians. cosh(x) ## 5.10d_dt Computes the time derivative of the signal $$x$$ using the difference between the value of the signal in the previous time step and the actual value divided by the time step. For $$t=0$$, the return value is zero. Unlike the functional derivative, this function works with expressions and not with functions. Therefore the argument $$x$$ may be for example an expression involving a variable that may be read from a shared-memory object, whose time derivative cannot be computed with derivative. d_dt(x) ## 5.11deadband Filters the first argument $$x$$ with a deadband centered at zero with an amplitude given by the second argument $$a$$. deadband(x, a) ## 5.12equal Checks if the two first expressions $$a$$ and $$b$$ are equal, up to the tolerance given by the third optional argument $$\epsilon$$. If either $$|a|>1$$ or $$|b|>1$$, the arguments are compared using GSL’s gsl_fcmp, otherwise the absolute value of their difference is compared against $$\epsilon$$. This function returns zero if the arguments are not equal and one otherwise. Default value for $$\epsilon = 10^{-16}$$. equal(a, b, [eps]) ## 5.13exp Computes the exponential function the argument $$x$$, i.e. the base of the natural logarithms raised to the $$x$$-th power. exp(x) ## 5.14expint1 Computes the first exponential integral function of the argument $$x$$. If $$x$$ equals zero, a NaN error is issued. expint1(x) ## 5.15expint2 Computes the second exponential integral function of the argument $$x$$. expint2(x) ## 5.16expint3 Computes the third exponential integral function of the argument $$x$$. expint3(x) ## 5.17expintn Computes the $$n$$-th exponential integral function of the argument $$x$$. If $$n$$ equals zero or one and $$x$$ zero, a NaN error is issued. expintn(n,x) ## 5.18floor Returns the largest integral value not greater than the argument $$x$$. floor(x) ## 5.19heaviside Computes the zero-centered Heaviside step function of the argument $$x$$. If the optional second argument $$\epsilon$$ is provided, the discontinuous step at $$x=0$$ is replaced by a ramp starting at $$x=0$$ and finishing at $$x=\epsilon$$. heaviside(x, [eps]) ## 5.20if Performs a conditional testing of the first argument $$a$$, and returns either the second optional argument $$b$$ if $$a$$ is different from zero or the third optional argument $$c$$ if $$a$$ evaluates to zero. The comparison of the condition $$a$$ with zero is performed within the precision given by the optional fourth argument $$\epsilon$$. If the second argument $$c$$ is not given and $$a$$ is not zero, the function returns one. If the third argument $$c$$ is not given and $$a$$ is zero, the function returns zero. The default precision is $$\epsilon = 10^{-16}$$. Even though if is a logical operation, all the arguments and the returned value are double-precision floating point numbers. if(a, [b], [c], [eps]) ## 5.21integral_dt Computes the time integral of the signal $$x$$ using the trapezoidal rule using the value of the signal in the previous time step and the current value. At $$t = 0$$ the integral is initialized to zero. Unlike the functional integral, this function works with expressions and not with functions. Therefore the argument $$x$$ may be for example an expression involving a variable that may be read from a shared-memory object, whose time integral cannot be computed with integral. integral_dt(x) ## 5.22integral_euler_dt Idem as integral_dt but uses the backward Euler rule to update the integral value. This function is provided in case this particular way of approximating time integrals is needed. integral_euler_dt(x) ## 5.23is_even Returns one if the argument $$x$$ rounded to the nearest integer is even. y = is_even(x) ## 5.24is_in_interval Returns true if the argument~$$x$$ is in the interval~$$[a,b)$$, i.e. including~$$a$$ but excluding~$$b$$. is_in_interval(x, a, b) ## 5.25is_odd Returns one if the argument $$x$$ rounded to the nearest integer is odd. y = is_odd(x) ## 5.26j0 Computes the regular cylindrical Bessel function of zeroth order evaluated at the argument $$x$$. j0(x) ## 5.27lag Filters the first argument $$x(t)$$ with a first-order lag of characteristic time $$\tau$$, i.e. this function applies the transfer function !bt [ G(s) = ] !et to the time-dependent signal $$x(t)$$, by assuming that it is constant during the time interval $$[t-\Delta t,t]$$ and using the analytical solution of the differential equation for that case at $$t = \Delta t$$ with the initial condition $$y(0) = y(t-\Delta t)$$. lag(x, tau) ## 5.28lag_bilinear Filters the first argument $$x(t)$$ with a first-order lag of characteristic time $$\tau$$, i.e. this function applies the transfer function !bt [ G(s) = ] !et to the time-dependent signal $$x(t)$$ by using the bilinear transformation formula. lag_bilinear(x, tau) ## 5.29lag_euler Filters the first argument $$x(t)$$ with a first-order lag of characteristic time $$\tau$$, i.e. this function applies the transfer function !bt [ G(s) = ] !et to the time-dependent signal $$x(t)$$ by using the Euler forward rule. lag_euler(x, tau) ## 5.30last Returns the value the signal $$x$$ had in the previous time step. This function is equivalent to the $$Z$$-transform operator “delay” denoted by $$z^{-1}\left[x\right]$$. For $$t=0$$ the function returns the actual value of $$x$$. The optional flag $$p$$ should be set to one if the reference to last is done in an assignment over a variable that already appears insi expression $$x$$. See example number 2. last(x,[p]) ## 5.31limit Limits the first argument $$x$$ to the interval $$[a,b]$$. The second argument $$a$$ should be less than the third argument $$b$$. limit(x, a, b) ## 5.32limit_dt Limits the value of the first argument $$x(t)$$ so to that its time derivative is bounded to the interval $$[a,b]$$. The second argument $$a$$ should be less than the third argument $$b$$. limit_dt(x, a, b) ## 5.33log Computes the natural logarithm of the argument $$x$$. If $$x$$ is zero or negative, a NaN error is issued. log(x) ## 5.34mark_max Returns the integer index $$i$$ of the maximum of the arguments $$x_i$$ provided. Currently only maximum of ten arguments can be provided. mark_max(x1, x2, [...], [x10]) ## 5.35mark_min Returns the integer index $$i$$ of the minimum of the arguments $$x_i$$ provided. Currently only maximum of ten arguments can be provided. mark_max(x1, x2, [...], [x10]) ## 5.36max Returns the maximum of the arguments $$x_i$$ provided. Currently only maximum of ten arguments can be provided. max(x1, x2, [...], [x10]) ## 5.37min Returns the minimum of the arguments $$x_i$$ provided. Currently only maximum of ten arguments can be provided. min(x1, x2, [...], [x10]) ## 5.38mod Returns the remainder of the division between the first argument $$a$$ and the second $$b$$. Both arguments may be non-integral. mod(a, b) ## 5.39not Returns one if the first argument $$x$$ is zero and zero otherwise. The second optional argument $$\epsilon$$ gives the precision of the “zero” evaluation. If not given, default is $$\epsilon = 10^{-16}$$. not(x, [eps]) ## 5.40random Returns a random real number uniformly distributed between the first real argument $$x_1$$ and the second one $$x_2$$. If the third integer argument $$s$$ 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. random(x1, x2, [s]) ## 5.41random_gauss Returns a random real number with a Gaussian distribution with a mean equal to the first argument $$x_1$$ and a standard deviation equatl to the second one $$x_2$$. If the third integer argument $$s$$ 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. random_gauss(x1, x2, [s]) ## 5.42round Rounds the argument $$x$$ to the nearest integer. Halfway cases are rounded away from zero. round(x) ## 5.43sawtooth_wave Computes a sawtooth wave betwen 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 $$x$$ a linear function of time such as $$\omega t+\phi$$, where $$\omega$$ controls the frequency of the wave and $$\phi$$ controls its phase. sawtooth_wave(x) ## 5.44sgn Returns minus one, zero or plus one depending on the sign of the first argument $$x$$. The second optional argument $$\epsilon$$ gives the precision of the “zero” evaluation. If not given, default is $$\epsilon = 10^{-16}$$. sgn(x, [eps]) ## 5.45sin Computes the sine of the argument $$x$$, where $$x$$ is in radians. A sine wave can be generated by passing as the argument $$x$$ a linear function of time such as $$\omega t+\phi$$, where $$\omega$$ controls the frequency of the wave and $$\phi$$ controls its phase. sin(x) ## 5.46sinh Computes the hyperbolic sine of the argument $$x$$, where $$x$$ is in radians. sinh(x) ## 5.47sqrt Computes the positive square root of the argument $$x$$. If $$x$$ is negative, a NaN error is issued. sqrt(x) ## 5.48square_wave Computes a square function betwen zero and one with a period equal to one. The output is one for $$0 < x < 1/2$$ and goes to zero for $$1/2 < x < 1$$. As with the sine wave, a square wave can be generated by passing as the argument $$x$$ a linear function of time such as $$\omega t+\phi$$, where $$\omega$$ controls the frequency of the wave and $$\phi$$ controls its phase. square_wave(x) ## 5.49tan Computes the tangent of the argument $$x$$, where $$x$$ is in radians. tan(x) ## 5.50tanh Computes the hyperbolic tangent of the argument $$x$$, where $$x$$ is in radians. tanh(x) ## 5.51threshold_max Returns one if the first argument $$x$$ is greater than the threshold given by the second argument $$a$$, and zero otherwise. If the optional third argument $$b$$ is provided, an hysteresis of width $$b$$ is needed in order to reset the function value. Default is no hysteresis, i.e. $$b=0$$. threshold_max(x, a, [b]) ## 5.52threshold_min Returns one if the first argument $$x$$ is less than the threshold given by the second argument $$a$$, and zero otherwise. If the optional third argument $$b$$ is provided, an hysteresis of width $$b$$ is needed in order to reset the function value. Default is no hysteresis, i.e. $$b=0$$. threshold_min(x, a, [b]) ## 5.53triangular_wave Computes a triangular wave betwen 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 $$x$$ a linear function of time such as $$\omega t+\phi$$, where$\$ controls the frequency of the wave and $$\phi$$ controls its phase.

triangular_wave(x)

# 6 Functionals

## 6.1derivative

Computes the derivative of the expression $$f(x)$$ given in the first argument with respect to the variable $$x$$ given in the second argument at the point $$x=a$$ given in the third argument using an adaptive scheme. The fourth optional argument $$h$$ is the initial width of the range the adaptive derivation method starts with. The fifth optional argument $$p$$ is a flag that indicates whether a backward ($$p < 0$$), centered ($$p = 0$$) or forward ($$p > 0$$) stencil is to be used. This functional calls the GSL functions gsl_deriv_central or gsl_deriv_forward according to the indicated flag $$p$$. Defaults are $$h = (1/2)^{-10} \approx 9.8 \times 10^{-4}$$ and $$p = 0$$.

derivative(f(x), x, a, [h], [p])

## 6.2func_min

Finds the value of the variable $$x$$ given in the second argument which makes the expression $$f(x)$$ given in the first argument to take local a minimum in the in the range $$[a,b]$$ given by the third and fourth arguments. If there are many local minima, the one that is closest to $$(a+b)/2$$ is returned. The optional fifth argument $$\epsilon$$ gives a relative tolerance for testing convergence, corresponding to GSL epsrel (note that epsabs is set also to $$\epsilon)$$. The sixth optional argument is an integer which indicates the algorithm to use: 0 (default) is quad_golden, 1 is brent and 2 is goldensection. See the GSL documentation for further information on the algorithms. The seventh optional argument $$p$$ is a flag that indicates how to proceed if there is no local minimum in the range $$[a,b]$$. If $$p = 0$$ (default), $$a$$ is returned if $$f(a) < f(b)$$ and $$b$$ otherwise. If $$p = 1$$ then the local minimum algorimth is tried nevertheless. Default is $$\epsilon = (1/2)^{-20} \approx 9.6\times 10^{-7}$$.

y = func_min(f(x), x, a, b, [eps], [alg], [p])

## 6.3gauss_kronrod

Computes the integral of the expression $$f(x)$$ given in the first argument with respect to variable $$x$$ given in the second argument over the interval $$[a,b]$$ given in the third and fourth arguments respectively using a non-adaptive procedure which uses fixed Gauss-Kronrod-Patterson abscissae to sample the integrand at a maximum of 87 points. It is provided for fast integration of smooth functions. The algorithm applies the Gauss-Kronrod 10-point, 21-point, 43-point and 87-point integration rules in succession until an estimate of the integral is achieved within the relative tolerance given in the fifth optional argument $$\epsilon$$ It correspondes to GSL’s epsrel parameter (epsabs is set to zero).
The rules are designed in such a way that each rule uses all the results of its predecessors, in order to minimize the total number of function evaluations. Defaults are $$\epsilon = (1/2)^{-10} \approx 10^{-3}$$. See GSL reference for further information.

gauss_kronrod(f(x), x, a, b, [eps])

## 6.4gauss_legendre

Computes the integral of the expression $$f(x)$$ given in the first argument with respect to variable $$x$$ given in the second argument over the interval $$[a,b]$$ given in the third and fourth arguments respectively using the $$n$$-point Gauss-Legendre rule, where $$n$$ is given in the optional fourth argument. It is provided for fast integration of smooth functions with known polynomic order (it is exact for polynomials of order $$2n-1$$). This functional calls GSL function gsl_integration_glfixedp. Default is $$n = 12$$. See GSL reference for further information.

gauss_legendre(f(x), x, a, b, [n])

## 6.5integral

Computes the integral of the expression $$f(x)$$ given in the first argument with respect to variable $$x$$ given in the second argument over the interval $$[a,b]$$ given in the third and fourth arguments respectively using an adaptive scheme, in which the domain is divided into a number of maximum number of subintervals and a fixed-point Gauss-Kronrod-Patterson scheme is applied to each quadrature subinterval. Based on an estimation of the error commited, one or more of these subintervals may be split to repeat the numerical integration alogorithm with a refined division. The fifth optional argument $$\epsilon$$ is is a relative tolerance used to check for convergence. It correspondes to GSL’s epsrel parameter (epsabs is set to zero). The sixth optional argument $$1\leq k \le 6$$ is an integer key that indicates the integration rule to apply in each interval. It corresponds to GSL’s parameter key. The seventh optional argument gives the maximum number of subdivisions, which defaults to 1024. If the integration interval $$[a,b]$$ if finite, this functional calls the GSL function gsl_integration_qag. If $$a$$ is less that minus the internal variable infinite, $$b$$ is greater that infinite or both conditions hold, GSL functions gsl_integration_qagil, gsl_integration_qagiu or gsl_integration_qagi are called. The condition of finiteness of a fixed range $$[a,b]$$ can thus be changed by modifying the internal variable infinite. Defaults are $$\epsilon = (1/2)^{-10} \approx 10^{-3}$$ and $$k=3$$. The maximum numbers of subintervals is limited to 1024. Due to the adaptivity nature of the integration method, this function gives good results with arbitrary integrands, even for infinite and semi-infinite integration ranges. However, for certain integrands, the adaptive algorithm may be too expensive or even fail to converge. In these cases, non-adaptive quadrature functionals ought to be used instead. See GSL reference for further information.

integral(f(x), x, a, b, [eps], [k], [max_subdivisions])

## 6.6prod

Computes product of the $$N=b-a$$ expressions $$f(i)$$ given in the first argument by varying the variable~$$i$$ given in the second argument between~$$a$$ given in the third argument and~$$b$$ given in the fourth argument,~$$i = a, a+1, \dots ,b-1,b$$.

prod(f(i), i, a, b)

## 6.7root

Computes the value of the variable $$x$$ given in the second argument which makes the expression $$f(x)$$ given in the first argument to be equal to zero by using a root bracketing algorithm. The root should be in the range $$[a,b]$$ given by the third and fourth arguments. The optional fifth argument $$\epsilon$$ gives a relative tolerance for testing convergence, corresponding to GSL epsrel (note that epsabs is set also to $$\epsilon)$$. The sixth optional argument is an integer which indicates the algorithm to use: 0 (default) is brent, 1 is falsepos and 2 is bisection. See the GSL documentation for further information on the algorithms. The seventh optional argument $$p$$ is a flag that indicates how to proceed if the sign of $$f(a)$$ is equal to the sign of $$f(b)$$. If $$p=0$$ (default) an error is raised, otherwise it is not. If more than one root is contained in the specified range, the first one to be found is returned. The initial guess is $$x_0 = (a+b)/2$$. If no roots are contained in the range and $$p \neq 0$$, the returned value can be any value. Default is $$\epsilon = (1/2)^{-10} \approx 10^{3}$$.

root(f(x), x, a, b, [eps], [alg], [p])

## 6.8sum

Computes sum of the $$N=b-a$$ expressions $$f_i$$ given in the first argument by varying the variable $$i$$ given in the second argument between $$a$$ given in the third argument and $$b$$ given in the fourth argument, $$i=a,a+1,\dots,b-1,b$$.

sum(f_i, i, a, b)

# 7 Vector functions

## 7.1vecdot

Computes the dot product between vectors $$\vec{a}$$ and $$\vec{b}$$, which should have the same size.

vecdot(a,b)

## 7.2vecmax

Returns the biggest element of vector $$\vec{b}$$, taking into account its sign (i.e. $$1 > -2$$).

vecmax(b)

## 7.3vecmaxindex

Returns the index of the biggest element of vector $$\vec{b}$$, taking into account its sign (i.e. $$2 > -1$$).

vecmaxindex(b)

## 7.4vecmin

Returns the smallest element of vector $$\vec{b}$$, taking into account its sign (i.e. $$-2 < 1$$).

vecmin(b)

## 7.5vecminindex

Returns the index of the smallest element of vector $$\vec{b}$$, taking into account its sign (i.e. $$-2 < 1$$).

vecminindex(b)

## 7.6vecnorm

Computes euclidean norm of vector $$\vec{b}$$. Other norms can be computed explicitly using the sum functional, as illustrated in the example.

vecnorm(b)

## 7.7vecsize

Returns the size of vector $$\vec{b}$$.

vecsize(b)

## 7.8vecsum

Computes the sum of all the components of vector $$\vec{b}$$.

vecsum(b)