.. _compat_checker: ########################## QGen Compatibility Checker ########################## QGen supports a subset of Simulink/Stateflow block types and features. The QGen Compatibility Checker allows you to check if your model contains elements that are incompatible with QGen and provides a report of violations and warnings so that you can investigate them. The report can be produced either as an HTML document (the default format) or a plain text document. Check Levels ============ The QGen Compatibility Checker is invoked on a model or a subsystem in a model. It processes the elements of the model checking for incompatibilities with QGen and traverses referenced models and checks them too. The QGen Compatibility Checker can be invoked with 3 levels of checks. The first one is the quickest but the least thorough. It is convenient for getting a quick initial assessment of your model(s). The last one is the slowest but the most thorough. 1. **Quick Check** This level verifies that the following properties are satisfied: * The solver type of the model and all referenced models is 'FixedStepDiscrete'. Violations are reported as failures. * The Simulink block types used in the model and in all referenced models and libraries are supported by QGen. This check is based on the :ref:`list of QGen-supported Simulink block types `. Violations are reported as failures, except for occurences of the 'MATLAB Function' block type which is reported as a warning since QGen handles this block by generating a skeleton to be implemented manually. 2. **Data Types and Callbacks Check** This check includes the *Quick Check*, and verifies additionally that the following properties are satisfied: * All port types do not have matrices with more than 2 dimensions. Violations are reported as failures. * There are no callback functions defined in the model and the contained blocks and ports. Violations are reported as warnings because it is up to the user to manually review their compatibility with QGen. Callback functions used for transfering mask parameter values from masks to parameters with the same name inside a masked subsystem are supported. Callback functions that modify the structure of the model by adding/removing blocks are not supported by QGen. 3. **Full Check** This check includes the *Quick Check* and the *Data Types and Callbacks Check*, and finally it invokes the initial steps of the code generation process to perform more thorough checks of the :ref:`Simulink block constraints `. For example, a *Delay* block that has the *Delay length* set to *Input port* will not be reported as incompatible by the *Quick Check*, but will be reported as unsupported by the *Full Check* in observance of the :ref:`Delay block constraints `. Compatibility Report ==================== The default format of the compatibility report is an HTML document including a list of the checks performed and the status of each check: Pass, Fail or Warning. The report includes collapsable sections to enhance readability. Within the scope of each check, the result for each referenced model is included separately, with a listing of all references to that model from the main model to improve navigation. Whenever possible, model elements are provided in the report as hyperlinks that navigate automatically to the corresponding location in the model when clicked. An alternate plain text report format is available when invoking the checker from the MATLAB command line. However it is less detailed and less readable for large models. Therefore the recommended report format is the HTML document. Invocation from the Simulink GUI ================================ The QGen Compatibility Checker can be invoked from the QGen main menu, or by right-clicking a particular subsystem of your model. .. figure:: img/compat-check-menu.png QGen Compatibility Checker in the main menu .. figure:: img/compat-check-ctx.png QGen Compatibility Checker in the context menu After selecting the desired check level, the Compatibility Checker will run the corresponding verifications and report its progress on the MATLAB command line. Progress is reported as ``(Number of checked models / Total number of models)``. Finally, the compatibility report is opened automatically in the MATLAB web browser. .. rubric:: Example Let us consider the example model ``share/qgen/examples/speedometer/speedometer.mdl`` provided with the QGen installation. Let us introduce some incompatibilities such as a *Polynomial* block and a *Delay* block configured with *Delay length* set to *Input port*. A *Quick Check* would only detect the unsupported *Polynomial* block and yield the following compatibility report: .. figure:: img/compat-check-speedometer-quick.png Compatibility Report with Quick Check level However, a *Full Check* will also detect the unsupported *Delay* block because of its unsupported parameter value, and will yield the following compatibility report: .. figure:: img/compat-check-speedometer-full.png Compatibility Report with Full Check level Invocation from the MATLAB Command Line ======================================= The Compatibility Checker can be invoked from the MATLAB command line as follows:: qgen_compatibility_check(mdl_path [, subsys [, level [, report_format, [, verbosity]]]]) The first argument ``mdl_path`` is the path to the Simulink model file. Optional arguments may follow in the following order: * ``subsys``: path to a subsystem in the model (Default: ``''``) Restricts the check to the specified subsystem. * ``level``: one of the strings ``'quick'``, ``'datatypes'`` or ``'full'`` (Default: ``'quick'``) Select the level of checks to perform. * ``report_format``: one of the strings ``'html'`` or ``'text'`` (Default: ``'html'``) * ``verbosity``: an integer between ``0`` and ``2`` (Default: ``0``) Configure the level of verbosity in the messages displayed on the console. A higher value yields more detailed messages. .. rubric:: Example For example, to perform the data types and callbacks check on the model ``speedometer.mdl`` and get a text report, use the following command:: >> qgen_compatibility_check('speedometer.mdl', '', 'datatypes', 'text') [INFO][QGen] Initializing QGen Compatibility Checker for level DATATYPES [INFO][QGen] (1/1) Loading speedometer [INFO][QGen] (1/1) Checking speedometer [INFO][QGen] (1/1) Running 'Update Diagram' of speedometer [INFO][QGen] (1/1) ########### [INFO][QGen] (1/1) # Results # [INFO][QGen] (1/1) ########### [INFO][QGen] (1/1) Found 2 constraint violations [INFO][QGen] (1/1) 1/2 Check failed: The following blocks have types that are unsupported by QGen [INFO][QGen] (1/1) 1 offending elements: [INFO][QGen] (1/1) speedometer/Polynomial of type Polyval [INFO][QGen] (1/1) Workaround: Use (an)other supported block type(s) that provides the same behavior [INFO][QGen] (1/1) 2/2 Check failed: [INFO][QGen] (1/1) 1 offending elements: [INFO][QGen] (1/1) speedometer/Compare To Constant [INFO][QGen] (1/1) Workaround: Make sure that the listed callback functions do not modify the structure of the model [INFO][QGen] (1/1) Details: [INFO][QGen] (1/1) speedometer/Compare To Constant callback Initialization [INFO][QGen] (1/1) speedometer/Compare To Constant callback ZeroCross [INFO][QGen] (1/1) Finished checking compatibility Invocation from Model Advisor ============================= If you have a valid *Simulink Verification and Validation* license [1]_ , you can also use the QGen Compatibility Checker from Model Advisor. To do so, open Model Advisor from the Simulink *Analysis* menu. As shown in the screenshot, QGen's compatibility checks are integrated in Model Advisor as individual checks .. figure:: img/compat-check-mdladv.png QGen Compatibility Checker integration with Model Advisor Select the checks you wish to perform, and click *Run Selected Checks*. The results of the checks are reported within the Model Advisor window as customary with standard Model Advisor checks. .. [1] Contact MathWorks to purchase a *Simulink Verification and Validation* license