Approximation model

Introduction

The Approximation model block evaluates an approximation model trained with an ApproxBuilder block or using predictive modeling tools in Analyze. The block receives a data sample for evaluation and outputs model values, gradients, and accuracy evaluation data. The block also outputs model information and validation data as a report in the HTML format to the Report port. Note that monitoring for this port is disabled by default.

To view the model report in Analyze:

  1. Create a new report and open the Report database pane.
  2. Drag the record with the report from the Project database pane to the Data series pane in the report database. It will create a string data series containing the HTML code.
  3. Select this new data series and click the Page viewer button on the report toolbar.

You can also export this report as a file to disk by specifying the export path to the Report path port. The path can be relative to the project directory — for example, ./results/My report.html saves the file to the results subdirectory in the project. Absolute paths can be used to save the report outside the project. In both cases, if the specified file already exists, it will be replaced.

Configuration

Approximation model configuration has 2 main modes — Simple and Flex.

  • Simple

    The block is not configured, all data (including the model) is received from default ports: Model file or Model path, Variables, Responses.

  • Flex

    The block has been configured in the block configuration dialog. The block configuration dialog has 2 tabs Model and Advanced.

Note

If Model file and Model path ports are connected, a model from Model file will be loaded.

Model Tab

The Model tab is intended to show main information about the loaded model and configure model inputs (variables) and outputs (responses).

Approximation model supports models trained by ApproxBuilder (.gta, .gtapprox), and also data fusion models trained by DFBuilder (.gtdf). Note that data fusion models may lack certain features or information, but general functionality is the same as for approximation models.

../_images/ApproxModel_no_data.png

To load the model click b_browse button in the Approximation model pane of the block’s configuration dialog.

../_images/ApproxModel_file.png

If the model has been changed on disk, click b_refreshwhite button to reload the model from disk.

Named inputs and outputs of the loaded model will be displayed in Variables and Responses tables, respectively. The Replace dialog will be shown if names of inputs or outputs in the model differ from the names of variables and responses in block configuration.

../_images/ApproxModel_replace.png

Click Yes to replace block variables and responses with model input and output names. Otherwise click No to keep the previously configured names of variables and responses.

Also, variables and responses can be configured step by step.

Variables

A variable is an interface to the one or more model inputs. When we add a variable under the name x, the input port with the same name will be created. All ports corresponding to variables have the RealMatrix type and accept batches of variable values. Any variable has the following properties — name, size and default.

[*]All variables should be vectors of equal size.

Name

type:StringScalar

Unique name of a variable and a corresponding input port.

Size

type:IntScalar

Size of a variable vector (1 for scalar values).

Default

type:RealScalar, RealVector, RealMatrix

Default value, which will be used if the corresponding input port is not connected.

Responses

A response is an interface to one or more model outputs. Also, any response is an interface to the model derivatives and accuracy estimates. When we add a response with the name f, the following output ports are created: f, f.Gradient, f.Accuracy, f.Gradient accuracy. Similarly, when the port f is deleted, all output ports corresponding to it will be deleted too.

The general layout of the Model tab with the model being loaded is given below:

../_images/ApproxModel_modelpage.png

Advanced tab

The Advanced tab is intended to map model Properties to output ports and specify a validation error or export file type.

../_images/ApproxModel_notree.png

Model Tree

After a model file is selected, you can click b_build_tree in the Model tree pane to get model properties.

../_images/ApproxModel_modeltree.png

Here you can select nodes to be mapped to output ports. When you select a node, a new corresponding variable appears in the Properties pane.

Structure

Currently Approximation model supports mapping model properties to output ports. The project tree has a simple structure with subtrees of properties:

  • Model Details — provides a detailed description stored with the model
    • Input variables — details on model’s inputs (input variable’s name, brief description, physical quantity, measurement units, variability)
    • Output variables — details on model’s outputs (output variable’s name, brief description, physical quantity, measurement units, variability)
    • Technique — information on the technique that was used to train the model
    • Training Dataset — detailed information on the training dataset
    • … more subtrees
  • Internal Validation Info — lists model internal validation data
    • Componentwise
    • … more subtrees

Node Properties

Hovering a tree node shows a tooltip with node’s properties: type, value and read-only state.

Type

When you select a node in the project tree, it is mapped to a port of this type.

Value

Shows the parameter value saved in the selected project file. In case of vector variables shows the <DblClick to show> placeholder. Double click on the tree node to show a value in the viewer.

Read-only

If you select a read-only node in the project tree, it is always mapped to an output port.

Validation Errors

To calculate model validation errors, select the appropriate error type from the drop-down list in the Validation errors pane. Possible values are: Mean, Max, Median, 95-th percentile, 99-th percentile, RMS, RRMS.

When you set a value of Validation errors to one of options mentioned above, two ports will be created for each configured Response f. The input port will be named f.Reference and is intended for reference value. The output port will be named f.Error. The validation error will be output to the f.Error port.

Model Export

The Approximation model block can export approximation models (.gta, .gtapprox) to various formats:

  • Executable: command-line executable for the platform, on which pSeven currently runs (.exe for Windows and .bin for Linux). Note that it is not possible to export an executable file for another platform — for example, you cannot export a Windows executable under Linux.

  • Excel document with a linked DLL: an Excel document with macros (.xlsm), which evaluates the model stored into a complementary DLL. In addition to the Excel document and two model DLLs (for the 32-bit and 64-bit Excel editions), this format also provides a file containing the code of a VBA wrapper (.bas) for the model DLL, and C source (.c) of the DLL. Export to this format is supported only in the Windows version of pSeven.

    For convenience, the DLL names are based on the name of the Excel document. However, DLL names (hence, the Excel document name) are also used in the VBA macros code. Due to this, the document name must contain only characters, which can be represented in the system locale’s encoding (see Language for non-Unicode programs in Windows’ language settings). For compatibility across different local versions of Windows, it is recommended to use English characters only.

  • FMU for Co-Simulation 1.0: FMI model (Functional Mock-up Unit, .fmu) in the Co-Simulation format, with source and binary.

  • FMU for Model Exchange 1.0: FMI model (Functional Mock-up Unit, .fmu) in the Model Exchange format, with source and binary.

  • FMU for Co-Simulation 1.0 (source only): FMI model in the Co-Simulation format, with source only.

  • FMU for Model Exchange 1.0 (source only): FMI model in the Model Exchange format, with source only.

  • C# source (experimental): source code (.cs) to compile the model with C# compiler.

  • C# library (experimental): a compiled .NET DLL (.dll). Note that using this export format requires a C# compiler installed (pSeven does not include a C# compiler).

    • In Windows: requires .NET Framework or another package which provides the C# compiler (csc.exe). pSeven finds the compiler automatically; if there are several versions installed, the latest is used. If you want to select a specific version, you can set the CSHARP_COMPILER_ROOT environment variable. Its value should be the full path to the directory which contains csc.exe.
    • In Linux: requires the dotnet command line tool which is a part of .NET Core SDK. The following environment variables are also required: CSHARP_COMPILER_ROOT must contain the path to the compiler executable (csc.dll), and CSHARP_LIBRARIES_ROOT must contain the full path to the directory where the System.dll and System.Private.CoreLib.dll libraries are located. Finally, the dotnet executable should be added to PATH.
  • C source for standalone program: C source code with the main() function, which you can compile to a complete command-line program.

  • C header for library: the header for a model compiled to a shared library (DLL or .so).

  • C source for library: C header and model implementation, which you can compile to a shared library (DLL or .so).

  • C source for MEX: source code for a MATLAB MEX file.

  • Octave script: model code compatible with MATLAB.

The Approximation model block also works with data fusion models (.gtdf) trained by the DFBuilder block. If you load a data fusion model to Approximation model, you can export it to the C source code formats; other export formats are not supported for data fusion models.

Note

If you select the Excel export format, the Model Export.Excel document with a linked DLL port outputs a ZIP archive (.zip) containing all exported files (Excel document, DLL files, VBA wrapper code and model C source).

Note

An FMI model in either format (Co-Simulation or Model Exchange) can be exported as a FMU with a binary, or as a source-only FMU.

The binary FMU is ready to use, but it is platform-dependent: you can use it only on the same platform where it has been exported. For example, it is not possible to export a FMU with a Windows binary if you are running pSeven on Linux. However, this FMU also contains source code, so you can recompile it for any platform.

The source-only FMU does not contain any binaries, so you will always have to compile it in order to obtain a working FMU.

When you select an export format, the following set of ports appears on the Ports tab: (<format> is the format name):

  • Model Export.<format>.Path input — the path where to save the exported model file.
  • Model Export.<format>.Function name input — sets the name of the model function for source code formats. For C#, sets the namespace containing the model class. If the name contains dots ., it is used to generate a hierarchy of namespaces, using dots as separators. Each part of the name must be a valid C# namespace identifier: it must start with @, _, or a letter, and the rest can contain only alphanumeric characters and underscores _.
  • Model Export.<format>.Function description input — optional, adds a code comment for source code formats.
  • Model Export.<format> output — outputs the file with exported model. This port is intended to send the exported model to another block; to save the model to disk, set the save path using the Model Export.<format>.Path input.

If you select multiple export formats, this set of ports is created for each requested format.

See section Model Export for details on configuring the block to export models to various formats.

Options

Error handling behavior

The action to perform if the block encounters an error.

Value:stop workflow, output defaults and signal, output signal only
Default:stop workflow (interrupt immediately)

When set to stop workflow, the block simply reports an error and the workflow interrupts.

If set to output defaults and signal, the block suppresses the error and does not interrupt the workflow. In this case, the done port outputs False (the failure signal), and values assigned to other output ports are used to generate certain data (the defaults), which is output by the block in order to allow the workflow to continue.

The output signal only behavior means to output only the False value to done; nothing is output to other ports.

Changed in version 6.13: scalar values assigned to output ports have special meaning in error handling.

Note that when you load a model file on the Model tab or manually add variables and responses on their respective panes, the named input and output ports (the data ports) will be created. Selecting model parameters to be mapped in the model tree, manually adding properties, specifying a validation error or export file type on the Advanced tab will also result in creating the respective input or output ports (the property ports). The errors the block may encounter are handled differently for property ports and data ports. The details are explained below.

The property ports always output the values assigned to them in case of any block’s error (for example, the block was configured to output model accuracy estimates and the respective port was created, but the loaded model does not support accuracy evaluation). Note that the block automatically assigns values to output ports generated when mapping nodes in the model tree, adding properties via Add properties dialog, selecting a validation error or export file type. These values are as follows:

  • -1 for the ports corresponding to integer parameters,
  • NaN for the ports corresponding to floating point parameters,
  • an empty string for the ports corresponding to string parameters,
  • empty vectors for the ports corresponding to vector parameters (of any type),
  • empty matrices for the ports corresponding to matrix parameters (of any type),
  • empty lists for the ports corresponding to list parameters.

The values assigned by the block to output data ports may be either of an array type (a matrix or a list) or scalar. Array-type values are always output as they are. Scalar values are used to generate certain data which is output by the block not to interrupt the workflow. This output is generated as follows: the block considers the input batch size and model dimension, determines the appropriate shape of an output array (for example, the size of a matrix that will be sent to the Responses port), creates an array of the required shape and fills it with the port-value scalars. The block automatically assigns a NaN scalar value to output data ports. This scalar value is used as described above.

In some cases, errors occur as the block cannot recover the shape of an output array — for example, when the model file is corrupt or the information about the input batch size and model dimension is missing. If the issue arise, the block will also output a scalar value assigned to the port to indicate that something goes wrong.

See also

GTApprox guide
The guide to the Generic Tool for Approximation (GTApprox) — the pSeven Core approximation component used by Approximation model to evaluate models.