Shared code for the Capabilities Registry and the python bindings to the Capabilities system. More...

Classes
class	CapabilityException

Typedefs
typedef std::variant< bool, int, std::string >	Type
	A capability can have a bool, int, or string value. More...

typedef std::tuple< CheckState, std::string, std::string >	Result
	Result from a capability check: the state, the reason, and the documentation. More...

typedef std::map< std::string, std::pair< Type, std::string > >	Registry
	The registry that stores the registered capabilities. More...

Enumerations
enum	CheckState { CERTAIN_FAIL = 0, POSSIBLE_FAIL = 1, UNKNOWN = 2, POSSIBLE_PASS = 3, CERTAIN_PASS = 4, PARSE_FAIL = 5 }
	Return state for check. More...

Functions
Result	check (std::string requirements, const Registry &capabilities)
	Checks if a set of requirements is satisified by the given capability registry. More...

Detailed Description

Shared code for the Capabilities Registry and the python bindings to the Capabilities system.

Typedef Documentation

◆ Registry

typedef std::map<std::string, std::pair<Type, std::string> > CapabilityUtils::Registry

The registry that stores the registered capabilities.

Definition at line 79 of file CapabilityUtils.h.

◆ Result

typedef std::tuple<CheckState, std::string, std::string> CapabilityUtils::Result

Result from a capability check: the state, the reason, and the documentation.

Definition at line 77 of file CapabilityUtils.h.

◆ Type

typedef std::variant<bool, int, std::string> CapabilityUtils::Type

A capability can have a bool, int, or string value.

Definition at line 75 of file CapabilityUtils.h.

Enumeration Type Documentation

◆ CheckState

enum CapabilityUtils::CheckState

Return state for check.

We use a plain enum because we rely on implicit conversion to int. Capability checks are run in the test harness using the JSON dump exported from the executable using --show-capabilities. This static check does not take dynamic loading into account, as capabilities that would be registered after initializing the dynamically loaded application will not exist with --show-capabilities.

A requested capability that is not registered at all is considered in a "possible" state, as we cannot guarantee that it does or not exist with a dynamic application. If no dynamic application loading is used, the possible states can be considered certain states.

When the test harness Tester specification "dynamic_capabilities" is set to True, it will run the test unless the result of the check is CERTAIN_FAIL. In this case, the runtime check in the executable will terminate if the result is either CERTAIN_FAIL or POSSIBLE_FAIL.

Enumerator
CERTAIN_FAIL
POSSIBLE_FAIL
UNKNOWN
POSSIBLE_PASS
CERTAIN_PASS
PARSE_FAIL

Definition at line 64 of file CapabilityUtils.h.

 {
   CERTAIN_FAIL = 0,
   POSSIBLE_FAIL = 1,
   UNKNOWN = 2,
   POSSIBLE_PASS = 3,
   CERTAIN_PASS = 4,
   PARSE_FAIL = 5
 };

Function Documentation

◆ check()

Result CapabilityUtils::check	(	std::string	requirements,
		const Registry &	capabilities
	)

Checks if a set of requirements is satisified by the given capability registry.

Parameters

requirements	The requirement string
capabilities	The registry that contains the capabilities

This method is exposed to Python within the capabilities_check method in framework/contrib/capabilities/capabilities.C. This external method is used significantly by the TestHarness to check capabilities for individual test specs.

Additionally, this method is used by the MooseApp command line option "--required-capabilities ...".

Requirements can use comparison operators (>,<,>=,<=,=!,=), where the name of the capability must always be on the left hand side. Comparisons can be performed on strings "compiler!=GCC" (which are case insensitive), integer numbers "ad_size>=50", and version numbers "petsc>3.8.0". The state of a boolean valued capability can be tested by just specifying the capability name "chaco". This check can be inverted using the ! operator as "!chaco".

The logic operators & and | can be used to chain multiple checks as "thermochimica & thermochimica>1.0". Parenthesis can be used to build complex logic expressions.

See the description for CheckState for more information on why a certain state would be returned.

Definition at line 20 of file CapabilityUtils.C.

Referenced by CommandLine::buildHitParams(), Moose::Capabilities::check(), BoundaryNodeIntegrityCheckThread::onNode(), and BoundaryElemIntegrityCheckThread::operator()().

 {
   using namespace peg;
 
   // unquote
   while (true)
   {
     const auto len = requirements.length();
     if (len >= 2 && ((requirements[0] == '\'' && requirements[len - 1] == '\'') ||
                      (requirements[0] == '"' && requirements[len - 1] == '"')))
       requirements = requirements.substr(1, len - 2);
     else
       break;
   }
   if (requirements.length() == 0)
     return {CapabilityUtils::CERTAIN_PASS, "Empty requirements", ""};
 
   parser parser(R"(
     Expression    <-  _ Bool _ LogicOperator _ Expression / Bool _
     Bool          <-  Comparison / '!' Bool / '!' Identifier / Identifier / '(' _ Expression _ ')'
     Comparison    <-  Identifier _ Operator _ Version / Identifier _ Operator _ String
     String        <-  [a-zA-Z0-9_-]+
     Identifier    <-  [a-zA-Z][a-zA-Z0-9_]*
     Operator      <-  [<>=!]+
     LogicOperator <-  [&|]
     Version       <-  Number '.' Version  / Number
     Number        <-  [0-9]+
     ~_            <-  [ \t]*
   )");
 
   if (!static_cast<bool>(parser))
     throw CapabilityException("Capabilities parser build failure.");
 
   parser["Number"] = [](const SemanticValues & vs) { return vs.token_to_number<int>(); };
 
   parser["Version"] = [](const SemanticValues & vs)
   {
     switch (vs.choice())
     {
       case 0: // Number '.' Version
       {
         std::vector<int> ret{std::any_cast<int>(vs[0])};
         const auto & vs1 = std::any_cast<std::vector<int>>(vs[1]);
         ret.insert(ret.end(), vs1.begin(), vs1.end());
         return ret;
       }
 
       case 1: // Number
         return std::vector<int>{std::any_cast<int>(vs[0])};
 
       default:
         throw CapabilityException("Unknown Number match");
     }
   };
 
   enum LogicOperator
   {
     OP_AND,
     OP_OR
   };
 
   parser["LogicOperator"] = [](const SemanticValues & vs)
   {
     const auto op = vs.token();
     if (op == "&")
       return OP_AND;
     if (op == "|")
       return OP_OR;
     throw CapabilityException("Unknown logic operator.");
   };
 
   enum Operator
   {
     OP_LESS_EQ,
     OP_GREATER_EQ,
     OP_LESS,
     OP_GREATER,
     OP_NOT_EQ,
     OP_EQ
   };
 
   parser["Operator"] = [](const SemanticValues & vs)
   {
     const auto op = vs.token();
     if (op == "<=")
       return OP_LESS_EQ;
     if (op == ">=")
       return OP_GREATER_EQ;
     if (op == "<")
       return OP_LESS;
     if (op == ">")
       return OP_GREATER;
     if (op == "!=")
       return OP_NOT_EQ;
     if (op == "=" || op == "==")
       return OP_EQ;
     throw CapabilityException("Unknown operator '", op, "'.");
   };
 
   parser["String"] = [](const SemanticValues & vs) { return vs.token_to_string(); };
   parser["Identifier"] = [](const SemanticValues & vs) { return vs.token_to_string(); };
 
   parser["Comparison"] = [&app_capabilities](const SemanticValues & vs)
   {
     const auto left = std::any_cast<std::string>(vs[0]);
     const auto op = std::any_cast<Operator>(vs[1]);
 
     // check existence
     const auto it = app_capabilities.find(left);
     if (it == app_capabilities.end())
       // return an unknown if the capability does not exist, this is important as it
       // stays unknown upon negation
       return CheckState::UNKNOWN;
 
     // capability is registered by the app
     const auto & [app_value, doc] = it->second;
 
     // explicitly false causes any comparison to fail
     if (std::holds_alternative<bool>(app_value) && std::get<bool>(app_value) == false)
       return CheckState::CERTAIN_FAIL;
 
     // comparator
     auto comp = [](int i, auto a, auto b)
     {
       switch (i)
       {
         case OP_LESS_EQ:
           return a <= b;
         case OP_GREATER_EQ:
           return a >= b;
         case OP_LESS:
           return a < b;
         case OP_GREATER:
           return a > b;
         case OP_NOT_EQ:
           return a != b;
         case OP_EQ:
           return a == b;
       }
       return false;
     };
 
     switch (vs.choice())
     {
       case 0: // Identifier _ Operator _ Version
       {
         // int comparison
         const auto right = std::any_cast<std::vector<int>>(vs[2]);
         if (std::holds_alternative<int>(app_value))
         {
           if (right.size() != 1)
             throw CapabilityException("Expected an integer value in comparison");
 
           return comp(op, std::get<int>(app_value), right[0]) ? CheckState::CERTAIN_PASS
                                                               : CheckState::CERTAIN_FAIL;
         }
 
         // version comparison
         std::vector<int> app_value_version;
 
         if (!std::holds_alternative<std::string>(app_value))
           throw CapabilityException(
               right.size() == 1 ? "Cannot compare capability " + left + " to a number."
                                 : "Cannot compare capability " + left + " to a version number.");
 
         if (!MooseUtils::tokenizeAndConvert(
                 std::get<std::string>(app_value), app_value_version, "."))
           throw CapabilityException("Expected a version number.");
 
         // compare versions
         return comp(op, app_value_version, right) ? CheckState::CERTAIN_PASS
                                                   : CheckState::CERTAIN_FAIL;
       }
 
       case 1: // Identifier _ Operator _ String
       {
         const auto right = std::any_cast<std::string>(vs[2]);
         // the app value has to be a string
         if (!std::holds_alternative<std::string>(app_value))
           throw CapabilityException("Unexpected comparison to a string.");
 
         return comp(op, std::get<std::string>(app_value), MooseUtils::toLower(right))
                    ? CheckState::CERTAIN_PASS
                    : CheckState::CERTAIN_FAIL;
       }
     }
 
     throw CapabilityException("Failed comparison.");
   };
 
   parser["Bool"] = [&app_capabilities](const SemanticValues & vs)
   {
     switch (vs.choice())
     {
       case 0: // Comparison
       case 4: // '(' _ Expression _ ')'
         return std::any_cast<CheckState>(vs[0]);
 
       case 1: // '!' Bool
         switch (std::any_cast<CheckState>(vs[0]))
         {
           case CheckState::CERTAIN_FAIL:
             return CheckState::CERTAIN_PASS;
           case CheckState::CERTAIN_PASS:
             return CheckState::CERTAIN_FAIL;
           case CheckState::POSSIBLE_FAIL:
             return CheckState::POSSIBLE_PASS;
           case CheckState::POSSIBLE_PASS:
             return CheckState::POSSIBLE_FAIL;
           default:
             return CheckState::UNKNOWN;
         }
 
       case 2: // '!' Identifier
       {
         const auto it = app_capabilities.find(std::any_cast<std::string>(vs[0]));
         if (it != app_capabilities.end())
         {
           const auto app_value = it->second.first;
           if (std::holds_alternative<bool>(app_value) && std::get<bool>(app_value) == false)
             return CheckState::CERTAIN_PASS;
           return CheckState::CERTAIN_FAIL;
         }
         return CheckState::POSSIBLE_PASS;
       }
 
       case 3: // Identifier
       {
         const auto it = app_capabilities.find(std::any_cast<std::string>(vs[0]));
         if (it != app_capabilities.end())
         {
           const auto app_value = it->second.first;
           if (std::holds_alternative<bool>(app_value) && std::get<bool>(app_value) == false)
             return CheckState::CERTAIN_FAIL;
           return CheckState::CERTAIN_PASS;
         }
         return CheckState::POSSIBLE_FAIL;
       }
 
       default:
         throw CapabilityException("Unknown choice in Bool non-terminal");
     }
   };
 
   parser["Expression"] = [](const SemanticValues & vs)
   {
     switch (vs.choice())
     {
       case 0: // Bool _ LogicOperator _ Expression
       {
         const auto left = std::any_cast<CheckState>(vs[0]);
         const auto op = std::any_cast<LogicOperator>(vs[1]);
         const auto right = std::any_cast<CheckState>(vs[2]);
 
         switch (op)
         {
           case OP_AND:
             for (const auto state : {CheckState::CERTAIN_FAIL,
                                      CheckState::POSSIBLE_FAIL,
                                      CheckState::UNKNOWN,
                                      CheckState::POSSIBLE_PASS,
                                      CheckState::CERTAIN_PASS})
               if (left == state || right == state)
                 return state;
             throw CapabilityException("Conjunction failure");
 
           case OP_OR:
             for (const auto state : {CheckState::CERTAIN_PASS,
                                      CheckState::POSSIBLE_PASS,
                                      CheckState::UNKNOWN,
                                      CheckState::POSSIBLE_FAIL,
                                      CheckState::CERTAIN_FAIL})
               if (left == state || right == state)
                 return state;
             throw CapabilityException("Conjunction failure");
 
           default:
             throw CapabilityException("Unknown logic operator");
         }
       }
 
       case 1: // Bool
         return std::any_cast<CheckState>(vs[0]);
 
       default:
         throw CapabilityException("Unknown choice in Expression non-terminal");
     }
   };
 
   // (4) Parse
   parser.enable_packrat_parsing(); // Enable packrat parsing.
 
   CheckState state = CheckState::CERTAIN_FAIL;
   if (!parser.parse(requirements, state))
     throw CapabilityException("Unable to parse requested capabilities '", requirements, "'.");
 
   std::string reason;
   std::string doc;
 
   return {state, reason, doc};
 }

Classes

Typedefs

Enumerations

Functions