FunctionParserUtils< is_ad > Class Template Reference

#include <FunctionParserUtils.h>

Inheritance diagram for FunctionParserUtils< is_ad >:

Public Types
typedef GenericSymFunction< is_ad >	SymFunction
	Shorthand for an autodiff function parser object. More...
typedef std::shared_ptr< SymFunction >	SymFunctionPtr
	Shorthand for an smart pointer to an autodiff function parser object. More...

Public Member Functions
	FunctionParserUtils (const InputParameters &parameters)
void	setParserFeatureFlags (SymFunctionPtr &) const
	apply input parameters to internal feature flags of the parser object More...

Static Public Member Functions
static InputParameters	validParams ()

Protected Types
enum	FailureMethod { FailureMethod::nan, FailureMethod::nan_warning, FailureMethod::error, FailureMethod::exception }
	Enum for failure method. More...

Protected Member Functions
GenericReal< is_ad >	evaluate (SymFunctionPtr &, const std::string &object_name="")
	Evaluate FParser object and check EvalError. More...
GenericReal< is_ad >	evaluate (SymFunctionPtr &, const std::vector< GenericReal< is_ad >> &, const std::string &object_name="")
	Evaluate FParser object and check EvalError. More...
void	addFParserConstants (SymFunctionPtr &parser, const std::vector< std::string > &constant_names, const std::vector< std::string > &constant_expressions) const
	add constants (which can be complex expressions) to the parser object More...
virtual void	functionsOptimize (SymFunctionPtr &parsed_function)
	run FPOptimizer on the parsed function More...
void	parsedFunctionSetup (SymFunctionPtr &function, const std::string &expression, const std::string &variables, const std::vector< std::string > &constant_names, const std::vector< std::string > &constant_expressions, const libMesh::Parallel::Communicator &comm) const
	Performs setup steps on a SymFunction. More...
template<>
void	functionsOptimize (SymFunctionPtr &parsed_function)
template<>
void	functionsOptimize (SymFunctionPtr &parsed_function)

Protected Attributes
enum FunctionParserUtils::FailureMethod	_evalerror_behavior
const Real	_quiet_nan
	appropriate not a number value to return More...
std::vector< GenericReal< is_ad > >	_func_params
	Array to stage the parameters passed to the functions when calling Eval. More...
const Real	_epsilon
	fuzzy comparison tolerance More...
bool	_enable_jit
	feature flags More...
bool	_enable_ad_cache
bool	_disable_fpoptimizer
bool	_enable_auto_optimize

Static Protected Attributes
static const char *	_eval_error_msg []
	table of FParser eval error codes More...

Detailed Description

template<bool is_ad = false>
class FunctionParserUtils< is_ad >

Definition at line 54 of file FunctionParserUtils.h.

Member Typedef Documentation

SymFunction

template<bool is_ad = false>

typedef GenericSymFunction<is_ad> FunctionParserUtils< is_ad >::SymFunction

Shorthand for an autodiff function parser object.

Definition at line 62 of file FunctionParserUtils.h.

SymFunctionPtr

template<bool is_ad = false>

typedef std::shared_ptr<SymFunction> FunctionParserUtils< is_ad >::SymFunctionPtr

Shorthand for an smart pointer to an autodiff function parser object.

Definition at line 65 of file FunctionParserUtils.h.

Member Enumeration Documentation

FailureMethod

template<bool is_ad = false>

enum FunctionParserUtils::FailureMethod

strongprotected

Enum for failure method.

Enumerator
nan
nan_warning
error
exception

Definition at line 116 of file FunctionParserUtils.h.

{ nan, nan_warning, error, exception } _evalerror_behavior;

Constructor & Destructor Documentation

FunctionParserUtils()

template<bool is_ad>

FunctionParserUtils< is_ad >::FunctionParserUtils

(

const InputParameters &

parameters

)

Definition at line 59 of file FunctionParserUtils.C.

  : _enable_jit(parameters.isParamValid("enable_jit") && parameters.get<bool>("enable_jit")),
    _enable_ad_cache(parameters.get<bool>("enable_ad_cache")),
    _disable_fpoptimizer(parameters.get<bool>("disable_fpoptimizer")),
    _enable_auto_optimize(parameters.get<bool>("enable_auto_optimize") && !_disable_fpoptimizer),
    _evalerror_behavior(parameters.get<MooseEnum>("evalerror_behavior").getEnum<FailureMethod>()),
    _quiet_nan(std::numeric_limits<Real>::quiet_NaN()),
    _epsilon(parameters.get<Real>("epsilon"))
{
#ifndef LIBMESH_HAVE_FPARSER_JIT
  if (_enable_jit)
  {
    mooseWarning("Tried to enable FParser JIT but libmesh does not have it compiled in.");
    _enable_jit = false;
  }
#endif
}

Member Function Documentation

addFParserConstants()

template<bool is_ad>

void FunctionParserUtils< is_ad >::addFParserConstants ( SymFunctionPtr &  parser, const std::vector< std::string > &  constant_names, const std::vector< std::string > &  constant_expressions  ) const

protected

add constants (which can be complex expressions) to the parser object

Definition at line 151 of file FunctionParserUtils.C.

{
  // check constant vectors
  unsigned int nconst = constant_expressions.size();
  if (nconst != constant_names.size())
    mooseError("The parameter vectors constant_names (size " +
               std::to_string(constant_names.size()) + ") and constant_expressions (size " +
               std::to_string(nconst) + ") must have equal length.");

  // previously evaluated constant_expressions may be used in following constant_expressions
  std::vector<Real> constant_values(nconst);

  for (unsigned int i = 0; i < nconst; ++i)
  {
    // no need to use dual numbers for the constant expressions
    auto expression = std::make_shared<FunctionParserADBase<Real>>();

    // add previously evaluated constants
    for (unsigned int j = 0; j < i; ++j)
      if (!expression->AddConstant(constant_names[j], constant_values[j]))
        mooseError("Invalid constant name: ", constant_names[j], " and value ", constant_values[j]);

    // build the temporary constant expression function
    if (expression->Parse(constant_expressions[i], "") >= 0)
      mooseError("Invalid constant expression\n",
                 constant_expressions[i],
                 "\n in parsed function object.\n",
                 expression->ErrorMsg());

    constant_values[i] = expression->Eval(NULL);

    if (!parser->AddConstant(constant_names[i], constant_values[i]))
      mooseError("Invalid constant name in parsed function object");
  }
}

evaluate() [1/2]

template<bool is_ad>

GenericReal< is_ad > FunctionParserUtils< is_ad >::evaluate ( SymFunctionPtr &  parser, const std::string &  object_name = ""  )

protected

Evaluate FParser object and check EvalError.

Definition at line 87 of file FunctionParserUtils.C.

Referenced by ParsedFunctorMaterialTempl< is_ad >::ParsedFunctorMaterialTempl().

{
  return evaluate(parser, _func_params, name);
}

evaluate() [2/2]

template<bool is_ad>

GenericReal< is_ad > FunctionParserUtils< is_ad >::evaluate ( SymFunctionPtr &  parser, const std::vector< GenericReal< is_ad >> &  func_params, const std::string &  object_name = ""  )

protected

Evaluate FParser object and check EvalError.

This version uses a supplied vector of function parameters, which is useful if an object uses more than one parsed function, which may have different function parameter values.

Definition at line 94 of file FunctionParserUtils.C.

{
  // null pointer is a shortcut for vanishing derivatives, see functionsOptimize()
  if (parser == NULL)
    return 0.0;

  // set desired epsilon
  auto tmp_eps = parser->epsilon();
  parser->setEpsilon(_epsilon);

  // evaluate expression
  auto result = parser->Eval(func_params.data());

  // restore epsilon
  parser->setEpsilon(tmp_eps);

  // fetch fparser evaluation error (set to unknown if the JIT result is nan)
  int error_code = _enable_jit ? (std::isnan(result) ? -1 : 0) : parser->EvalError();

  // no error
  if (error_code == 0)
    return result;

  // hard fail or return not a number
  switch (_evalerror_behavior)
  {
    case FailureMethod::nan:
      return _quiet_nan;

    case FailureMethod::nan_warning:
      mooseWarning("In ",
                   name,
                   ": Parsed function evaluation encountered an error: ",
                   _eval_error_msg[(error_code < 0 || error_code > 5) ? 0 : error_code]);
      return _quiet_nan;

    case FailureMethod::error:
      mooseError("In ",
                 name,
                 ": Parsed function evaluation encountered an error: ",
                 _eval_error_msg[(error_code < 0 || error_code > 5) ? 0 : error_code]);

    case FailureMethod::exception:
      mooseException("In ",
                     name,
                     ": Parsed function evaluation encountered an error: ",
                     _eval_error_msg[(error_code < 0 || error_code > 5) ? 0 : error_code],
                     "\n Cutting timestep");
  }

  return _quiet_nan;
}

functionsOptimize() [1/3]

template<bool is_ad = false>

virtual void FunctionParserUtils< is_ad >::functionsOptimize ( SymFunctionPtr &  parsed_function )

protectedvirtual

run FPOptimizer on the parsed function

Referenced by DerivativeParsedMaterialHelperTempl< is_ad >::functionsPostParse().

functionsOptimize() [2/3]

template<>

void FunctionParserUtils< true >::functionsOptimize ( SymFunctionPtr &  parsed_function )

protected

functionsOptimize() [3/3]

template<>

void FunctionParserUtils< true >::functionsOptimize ( SymFunctionPtr &  parsed_function )

protected

Definition at line 209 of file FunctionParserUtils.C.

{
  // set desired epsilon for optimization!
  auto tmp_eps = parsed_function->epsilon();
  parsed_function->setEpsilon(_epsilon);

  // base function
  if (!_disable_fpoptimizer)
    parsed_function->Optimize();
  if (!_enable_jit || !parsed_function->JITCompile())
    mooseError("AD parsed objects require JIT compilation to be enabled and working.");

  parsed_function->setEpsilon(tmp_eps);
}

parsedFunctionSetup()

template<bool is_ad>

void FunctionParserUtils< is_ad >::parsedFunctionSetup ( SymFunctionPtr &  function, const std::string &  expression, const std::string &  variables, const std::vector< std::string > &  constant_names, const std::vector< std::string > &  constant_expressions, const libMesh::Parallel::Communicator &  comm  ) const

protected

Performs setup steps on a SymFunction.

Parameters

function	reference to pointer to the function to set up
expression	expression to parse
variables	comma separated string holding all the variables of the expression
constant_names	vector of names (symbols) of constants in the expression
constant_expressions	vectors of expressions (=values) of constants in the expression
comm	communicator used to stagger JIT file creations

Definition at line 226 of file FunctionParserUtils.C.

{
  // set FParser internal feature flags
  setParserFeatureFlags(function);

  // add the constant expressions
  addFParserConstants(function, constant_names, constant_expressions);

  // parse function
  if (function->Parse(expression, variables) >= 0)
    mooseError("Invalid function\n", expression, "\nError:\n", function->ErrorMsg());

  // optimize
  if (!_disable_fpoptimizer)
    function->Optimize();

  // just-in-time compile
  if (_enable_jit)
  {
    // let rank 0 do the JIT compilation first
    if (comm.rank() != 0)
      comm.barrier();

    function->JITCompile();

    // wait for ranks > 0 to catch up
    if (comm.rank() == 0)
      comm.barrier();
  }
}

setParserFeatureFlags()

template<bool is_ad>

void FunctionParserUtils< is_ad >::setParserFeatureFlags

(

SymFunctionPtr &

parser

)

const

apply input parameters to internal feature flags of the parser object

Definition at line 79 of file FunctionParserUtils.C.

{
  parser->SetADFlags(SymFunction::ADCacheDerivatives, _enable_ad_cache);
  parser->SetADFlags(SymFunction::ADAutoOptimize, _enable_auto_optimize);
}

validParams()

template<bool is_ad>

InputParameters FunctionParserUtils< is_ad >::validParams ( )

static

Definition at line 18 of file FunctionParserUtils.C.

Referenced by ArrayParsedAux::validParams(), ParsedAux::validParams(), ParsedPostprocessor::validParams(), ParsedODEKernel::validParams(), ParsedVectorAux::validParams(), ParsedSubdomainGeneratorBase::validParams(), ParsedCurveGenerator::validParams(), ParsedFunctorMaterialTempl< is_ad >::validParams(), ParsedExtraElementIDGenerator::validParams(), ParsedGenerateNodeset::validParams(), ParsedConvergence::validParams(), SolutionUserObject::validParams(), ParsedNodeTransformGenerator::validParams(), CutMeshByLevelSetGeneratorBase::validParams(), ParsedGenerateSideset::validParams(), TransfiniteMeshGenerator::validParams(), ParsedDownSelectionPositions::validParams(), ParsedElementDeletionGenerator::validParams(), and ParsedMaterialHelper< is_ad >::validParams().

{
  InputParameters params = emptyInputParameters();

  params.addParam<bool>(
      "enable_jit",
#ifdef LIBMESH_HAVE_FPARSER_JIT
      true,
#else
      false,
#endif
      "Enable just-in-time compilation of function expressions for faster evaluation");
  params.addParam<bool>(
      "enable_ad_cache", true, "Enable caching of function derivatives for faster startup time");
  params.addParam<bool>(
      "enable_auto_optimize", true, "Enable automatic immediate optimization of derivatives");
  params.addParam<bool>(
      "disable_fpoptimizer", false, "Disable the function parser algebraic optimizer");
  MooseEnum evalerror("nan nan_warning error exception", "nan");
  params.addParam<MooseEnum>("evalerror_behavior",
                             evalerror,
                             "What to do if evaluation error occurs. Options are to pass a nan, "
                             "pass a nan with a warning, throw a error, or throw an exception");

  params.addParamNamesToGroup(
      "enable_jit enable_ad_cache enable_auto_optimize disable_fpoptimizer evalerror_behavior",
      "Parsed expression advanced");
  params.addParam<Real>("epsilon", 0, "Fuzzy comparison tolerance");
  return params;
}

Member Data Documentation

_disable_fpoptimizer

template<bool is_ad = false>

bool FunctionParserUtils< is_ad >::_disable_fpoptimizer

protected

Definition at line 111 of file FunctionParserUtils.h.

_enable_ad_cache

template<bool is_ad = false>

bool FunctionParserUtils< is_ad >::_enable_ad_cache

protected

Definition at line 110 of file FunctionParserUtils.h.

_enable_auto_optimize

template<bool is_ad = false>

bool FunctionParserUtils< is_ad >::_enable_auto_optimize

protected

Definition at line 112 of file FunctionParserUtils.h.

_enable_jit

template<bool is_ad = false>

bool FunctionParserUtils< is_ad >::_enable_jit

protected

feature flags

Definition at line 109 of file FunctionParserUtils.h.

Referenced by FunctionParserUtils< false >::FunctionParserUtils().

_epsilon

template<bool is_ad = false>

const Real FunctionParserUtils< is_ad >::_epsilon

protected

fuzzy comparison tolerance

Definition at line 128 of file FunctionParserUtils.h.

_eval_error_msg

template<bool is_ad = false>

const char * FunctionParserUtils< is_ad >::_eval_error_msg

staticprotected

Initial value:

= {
    "Unknown",
    "Division by zero",
    "Square root of a negative value",
    "Logarithm of negative value",
    "Trigonometric error (asin or acos of illegal value)",
    "Maximum recursion level reached"}

table of FParser eval error codes

Definition at line 122 of file FunctionParserUtils.h.

_evalerror_behavior

template<bool is_ad = false>

enum FunctionParserUtils::FailureMethod FunctionParserUtils< is_ad >::_evalerror_behavior

protected

_func_params

template<bool is_ad = false>

std::vector<GenericReal<is_ad> > FunctionParserUtils< is_ad >::_func_params

protected

Array to stage the parameters passed to the functions when calling Eval.

Definition at line 125 of file FunctionParserUtils.h.

Referenced by ParsedFunctorMaterialTempl< is_ad >::ParsedFunctorMaterialTempl().

_quiet_nan

template<bool is_ad = false>

const Real FunctionParserUtils< is_ad >::_quiet_nan

protected

appropriate not a number value to return

Definition at line 119 of file FunctionParserUtils.h.

---

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

• include/utils/FunctionParserUtils.h
• src/utils/FunctionParserUtils.C