Nektar::LibUtilities::Interpreter Class Reference

Interpreter class for the evaluation of mathematical expressions. More...

#include <Interpreter.h>

Classes
class	ExpressionEvaluator
	Concrete implementation of the interface defined in Interpreter. More...

Public Member Functions
	Interpreter ()
	Default constructor. More...
	~Interpreter ()
	Default destructor. More...
	Interpreter (Interpreter &&)
	Default move constructor. More...
Interpreter &	operator= (Interpreter &&)
	Default assignment operator. More...
void	SetRandomSeed (unsigned int seed=123u)
	Sets the random seed for the pseudorandom number generator. More...
void	AddConstants (std::map< std::string, NekDouble > const &constants)
	Set constants to be evaluated. More...
int	AddConstant (std::string const &name, NekDouble value)
	Set constants to be evaluated. More...
NekDouble	GetConstant (std::string const &name)
	Return the value of a constant. More...
void	SetParameters (std::map< std::string, NekDouble > const &params)
	Set parameter values. More...
void	SetParameter (std::string const &name, NekDouble value)
	Set parameter values. More...
NekDouble	GetParameter (std::string const &name)
	Get the value of a parameter. More...
NekDouble	GetTime () const
	Returns the total walltime spent in evaluation procedures in seconds. More...
int	DefineFunction (const std::string &vlist, const std::string &expr)
	Defines a function for the purposes of evaluation. More...
NekDouble	Evaluate (const int id)
	Evaluate a function which depends only on constants and/or parameters. More...
NekDouble	Evaluate (const int id, const NekDouble x, const NekDouble y, const NekDouble z, const NekDouble t)
	Evaluate a function which depends on four variables: typically space \( (x, y, z) \) and time \( t\). More...
NekDouble	EvaluateAtPoint (const int id, std::vector< NekDouble > point)
	Evaluate a function which depends on zero or more variables. More...
void	Evaluate (const int id, const Array< OneD, const NekDouble > &x, const Array< OneD, const NekDouble > &y, const Array< OneD, const NekDouble > &z, const Array< OneD, const NekDouble > &t, Array< OneD, NekDouble > &result)
	Evaluate a function which depends on four variables: typically space \( (x, y, z) \) and time \( t\) in a vectorised manner. More...
void	Evaluate (const int expression_id, const std::vector< Array< OneD, const NekDouble > > &points, Array< OneD, NekDouble > &result)
	Evaluate a function which depends on zero or more variables. More...

Private Attributes
std::unique_ptr< ExpressionEvaluator >	m_impl
	Concrete implementation of the above API calls. More...

Detailed Description

Interpreter class for the evaluation of mathematical expressions.

The Interpreter class uses the boost::spirit parser framework in order to construct a simple grammar for the evaluation of mathematical expressions. Primarily this is used within LibUtilities::SessionReader to evaluate functions defined using strings, but can be used generically anywhere within the framework in order to provide parsing functionality.

The interpreter supports:

• classical mathematical binary operators of addition +, subtraction -, multiplication *, division / and exponentiation ^, evaluated in the appropriate manner and with use of parentheses;
• logical operators &&, ||, ==, <= and >=;
• several predefined constants such as PI and other related constants from the cmath header assigned by the AddConstant function;
• various mathematical functions including trigonometric functions (sin, cos, etc), pow, log and exp;
• noise generation with the awgn function;
• the evaluation of spatially-constant parameters, controlled by the SetParameters function;
• support for either single-value or multiple-value variables, in order to e.g. support the evaluation of spatially-variable expressions.

Note that this class exposes the interface of the Interpreter class only in order to reduce compile-time includes. The implementation itself can be found in Interpreter::ExpressionEvaluator.

Definition at line 77 of file Interpreter.h.

Constructor & Destructor Documentation

Interpreter() [1/2]

Nektar::LibUtilities::Interpreter::Interpreter

(

)

Default constructor.

Definition at line 2012 of file Interpreter.cpp.

{
    m_impl = std::unique_ptr<ExpressionEvaluator>(new ExpressionEvaluator());
}

~Interpreter()

Nektar::LibUtilities::Interpreter::~Interpreter

(

)

Default destructor.

Definition at line 2017 of file Interpreter.cpp.

{
}

Interpreter() [2/2]

Nektar::LibUtilities::Interpreter::Interpreter

(

Interpreter &&

r

)

Default move constructor.

Definition at line 2021 of file Interpreter.cpp.

                                        : m_impl(std::move(r.m_impl))
{
}

Member Function Documentation

AddConstant()

int Nektar::LibUtilities::Interpreter::AddConstant	(	std::string const &	name,
		NekDouble	value
	)

Set constants to be evaluated.

This function behaves in the same way as AddConstants, but it only adds one constant at a time. If the constant existed previously, an exception will be thrown stating the fact. If it did not exist previously, it will be added to the global constants and will be used the next time DefineFunction is called.

Returns

Total number of constants after this one has been added.

Definition at line 2042 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->AddConstant(name, value);
}

AddConstants()

void Nektar::LibUtilities::Interpreter::AddConstants

(

std::map< std::string, NekDouble > const &

constants

)

Set constants to be evaluated.

Constants are evaluated and inserted into the function at the time it is parsed when calling the DefineFunction function. After parsing, if a constant is changed, it will not be reflected in the function when Evaluate is called. This also means that if a function with an unknown constant is added, and then the constant is added, the function will not see the added constant and through an exception.

This function will add all of the constants in the constants parameter to the global internal constants. If a constant was already loaded previously, it will throw an exception stating which constants in the map had this issue. It will add all of the constants it can from constants and output the constants it couldn't add in the string exception.

Parameters

constants

A std::map with string names for the constants (which will be evalauted in the expression) and their NekDouble value.

Definition at line 2036 of file Interpreter.cpp.

References m_impl.

{
    m_impl->AddConstants(constants);
}

DefineFunction()

int Nektar::LibUtilities::Interpreter::DefineFunction	(	const std::string &	vlist,
		const std::string &	expr
	)

Defines a function for the purposes of evaluation.

This function allows one to define a function to evaluate. The vlist argument should define a list of space-separated variables that the expression defined in function is dependent upon. For example, if function is defined as the string x + y, then vlist should most likely be x y, unless you are defining x or y as parameters with the SetParameters function.

Parameters

vlist	List of variable names separated with spaces.
expr	String definition of the function to be evaluated.

Returns

An integer denoting the unique ID of this function. This should be passed into Evaluate functions for later evaluation.

Definition at line 2072 of file Interpreter.cpp.

References m_impl.

Referenced by Nektar::NekMeshUtils::CurveMesh::CurveMesh(), Nektar::MultiRegions::DisContField3D::FindPeriodicFaces(), Nektar::Utilities::ProcessPerAlign::Process(), Nektar::Utilities::OutputNekpp::Process(), Nektar::FieldUtils::ProcessFieldFromString::Process(), Nektar::Utilities::ProcessScalar::Process(), Nektar::NekMeshUtils::Generator2D::Process(), Nektar::SpatialDomains::MeshGraphXmlCompressed::ReadCurves(), Nektar::SpatialDomains::MeshGraphXml::ReadCurves(), Nektar::SpatialDomains::MeshGraphXmlCompressed::ReadVertices(), Nektar::SpatialDomains::MeshGraphXml::ReadVertices(), and Nektar::Utilities::ProcessCurve::v_GenerateEdgeNodes().

{
    return m_impl->DefineFunction(vlist, function);
}

Evaluate() [1/4]

NekDouble Nektar::LibUtilities::Interpreter::Evaluate

(

const int

id

)

Evaluate a function which depends only on constants and/or parameters.

Parameters

id	The ID returned from DefineFunction representing the function to be evaluated.

Definition at line 2078 of file Interpreter.cpp.

References m_impl.

Referenced by Evaluate(), Nektar::Utilities::ProcessCurve::EvaluateCoordinate(), Nektar::MultiRegions::DisContField3D::FindPeriodicFaces(), Nektar::NekMeshUtils::Generator2D::MakeBL(), Nektar::Utilities::ProcessPerAlign::Process(), Nektar::FieldUtils::ProcessFieldFromString::Process(), Nektar::NekMeshUtils::Generator2D::Process(), Nektar::SpatialDomains::MeshGraphXmlCompressed::ReadCurves(), Nektar::SpatialDomains::MeshGraphXml::ReadCurves(), Nektar::SpatialDomains::MeshGraphXmlCompressed::ReadVertices(), Nektar::SpatialDomains::MeshGraphXml::ReadVertices(), and Nektar::Utilities::TestElmts().

{
    return m_impl->Evaluate(AnalyticExpression_id);
}

Evaluate() [2/4]

NekDouble Nektar::LibUtilities::Interpreter::Evaluate	(	const int	id,
		const NekDouble	x,
		const NekDouble	y,
		const NekDouble	z,
		const NekDouble	t
	)

Evaluate a function which depends on four variables: typically space \( (x, y, z) \) and time \( t\).

Parameters

id	The ID returned from DefineFunction representing the function to be evaluated.
x	The value of variable 1 (typically \( x \)).
y	The value of variable 2 (typically \( x \)).
z	The value of variable 3 (typically \( x \)).
t	The value of variable 4 (typically \( x \)).

Definition at line 2083 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->Evaluate(AnalyticExpression_id, x, y, z, t);
}

Evaluate() [3/4]

void Nektar::LibUtilities::Interpreter::Evaluate	(	const int	id,
		const Array< OneD, const NekDouble > &	x,
		const Array< OneD, const NekDouble > &	y,
		const Array< OneD, const NekDouble > &	z,
		const Array< OneD, const NekDouble > &	t,
		Array< OneD, NekDouble > &	result
	)

Evaluate a function which depends on four variables: typically space \( (x, y, z) \) and time \( t\) in a vectorised manner.

This is a vectorised version of the evaluation method that will allow the same function to be evaluated many times for each of the entries in the input variable arrays x, y, z and t. Note that this is typically far quicker than the use of a loop with many calls to the single-variable variants in this class.

Note

All parameters x, y, z and t should be Arrays of the same length.

Parameters

id	The ID returned from DefineFunction representing the function to be evaluated.
x	An Array of values for variable 1 (typically \( x\)).
y	An Array of values for variable 2 (typically \( y\)).
z	An Array of values for variable 3 (typically \( z\)).
t	An Array of values for variable 4 (typically \( t\)).
result	An Array containing the evaluation of the function for each of the variable values.

Definition at line 2096 of file Interpreter.cpp.

References Evaluate(), and m_impl.

{
    m_impl->Evaluate(expression_id, x, y, z, t, result);
}

Evaluate() [4/4]

void Nektar::LibUtilities::Interpreter::Evaluate	(	const int	expression_id,
		const std::vector< Array< OneD, const NekDouble > > &	points,
		Array< OneD, NekDouble > &	result
	)

Evaluate a function which depends on zero or more variables.

This is a vectorised version of the evaluation method that will allow the same function to be evaluated many times for each of the entries in the input variable arrays within points. Note that this is typically far quicker than the use of a loop with many calls to the single-variable variants in this class.

Note

All entries of the input array points should be of the same length.

Parameters

id	The ID returned from DefineFunction representing the function to be evaluated.
points	An Array in which the i-th entry corresponds to values of variable \( i\).
result	An Array containing the evaluation of the function for each of the variable values.

EvaluateAtPoint()

NekDouble Nektar::LibUtilities::Interpreter::EvaluateAtPoint	(	const int	id,
		std::vector< NekDouble >	point
	)

Evaluate a function which depends on zero or more variables.

This is suitable for expressions depending on more than 4 variables or for the dynamic setting of some variables as parameters (there is currently no interface method for removing a variable from parameter map however).

Parameters

id	The ID returned from DefineFunction representing the function to be evaluated.
point	A std::vector of points to be evaluated.

Definition at line 2090 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->EvaluateAtPoint(AnalyticExpression_id, point);
}

GetConstant()

NekDouble Nektar::LibUtilities::Interpreter::GetConstant

(

std::string const &

name

)

Return the value of a constant.

If a constant with the specified name name exists, this function returns the NekDouble value that the constant stores. If the constant doesn't exist, this throws an exception.

Parameters

name	Name of constant to return.

Definition at line 2047 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->GetConstant(name);
}

GetParameter()

NekDouble Nektar::LibUtilities::Interpreter::GetParameter

(

std::string const &

name

)

Get the value of a parameter.

If a parameter with the specified name exists, it returns the NekDouble value that the parameter stores. If the parameter doesn't exist, it throws an exception.

Parameters

name	Name of the parameter to query.

Definition at line 2062 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->GetParameter(name);
}

GetTime()

NekDouble Nektar::LibUtilities::Interpreter::GetTime

(

)

const

Returns the total walltime spent in evaluation procedures in seconds.

Definition at line 2067 of file Interpreter.cpp.

References m_impl.

{
    return m_impl->GetTime();
}

operator=()

Interpreter & Nektar::LibUtilities::Interpreter::operator=

(

Interpreter &&

r

)

Default assignment operator.

Definition at line 2025 of file Interpreter.cpp.

References m_impl.

{
    m_impl = std::move(r.m_impl);
    return *this;
}

SetParameter()

void Nektar::LibUtilities::Interpreter::SetParameter	(	std::string const &	name,
		NekDouble	value
	)

Set parameter values.

This function behaves in the same way as SetParameters, but it only adds one parameter and it does not delete the others. If the parameter name existed previously, it will be overridden and replaced with the new value. If it did not exist previously, it will be added to the current parameters.

Parameters

name	Name of the parameter to define.
value	The parameter's value.

Definition at line 2057 of file Interpreter.cpp.

References m_impl.

{
    m_impl->SetParameter(name, value);
}

SetParameters()

void Nektar::LibUtilities::Interpreter::SetParameters

(

std::map< std::string, NekDouble > const &

params

)

Set parameter values.

Parameters are functionally similar to constants, but they are inserted into the function at the time that Evaluate is called, instead of when the function is parsed. This function can therefore be called at any time, and it will take effect in the next call to Evaluate. This function will delete all of the parameters, and replace all of them with only the ones in the map argument.

Definition at line 2052 of file Interpreter.cpp.

References m_impl.

{
    m_impl->SetParameters(params);
}

SetRandomSeed()

void Nektar::LibUtilities::Interpreter::SetRandomSeed

(

unsigned int

seed = 123u

)

Sets the random seed for the pseudorandom number generator.

This allows for e.g. different ranks to be given different seeds to ensure appropriate entropy in noise generation.

Definition at line 2031 of file Interpreter.cpp.

References m_impl.

{
    m_impl->SetRandomSeed(seed);
}

Member Data Documentation

m_impl

std::unique_ptr<ExpressionEvaluator> Nektar::LibUtilities::Interpreter::m_impl

private

Concrete implementation of the above API calls.

Definition at line 320 of file Interpreter.h.

Referenced by AddConstant(), AddConstants(), DefineFunction(), Evaluate(), EvaluateAtPoint(), GetConstant(), GetParameter(), GetTime(), operator=(), SetParameter(), SetParameters(), and SetRandomSeed().