Classes | |
class | ExcInvalidExpressionSize |
class | ExcParseError |
Public Types | |
typedef std::map< std::string, double > | ConstMap |
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 |
Static Public Member Functions | |
static std::string | default_variable_names () |
Private Attributes | |
fparser::FunctionParser * | fp |
bool | initialized |
unsigned int | n_vars |
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> 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 can 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 exptra 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>. 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 5/2 inches is what one wants, it has to be written "(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.
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 for you 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 call the initialize() method first, 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 betwen -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 FunctionParser<2> 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);
typedef std::map<std::string, double> FunctionParser< dim >::ConstMap |
Type for the constant map. Used by the initialize() method.
typedef ConstMap::iterator FunctionParser< dim >::ConstMapIterator |
Iterator for the constants map. Used by the initialize() method.
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.
FunctionParser< dim >::~FunctionParser | ( | ) |
Destructor. Explicitly delete the FunctionParser objects (there is one for each component of the function).
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.
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.
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.
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.
std::string FunctionParser< dim >::default_variable_names | ( | ) | [inline, 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.
References Assert.
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 >.
virtual void FunctionParser< dim >::vector_value | ( | const Point< dim > & | p, | |
Vector< double > & | values | |||
) | const [virtual] |
Return all components of a vector-valued function at a given point.
values
shall have the right size beforehand, i.e. n_components.
Reimplemented from Function< dim >.
fparser::FunctionParser* FunctionParser< dim >::fp [private] |
A pointer to the actual function parsers.
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.
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.