Check a model

Two checker classes are provided in libCellML; the Validator and the Analyser classes. These can be used to check the syntax and structure of your model is correct (validating), and to check that its mathematical representation is solvable (analysing).

Validate a model

The Validator is the equivalent of a spelling checker: it can check that each item in a model has all of the information it needs, but it can’t check whether it means what you intend it to. Thus even if a model is valid, it could still be the equivalent of correctly-spelled nonsense.

Validate a model against the CellML specification

C++ snippetPython snippet

    // Validate the model: check for syntactic and semantic errors.

    // Create a Validator instance and pass the model for checking.
    auto validator = libcellml::Validator::create();
    validator->validateModel(model);
    auto isValid = validator->errorCount() == 0;
    printIssues(validator);

Full context: example_simulationToolDev.cpp

Once a model has been passed to a Validator instance, the validator’s internal logger will contain a list of any of the issues which have been encountered during the checking process. A model can be said to be valid - that is, conforming to the CellML normative specification - if the validator’s logger contains no issues with a level of ERROR.

For more information on how to use any of the classes which record issues, please see the Get Issues section below.

Retrieve Issue items

Selected libCellML classes contain a Logger whose job it is to curate any issues encountered within the class, and return them to the user when asked.

The classes are:

• the Parser class;

• the Validator class;

• the Printer class;

• the Analyser class;

• the Importer class; and

• the Generator class.

Individual issues can be retrieved from the parent class by their index, an integer between 0 and issueCount()-1. Each issue contains a severity level indicator, one of four levels (ERROR, WARNING, HINT, or MESSAGE):

• ERROR level indicates issues that must be resolved before the model is valid and runnable;

• WARNING level indicates a non-fatal issue, but one that may cause hidden or unintended consequences;

• HINT level indicates a commonly encountered valid-but-nonsense situation; and

• MESSAGE level is for your information but does not require action.

Issues can also be retrieved from subgroups based on their severity, as shown in the examples below.

C++Python

// Iterate through all the issues in a Validator, regardless of level, and print to the terminal.
for (size_t i = 0; i < validator->issueCount(); ++i) {
  // Retrieve the i-th issue and store it in the variable "myIssue".
  libcellml::IssuePtr myIssue = validator->issue(i);

  // Print the issue's description:
  std::cout << myIssue->description() << std::endl;

  // Print the issue's URL.  This is a URL at which more
  // information could be found about the cause and corrections
  // are needed to avoid it.
  std::cout << myIssue->url() << std::endl;

  // Validator only: Print the issue's reference. This is
  // the heading reference in the normative specification which
  // relates to this issue.
  std::cout << myIssue->referenceHeading() << std::endl;
}

// Retrieve the second ERROR level issue from a Printer. Note indexing from 0.
auto secondError = printer->error(1);

// Retrieve the last WARNING level issue from a Parser.
auto lastWarning = parser->warning(parser->warningCount()-1);

// Iterate through all HINT level issues in a Generator.
for (size_t h = 0; h < generator->hintCount(); ++h) {
  // Retrieve the h-th hint and store it in the variable "myHint".
  auto myHint = generator->hint(h);
}

Each Issue also contains the following attributes:

• A description: a brief statement about the problem and how it might be fixed;

• A reference heading: a chapter number pertaining to the formal CellML 2.0 Specification document, for issues related to formatting and specification;

• A URL: a web address at which more detailed information and examples pertaining to the issue are available;

• A cause: an enum which reports the type of item responsible for the issue. This is one of the enums:

• COMPONENT,

• CONNECTION,

• ENCAPSULATION,

• IMPORT,

• MAP_VARIABLES,

• MATHML,

• MODEL,

• RESET,

• RESET_VALUE,

• TEST_VALUE,

• UNDEFINED,

• UNIT,

• UNITS,

• VARIABLE, and

• XML.

C++Python

// Retrieve and print the description of the issue.
std::cout << issue->description() << std::endl;

// Retrieve and print the reference heading number, if related to CellML2.0 specification and format.
std::cout << issue->referenceHeading() << std::endl;

// Retrieve and print the URL for more help and information about the issue.
std::cout << issue->url() << std::endl;

// Retrieve the item type - a libcellml::CellmlElementType enum - for the issue.
auto myType = issue->CellmlElementType();

// Retrieve the level - a libcellml::Issue::LEVEL enum - for the issue.
auto myLevel = issue->level();

Useful functions for dealing with Issues

Utility functions to retrieve issues

C++Python

void printIssues(const libcellml::LoggerPtr &item) {

    // Get the number of issues attached to the logger item.  Note that this will 
    // return issues of all levels.  To retrieve the total number of a specific level
    // of issues, use the errorCount(), warningCount(), hintCount(), or messageCount() functions. 
    size_t num = item->issueCount();
    std::cout << "Recorded " << num << " issues";

    if (num != 0) {
        std::cout << ":" << std::endl;
        for (size_t i = 0; i < num; ++i) {

            // Retrieve the issue at index i.  Note that this is agnostic as to the level of issue.
            // Specific issue levels can be retrieved using the functions item->error(i), item->warning(i) 
            // etc, where the index must be within appropriate limits.
            libcellml::IssuePtr issue = item->issue(i);

            // Issues created by the Validator class contain a reference heading number, which indicates
            // the section reference within the normative specification relevant to the issue.
            std::string errorReference = issue->referenceHeading();

            // The level of an issue is retrieved using the level() function as an enum value.  
            std::cout << "Issue " << i << " is " << getIssueLevelFromEnum(issue->level()) << ":" << std::endl;

            // Each issue has a descriptive text field, accessible through the description() function.
            std::cout << "    description: " << issue->description() << std::endl;
            if (errorReference != "") {
                std::cout << "    see section " << errorReference
                          << " in the CellML specification." << std::endl;
            }

            // An optional URL is given for some issues which directs the user to more detailed information.
            if(!issue->url().empty()){
                std::cout << "    more information at: " <<issue->url() << std::endl;
            }

            // Each issue is associated with an item.  In order to properly deal with the item stored, its type is 
            // recorded too in an enumeration.
            std::cout << "    stored item type: " << getCellmlElementTypeFromEnum(issue->cellmlElementType()) << std::endl;
        }
        std::cout << std::endl << std::endl;
    }
    else {
        std::cout << "!" << std::endl << std::endl;
    }
}

std::map<libcellml::CellmlElementType, std::string> itemTypeToString = 
    {{libcellml::CellmlElementType::COMPONENT, "COMPONENT"},
    {libcellml::CellmlElementType::COMPONENT_REF, "COMPONENT_REF"},
    {libcellml::CellmlElementType::CONNECTION, "CONNECTION"},
    {libcellml::CellmlElementType::ENCAPSULATION, "ENCAPSULATION" },
    {libcellml::CellmlElementType::IMPORT, "IMPORT"},
    {libcellml::CellmlElementType::MAP_VARIABLES, "MAP_VARIABLES"},
    {libcellml::CellmlElementType::MATH, "MATH"},
    {libcellml::CellmlElementType::MODEL, "MODEL"},
    {libcellml::CellmlElementType::RESET, "RESET"},
    {libcellml::CellmlElementType::RESET_VALUE, "RESET_VALUE"},
    {libcellml::CellmlElementType::TEST_VALUE, "TEST_VALUE"},
    {libcellml::CellmlElementType::UNDEFINED, "UNDEFINED"},
    {libcellml::CellmlElementType::UNIT, "UNIT"},
    {libcellml::CellmlElementType::UNITS, "UNITS"}, 
    {libcellml::CellmlElementType::VARIABLE, "VARIABLE"}};

std::string getCellmlElementTypeFromEnum(libcellml::CellmlElementType t) {
    return itemTypeToString.at(t);
}

std::string getIssueLevelFromEnum(libcellml::Issue::Level myLevel)
{
    std::string myTypeAsString = "dunno";

    switch (myLevel) {
    case libcellml::Issue::Level::ERROR:
        myTypeAsString = "an ERROR";
        break;
    case libcellml::Issue::Level::WARNING:
        myTypeAsString = "a WARNING";
        break;
    case libcellml::Issue::Level::HINT:
        myTypeAsString = "a HINT";
        break;
    case libcellml::Issue::Level::MESSAGE:
        myTypeAsString = "a MESSAGE";
        break;
    }
    return myTypeAsString;
}

Full context: utilities.cpp

Analyse a Model item

The Analyser class takes an existing, valid Model item, and checks it for mathematical sense. This includes checking things like that all variables requiring initial values have them, that equations do not conflict with one another, and that any variables used in equations are actually defined in the model.

The three basic steps to model analysis are:

1. Creating an Analyser item and passing in a Model for analysis;

2. Checking for any Issues raised; and

3. (optional: for code generation only) Retrieving a AnalysedModel item to pass to a Generator, if required.

C++Python

    // Analyse the model: check for mathematical and modelling errors.
    auto analyser = libcellml::Analyser::create();
    analyser->analyseModel(model);
    printIssues(analyser);

Full context: example_simulationToolDev.cpp

Any issues or messages raised are stored within the class’s logger. More information about accessing Issue items can be found on the Common actions > Retrieve Issue items page.

Use of the Analyser class is a prerequisite for the Generator class. The generator makes use of the structures created during the analysis process, so takes a AnalyserModel as an input.

C++Python

    // Generate runnable code in other language formats for this model.

    // Create a Generator instance.  Note that by default this uses the C language profile.
    auto generator = libcellml::Generator::create();

    // Pass the generator the model for processing.
    generator->setModel(analyser->model());
    printIssues(generator);

Full context: example_simulationToolDev.cpp

TODO