- Group: Modeling
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:
- Create a new report and open the Report database pane.
- 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.
- 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.
Approximation model configuration has 2 main modes — Simple and Flex.
The block is not configured, all data (including the model) is received from default ports: Model file or Model path, Variables, Responses.
The block has been configured in the block configuration dialog. The block configuration dialog has 2 tabs Model and Advanced.
If Model file and Model path ports are connected, a model from Model file will be loaded.
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 (
and also data fusion models trained by DFBuilder (
Note that data fusion models may lack certain features or information,
but general functionality is the same as for approximation models.
To load the model click button in the Approximation model pane of the block’s configuration dialog.
If the model has been changed on disk, click 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.
Clickto replace block variables and responses with model input and output names. Otherwise click to keep the previously configured names of variables and responses.
Also, variables and responses can be configured step by step.
A variable is an interface to the one or more model inputs.
When we add a variable under the name
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.|
Unique name of a variable and a corresponding input port.
Size of a variable vector (1 for scalar values).
|type:||RealScalar, RealVector, RealMatrix|
Default value, which will be used if the corresponding input port is not connected.
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:
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:
The Advanced tab is intended to map model Properties to output ports and specify a validation error or export file type.
After a model file is selected, you can click in the Model tree pane to get model properties.
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.
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
- … more subtrees
Hovering a tree node shows a tooltip with node’s properties: type, value and read-only state.
When you select a node in the project tree, it is mapped to a port of this type.
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.
If you select a read-only node in the project tree, it is always mapped to an output port.
To calculate model validation errors,
select the appropriate error type from the drop-down list
in the Validation errors pane.
Possible values are:
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.
The Approximation model block can export approximation models (
to various formats:
Executable: command-line executable for the platform, on which pSeven currently runs (
.exefor Windows and
.binfor 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_ROOTenvironment 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_ROOTmust contain the path to the compiler executable (
CSHARP_LIBRARIES_ROOTmust contain the full path to the directory where the
System.Private.CoreLib.dlllibraries are located. Finally, the dotnet executable should be added to
- 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
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
C source for library: C header and model implementation, which you can compile to a shared library (DLL or
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 (
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.
If you select the Excel export format,
the Model Export.Excel document with a linked DLL port outputs a ZIP archive (
containing all exported files
(Excel document, DLL files, VBA wrapper code and model C source).
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.
Error handling behavior
The action to perform if the block encounters an error.
output defaults and signal,
output signal only
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.
output signal onlybehavior means to output only the
Falsevalue 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:
-1for the ports corresponding to integer parameters,
NaNfor 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
NaNscalar 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.
- GTApprox guide
- The guide to the Generic Tool for Approximation (GTApprox) — the pSeven Core approximation component used by Approximation model to evaluate models.