Reference documentation for deal.II version 8.1.0
Public Types | Public Member Functions | Static Public Member Functions | Private Attributes | List of all members
FunctionParser< dim > Class Template Reference

#include <function_parser.h>

Inheritance diagram for FunctionParser< dim >:
[legend]

Public Types

typedef std::map< std::string, doubleConstMap
 
typedef ConstMap::iterator ConstMapIterator
 

Public Member Functions

 FunctionParser (const unsigned int n_components=1, const double initial_time=0.0)
 
 ~FunctionParser ()
 
void initialize (const std::string &vars, const std::vector< std::string > &expressions, const ConstMap &constants, const bool time_dependent=false, const bool use_degrees=false)
 
void initialize (const std::string &vars, const std::vector< std::string > &expressions, const ConstMap &constants, const ConstMap &units, const bool time_dependent=false, const bool use_degrees=false)
 
void initialize (const std::string &vars, const std::string &expression, const ConstMap &constants, const bool time_dependent=false, const bool use_degrees=false)
 
void initialize (const std::string &vars, const std::string &expression, const ConstMap &constants, const ConstMap &units, const bool time_dependent=false, const bool use_degrees=false)
 
virtual double value (const Point< dim > &p, const unsigned int component=0) const
 
virtual void vector_value (const Point< dim > &p, Vector< double > &values) const
 
 DeclException2 (ExcParseError, int, char *,<< "Parsing Error at Column "<< arg1<< ". The parser said: "<< arg2)
 
 DeclException2 (ExcInvalidExpressionSize, int, int,<< "The number of components ("<< arg1<< ") is not equal to the number of expressions ("<< arg2<< ").")
 
- Public Member Functions inherited from Function< dim >
 Function (const unsigned int n_components=1, const double initial_time=0.0)
 
virtual ~Function ()=0
 
Functionoperator= (const Function &f)
 
virtual void value_list (const std::vector< Point< dim > > &points, std::vector< double > &values, const unsigned int component=0) const
 
virtual void vector_value_list (const std::vector< Point< dim > > &points, std::vector< Vector< double > > &values) const
 
virtual void vector_values (const std::vector< Point< dim > > &points, std::vector< std::vector< double > > &values) const
 
virtual Tensor< 1, dim > gradient (const Point< dim > &p, const unsigned int component=0) const
 
virtual void vector_gradient (const Point< dim > &p, std::vector< Tensor< 1, dim > > &gradients) const
 
virtual void gradient_list (const std::vector< Point< dim > > &points, std::vector< Tensor< 1, dim > > &gradients, const unsigned int component=0) const
 
virtual void vector_gradients (const std::vector< Point< dim > > &points, std::vector< std::vector< Tensor< 1, dim > > > &gradients) const
 
virtual void vector_gradient_list (const std::vector< Point< dim > > &points, std::vector< std::vector< Tensor< 1, dim > > > &gradients) const
 
virtual double laplacian (const Point< dim > &p, const unsigned int component=0) const
 
virtual void vector_laplacian (const Point< dim > &p, Vector< double > &values) const
 
virtual void laplacian_list (const std::vector< Point< dim > > &points, std::vector< double > &values, const unsigned int component=0) const
 
virtual void vector_laplacian_list (const std::vector< Point< dim > > &points, std::vector< Vector< double > > &values) const
 
std::size_t memory_consumption () const
 
- Public Member Functions inherited from FunctionTime
 FunctionTime (const double initial_time=0.0)
 
virtual ~FunctionTime ()
 
double get_time () const
 
virtual void set_time (const double new_time)
 
virtual void advance_time (const double delta_t)
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
void subscribe (const char *identifier=0) const
 
void unsubscribe (const char *identifier=0) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
 DeclException3 (ExcInUse, int, char *, std::string &,<< "Object of class "<< arg2<< " is still used by "<< arg1<< " other objects.\n"<< "(Additional information: "<< arg3<< ")\n"<< "Note the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "more information on what this error means.")
 
 DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier \""<< arg2<< "\" did subscribe to this object of class "<< arg1)
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Static Public Member Functions

static std::string default_variable_names ()
 

Private Attributes

fparser::FunctionParser * fp
 
bool initialized
 
unsigned int n_vars
 

Additional Inherited Members

- Public Attributes inherited from Function< dim >
const unsigned int n_components
 
- Static Public Attributes inherited from Function< dim >
static const unsigned int dimension = dim
 

Detailed Description

template<int dim>
class FunctionParser< dim >

This class implements a function object that gets its value by parsing a string describing this function. It is a wrapper class for the fparser library (see http://warp.povusers.org/FunctionParser/). This class lets you evaluate strings such as "sqrt(1-x^2+y^2)" for given values of 'x' and 'y'. Some of the information contained here is copied verbatim from the fparser.txt file that comes with the fparser library. Please refer also to that file both for clarifications on how this wrapper works, as well as for any issue regarding the licence that applies to this class. This class is used in the step-33 and step-36 tutorial programs (the latter being much simpler to understand).

By using this class you indicate that you accept the terms of the licence that comes with the fparser library. If you do not agree with them, you should not use this class or configure the deal.II library without the function parser (see the ReadMe file of deal.II on instructions for this).

The following example shows how to use this class:

// Define some constants that will be used by the function parser
std::map<std::string,double> constants;
constants["pi"] = numbers::PI;
// Define the variables that will be used inside the expressions
std::string variables = "x,y,z";
// Define the expressions of the individual components of a
// vector valued function with two components:
std::vector<std::string> expressions(2);
expressions[0] = "sin(2*pi*x)+sinh(pi*z)";
expressions[1] = "sin(2*pi*y)*exp(x^2)";
// Generate an empty function for these two components.
ParsedFunction<3> vector_function(2);
// And populate it with the newly created objects.
vector_function.initialize(variables,
expressions,
constants);

FunctionParser also provides an option to use units in expressions. We illustrate the use of this functionality with the following example:

// Define some constants that will be used by the function parser
std::map<std::string> constants;
std::map<std::string> units;
constants["PI"] = numbers::PI;
units["cm"] = 10;
units["m"] = 1000;
// Define the variables that will be used inside the expressions
std::string variables = "x,y";
// Define the expressions of the individual components of a
// vector valued function with two components:
std::vector<std::string> expressions(1);
expressions[0] = "x cm + y m + PI cm;
// Generate an empty function for these two components.
FunctionParser<2> vector_function;
// And populate it with the newly created objects.
vector_function.initialize(variables,
expressions,
constants,
units); //An extra argument here
// Point at which we want to evaluate the function
Point<2> point(2.0, 3.0);
// Output the evaluated function
std::cout << "Function " << "[" << expressions[0] << "]" <<
" @point " << "[" << point << "]" << " is " <<
"[" << vector_function.value(point) << "]" << std::endl;

Units are similar to constants in the way they are passed to the parser, i.e. via std::map<std::string,double>. But units are slightly different in that they have a higher precedence than any other operator (except parentheses). Thus for example "5/2in" is parsed as "5/(2*300)". (If you actually do want 5/2 inches, it has to be written as "(5/2)in".)

Overall, the main point of units is to make input expressions more readable since expressing, say, length as 10cm looks more natural than 10*cm.

Beware that the user has full control over units as well as full responsibility for "sanity" of the parsed expressions, because the parser does NOT know anything about the physical nature of units and one would not be warned when adding kilometers to kilograms.

The units argument to the initialize function is optional, i.e. the user does NOT have to use this functionality.

For more information on this feature, please see contrib/functionparser/fparser.txt

See http://warp.povusers.org/FunctionParser/ for an explanation on how the underlying library works.

From the fparser.txt file :

The library is intended to be very fast. It byte-compiles the
function string at parse time and interpretes this byte-code at
evaluation time.  The evaluation is straightforward and no recursions
are done (uses stack arithmetic).  Empirical tests show that it indeed
is very fast (specially compared to libraries which evaluate functions
by just interpreting the raw function string).

This class overloads the virtual methods value() and vector_value() of the Function base class with the byte compiled versions of the expressions given to the initialize() methods. Note that the class will not work unless you first call the initialize() method that accepts the text description of the function as an argument (among other things). The reason for this is that this text description may be read from an input file, and may therefore not be available at object construction time yet.

The syntax to describe a function follows usual programming practice, and is explained in this snippet from the fparser.txt file :

     The function string understood by the class is very similar to the C-syntax.
     Arithmetic float expressions can be created from float literals, variables
     or functions using the following operators in this order of precedence:

     ()             expressions in parentheses first
     -A             unary minus
     A^B            exponentiation (A raised to the power B)
     A*B  A/B  A%B  multiplication, division and modulo
     A+B  A-B       addition and subtraction
     A=B  A<B  A>B  comparison between A and B (result is either 0 or 1)
     A&B            result is 1 if int(A) and int(B) differ from 0, else 0.
     A|B            result is 1 if int(A) or int(B) differ from 0, else 0.

     Since the unary minus has higher precedence than any other operator, for
     example the following expression is valid: x*-y
     Note that the '=' comparison can be inaccurate due to floating point
     precision problems (eg. "sqrt(100)=10" probably returns 0, not 1).

     The class supports these functions:

     abs(A)    : Absolute value of A. If A is negative, returns -A otherwise
                 returns A.
     acos(A)   : Arc-cosine of A. Returns the angle, measured in radians,
                 whose cosine is A.
     acosh(A)  : Same as acos() but for hyperbolic cosine.
     asin(A)   : Arc-sine of A. Returns the angle, measured in radians, whose
                 sine is A.
     asinh(A)  : Same as asin() but for hyperbolic sine.
     atan(A)   : Arc-tangent of (A). Returns the angle, measured in radians,
                 whose tangent is (A).
     atan2(A,B): Arc-tangent of A/B. The two main differences to atan() is
                 that it will return the right angle depending on the signs of
                 A and B (atan() can only return values between -pi/2 and pi/2),
                 and that the return value of pi/2 and -pi/2 are possible.
     atanh(A)  : Same as atan() but for hyperbolic tangent.
     ceil(A)   : Ceiling of A. Returns the smallest integer greater than A.
                 Rounds up to the next higher integer.
     cos(A)    : Cosine of A. Returns the cosine of the angle A, where A is
                 measured in radians.
     cosh(A)   : Same as cos() but for hyperbolic cosine.
     cot(A)    : Cotangent of A (equivalent to 1/tan(A)).
     csc(A)    : Cosecant of A (equivalent to 1/sin(A)).
     eval(...) : This a recursive call to the function to be evaluated. The
                 number of parameters must be the same as the number of parameters
                 taken by the function. Usually called inside if() to avoid
                 infinite recursion.
     exp(A)    : Exponential of A. Returns the value of e raised to the power
                 A where e is the base of the natural logarithm, i.e. the
                 non-repeating value approximately equal to 2.71828182846.
     floor(A)  : Floor of A. Returns the largest integer less than A. Rounds
                 down to the next lower integer.
     if(A,B,C) : If int(A) differs from 0, the return value of this function is B,
                 else C. Only the parameter which needs to be evaluated is
                 evaluated, the other parameter is skipped; this makes it safe to
                 use eval() in them.
     int(A)    : Rounds A to the closest integer. 0.5 is rounded to 1.
     log(A)    : Natural (base e) logarithm of A.
     log10(A)  : Base 10 logarithm of A.
     max(A,B)  : If A>B, the result is A, else B.
     min(A,B)  : If A<B, the result is A, else B.
     sec(A)    : Secant of A (equivalent to 1/cos(A)).
     sin(A)    : Sine of A. Returns the sine of the angle A, where A is
                 measured in radians.
     sinh(A)   : Same as sin() but for hyperbolic sine.
     sqrt(A)   : Square root of A. Returns the value whose square is A.
     tan(A)    : Tangent of A. Returns the tangent of the angle A, where A
                 is measured in radians.
     tanh(A)   : Same as tan() but for hyperbolic tangent.


   Examples of function string understood by the class:

   "1+2"
   "x-1"
   "-sin(sqrt(x^2+y^2))"
   "sqrt(XCoord*XCoord + YCoord*YCoord)"

   An example of a recursive function is the factorial function:

   "if(n>1, n*eval(n-1), 1)"

 Note that a recursive call has some overhead, which makes it a bit slower
 than any other operation. It may be a good idea to avoid recursive functions
 in very time-critical applications. Recursion also takes some memory, so
 extremely deep recursions should be avoided (eg. millions of nested recursive
 calls).

 Also note that the if() function is the only place where making a recursive
 call is safe. In any other place it will cause an infinite recursion (which
 will make the program eventually run out of memory).

Vector-valued functions can either be declared using strings where the function components are separated by semicolons, or using a vector of strings each defining one vector component.

An example of time dependent scalar function is the following:

// Empty constants object
std::map<std::string> constants;
// Variables that will be used inside the expressions
std::string variables = "x,y,t";
// Define the expression of the scalar time dependent function.
std::string expression = "exp(y*x)*exp(-t)";
// Generate an empty scalar function
// And populate it with the newly created objects.
function.initialize(variables,
expression,
constants,
true); // This tells the parser that
// it is a time-dependent function
// and there is another variable
// to be taken into account (t).

The following is another example of how to instantiate a vector valued function by using a single string:

// Empty constants object
std::map<std::string> constants;
// Variables that will be used inside the expressions
std::string variables = "x,y";
// Define the expression of the vector valued function.
std::string expression = "cos(2*pi*x)*y^2; sin(2*pi*x)*exp(y)";
// Generate an empty vector valued function
FunctionParser<2> function(2);
// And populate it with the newly created objects.
function.initialize(variables,
expression,
constants);
Author
Luca Heltai, 2005

Definition at line 318 of file function_parser.h.

Member Typedef Documentation

template<int dim>
typedef std::map<std::string, double> FunctionParser< dim >::ConstMap

Type for the constant map. Used by the initialize() method.

Definition at line 351 of file function_parser.h.

template<int dim>
typedef ConstMap::iterator FunctionParser< dim >::ConstMapIterator

Iterator for the constants map. Used by the initialize() method.

Definition at line 358 of file function_parser.h.

Constructor & Destructor Documentation

template<int dim>
FunctionParser< dim >::FunctionParser ( const unsigned int  n_components = 1,
const double  initial_time = 0.0 
)

Constructor for Parsed functions. Its arguments are the same of the base class Function. The only difference is that this object needs to be initialized with initialize() method before you can use it. If an attempt to use this function is made before the initialize() method has been called, then an exception is thrown.

template<int dim>
FunctionParser< dim >::~FunctionParser ( )

Destructor. Explicitly delete the FunctionParser objects (there is one for each component of the function).

Member Function Documentation

template<int dim>
void FunctionParser< dim >::initialize ( const std::string &  vars,
const std::vector< std::string > &  expressions,
const ConstMap constants,
const bool  time_dependent = false,
const bool  use_degrees = false 
)

Initialize the function. This methods accepts the following parameters:

vars: a string with the variables that will be used by the expressions to be evaluated. Note that the variables can have any name (of course different from the function names defined above!), but the order IS important. The first variable will correspond to the first component of the point in which the function is evaluated, the second variable to the second component and so forth. If this function is also time dependent, then it is necessary to specify it by setting the time_dependent parameter to true. An exception is thrown if the number of variables specified here is different from dim (if this function is not time-dependent) or from dim+1 (if it is time-dependent).

expressions: a list of strings containing the expressions that will be byte compiled by the internal parser (FunctionParser). Note that the size of this vector must match exactly the number of components of the FunctionParser, as declared in the constructor. If this is not the case, an exception is thrown.

constants: a map of constants used to pass any necessary constant that we want to specify in our expressions (in the example above the number pi). An expression is valid if and only if it contains only defined variables and defined constants (other than the functions specified above). If a constant is given whose name is not valid (eg: constants["sin"] = 1.5;) an exception is thrown.

time_dependent. If this is a time dependent function, then the last variable declared in vars is assumed to be the time variable, and this->get_time() is used to initialize it when evaluating the function. Naturally the number of variables parsed by the initialize() method in this case is dim+1. The value of this parameter defaults to false, i.e. do not consider time.

use_degrees. Parameter to decide if the trigonometric functions work in radians or degrees. The default for this parameter is false, i.e. use radians and not degrees.

template<int dim>
void FunctionParser< dim >::initialize ( const std::string &  vars,
const std::vector< std::string > &  expressions,
const ConstMap constants,
const ConstMap units,
const bool  time_dependent = false,
const bool  use_degrees = false 
)

Initialize the function. Same as above, but with an additional argument units - a map of units passed to FunctionParser via AddUnint.

Can be used as "3cm". Have higher precedence in parsing, i.e. if cm=10 then 3/2cm is 3 /(2*10). See contrib/functionparser/fparser.txt for more details.

template<int dim>
void FunctionParser< dim >::initialize ( const std::string &  vars,
const std::string &  expression,
const ConstMap constants,
const bool  time_dependent = false,
const bool  use_degrees = false 
)

Initialize the function. Same as above, but accepts a string rather than a vector of strings. If this is a vector valued function, its componenents are expected to be separated by a semicolon. An exception is thrown if this method is called and the number of components successfully parsed does not match the number of components of the base function.

template<int dim>
void FunctionParser< dim >::initialize ( const std::string &  vars,
const std::string &  expression,
const ConstMap constants,
const ConstMap units,
const bool  time_dependent = false,
const bool  use_degrees = false 
)

Initialize the function. Same as above, but with units.

template<int dim>
std::string FunctionParser< dim >::default_variable_names ( )
static

A function that returns default names for variables, to be used in the first argument of the initialize() functions: it returns "x" in 1d, "x,y" in 2d, and "x,y,z" in 3d.

Definition at line 575 of file function_parser.h.

template<int dim>
virtual double FunctionParser< dim >::value ( const Point< dim > &  p,
const unsigned int  component = 0 
) const
virtual

Return the value of the function at the given point. Unless there is only one component (i.e. the function is scalar), you should state the component you want to have evaluated; it defaults to zero, i.e. the first component.

Reimplemented from Function< dim >.

template<int dim>
virtual void FunctionParser< dim >::vector_value ( const Point< dim > &  p,
Vector< double > &  values 
) const
virtual

Return all components of a vector-valued function at the given point p.

values shall have the right size beforehand, i.e. n_components.

Reimplemented from Function< dim >.

Member Data Documentation

template<int dim>
fparser::FunctionParser* FunctionParser< dim >::fp
private

A pointer to the actual function parsers. The pointer is to an array of parsers, not just a single one. The length of the array equals the number of vector components.

Definition at line 544 of file function_parser.h.

template<int dim>
bool FunctionParser< dim >::initialized
private

State of usability. This variable is checked every time the function is called for evaluation. It's set to true in the initialize() methods.

Definition at line 553 of file function_parser.h.

template<int dim>
unsigned int FunctionParser< dim >::n_vars
private

Number of variables. If this is also a function of time, then the number of variables is dim+1, otherwhise it is dim. In the case that this is a time dependent function, the time is supposed to be the last variable. If n_vars is not identical to the number of the variables parsed by the initialize() method, then an exception is thrown.

Definition at line 569 of file function_parser.h.


The documentation for this class was generated from the following file: