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 75 of file Interpreter.h.

Constructor & Destructor Documentation

◆ Interpreter() [1/2]

Nektar::LibUtilities::Interpreter::Interpreter ( )

Default constructor.

Definition at line 2179 of file Interpreter/Interpreter.cpp.

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

References m_impl.

◆ ~Interpreter()

Nektar::LibUtilities::Interpreter::~Interpreter ( )

Default destructor.

Definition at line 2184 of file Interpreter/Interpreter.cpp.

2185{

2186}

◆ Interpreter() [2/2]

Nektar::LibUtilities::Interpreter::Interpreter ( Interpreter && r )

Default move constructor.

Definition at line 2188 of file Interpreter/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 2209 of file Interpreter/Interpreter.cpp.

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

References m_impl, and CellMLToNektar.pycml::name.

◆ 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 2203 of file Interpreter/Interpreter.cpp.

{
    m_impl->AddConstants(constants);
}

References m_impl.

Referenced by Interpreter_AddConstants().

◆ 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 2239 of file Interpreter/Interpreter.cpp.

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

References m_impl.

Referenced by Nektar::InterpreterUnitTests::BOOST_AUTO_TEST_CASE(), Nektar::MultiRegions::DisContField::FindPeriodicTraces(), Replacevertices(), Nektar::FieldUtils::ProcessFieldFromString::v_Process(), Nektar::FieldUtils::ProcessIsoContour::v_Process(), Nektar::SpatialDomains::MeshGraphIOXml::v_ReadCurves(), Nektar::SpatialDomains::MeshGraphIOXmlCompressed::v_ReadCurves(), Nektar::SpatialDomains::MeshGraphIOXml::v_ReadVertices(), and Nektar::SpatialDomains::MeshGraphIOXmlCompressed::v_ReadVertices().

◆ Evaluate() [1/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.

Definition at line 2273 of file Interpreter/Interpreter.cpp.

{
    m_impl->Evaluate(expression_id, points, result);
}

References m_impl.

◆ Evaluate() [2/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 2245 of file Interpreter/Interpreter.cpp.

{
    return m_impl->Evaluate(AnalyticExpression_id);
}

References m_impl.

Referenced by Nektar::InterpreterUnitTests::BOOST_AUTO_TEST_CASE(), Nektar::MultiRegions::DisContField::FindPeriodicTraces(), Replacevertices(), Nektar::FieldUtils::ProcessFieldFromString::v_Process(), Nektar::FieldUtils::ProcessIsoContour::v_Process(), Nektar::SpatialDomains::MeshGraphIOXml::v_ReadCurves(), Nektar::SpatialDomains::MeshGraphIOXmlCompressed::v_ReadCurves(), Nektar::SpatialDomains::MeshGraphIOXml::v_ReadVertices(), and Nektar::SpatialDomains::MeshGraphIOXmlCompressed::v_ReadVertices().

◆ 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 2263 of file Interpreter/Interpreter.cpp.

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

References m_impl, and Nektar::UnitTests::z().

◆ Evaluate() [4/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 \( y \)).
z	The value of variable 3 (typically \( z \)).
t	The value of variable 4 (typically \( t \)).

Definition at line 2250 of file Interpreter/Interpreter.cpp.

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

References m_impl, and Nektar::UnitTests::z().

◆ 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 2257 of file Interpreter/Interpreter.cpp.

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

References m_impl.

◆ 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 2214 of file Interpreter/Interpreter.cpp.

{
    return m_impl->GetConstant(name);
}

References m_impl, and CellMLToNektar.pycml::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 2229 of file Interpreter/Interpreter.cpp.

{
    return m_impl->GetParameter(name);
}

References m_impl, and CellMLToNektar.pycml::name.

◆ GetTime()

NekDouble Nektar::LibUtilities::Interpreter::GetTime ( ) const

Returns the total walltime spent in evaluation procedures in seconds.

Definition at line 2234 of file Interpreter/Interpreter.cpp.

{
    return m_impl->GetTime();
}

References m_impl.

◆ operator=()

Interpreter & Nektar::LibUtilities::Interpreter::operator= ( Interpreter && r )

Default assignment operator.

Definition at line 2192 of file Interpreter/Interpreter.cpp.

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

References m_impl.

◆ 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 2224 of file Interpreter/Interpreter.cpp.

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

References m_impl, and CellMLToNektar.pycml::name.

◆ 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 2219 of file Interpreter/Interpreter.cpp.

{
    m_impl->SetParameters(params);
}

References m_impl.

Referenced by Interpreter_SetParameters().

◆ 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 2198 of file Interpreter/Interpreter.cpp.

{
    m_impl->SetRandomSeed(seed);
}

References m_impl.

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 319 of file Interpreter.h.

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

Classes

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Interpreter() [1/2]

◆ ~Interpreter()

◆ Interpreter() [2/2]

Member Function Documentation

◆ AddConstant()

◆ AddConstants()

◆ DefineFunction()

◆ Evaluate() [1/4]

◆ Evaluate() [2/4]

◆ Evaluate() [3/4]

◆ Evaluate() [4/4]

◆ EvaluateAtPoint()

◆ GetConstant()

◆ GetParameter()

◆ GetTime()

◆ operator=()

◆ SetParameter()

◆ SetParameters()

◆ SetRandomSeed()

Member Data Documentation

◆ m_impl