From File

Sources

Description

The From File block reads data from a MAT-file and outputs the data as a signal. The data is a sequence of samples. Each sample consists of a time stamp and an associated data value.

The From File block icon shows the name of the MAT-file that supplies the data.

You can have multiple From File blocks that read from the same MAT-file.

Storage Formats

When the From File block reads data from a MAT-file, that data must be stored in one of two formats:

• MATLAB® `timeseries` object

• Array

Use array format only for vector, double, noncomplex signals. To load a bus signal, use a MATLAB structure that matches the bus hierarchy, where each leaf of the structure is a MATLAB `timeseries` object.

The MATLAB `timeseries` format supports the following simulation and code generation modes:

• Normal

• Accelerator

• Rapid Accelerator

• Rapid simulation target (RSim)

• Model Reference Accelerator

MATLAB `timeseries` format data can have:

• Any dimensionality and complexity

• Any built-in data type, including `Boolean`

• A fixed-point data type with a word length of up to 32 bits

• An enumerated data type

The array format for stored data is a matrix containing two or more rows. The matrix in the MAT-file must have the following form:

$\left[\begin{array}{cccc}{t}_{1}& {t}_{2}& \dots & {t}_{final}\\ u{1}_{1}& u{1}_{2}& \dots & u{1}_{final}\\ \dots & & & \\ u{n}_{1}& u{n}_{2}& \dots & u{n}_{final}\end{array}\right]$

The first element of each column contains a time stamp. The remainder of the column contains data for the corresponding output values. Each element must be a double and cannot include a NaN, Inf, or -Inf.

For data stored using the array format, the width of the From File output depends on the number of rows in the matrix. Given a matrix containing m rows, the block outputs a vector of length m–1.

MAT-File Variable that From File Uses

If a MAT-file contains only one variable, then the From File block uses that variable.

If the MAT-file contains more than one variable:

• For Version 7.3 MAT-files, the From File block uses the variable that is first alphabetically.

• For Version 7.0 or earlier MAT-files, the From File also uses the first variable. However, for Version 7.0 and earlier, the ordering algorithm for variables is complicated. Use a MAT-file that contains just the variable with the data that you want the From File block to read into the model.

Simulation

For a Version 7.3 MAT-file, the From File block incrementally reads data from the MAT-file during simulation.

 Tip   For faster data loading, consider upgrading Version 7.0 or earlier MAT-files to Version 7.3. For details, see Convert Version 7.0 and Earlier Version MAT-Files.

The Sample time parameter specifies the sample time that the From File block uses to read data from a MAT-file. For details, see "Parameters and Dialog Box". The time stamps in the file must be monotonically nondecreasing.

For each simulation time hit for which the MAT-file contains no matching time stamp, Simulink® software interpolates or extrapolates to obtain the needed data using the method that you select. For details, see "Simulation Time Hits That Have No Corresponding MAT-File Time Stamps."

During simulation, the From File block cannot read data from a MAT-file that is being written to by a To File block.

Simulation Time Hits That Have No Corresponding MAT-File Time Stamps

If the simulation time hit does not have a corresponding MAT-file time stamp, then the From File block output depends on :

• Whether the simulation time hit occurs before the first time stamp, within the range of time stamps, or after the last time stamp.

• The interpolation or extrapolation methods that you select

• The data type of the MAT-file data

For details about interpolation and extrapolation options, see the descriptions of the following parameters in "Parameters and Dialog Box":

• Data extrapolation before first data point

• Data interpolation within time range

• Data extrapolation after last data point

Sometimes the MAT-file includes duplicate time stamps (two or more data values that have the same time stamp). In such cases, the From File block action depends when the simulation time hit occurs, relative to the duplicate time stamps in the MAT-file.

For example, suppose the MAT-file contains the following data, with three data values having a time stamp value of `2`:

```time stamps: 0 1 2 2 2 3 4 data values: 2 3 6 4 9 1 5 ```

The following table describes the From File block output.

Simulation Time, Relative to Duplicate Time Stamp Values in MAT-FileFrom File Block Action
Before the duplicate time stamps

Performs the same actions as when the time stamps are distinct, using the first of the duplicate time stamp values as the basis for interpolation. (In this example, that time stamp value is `6`.)

At or after the duplicate time stamps

Performs the same actions as when the times stamps are distinct, using the last of the duplicate time stamp values as the basis for interpolation. (In this example, that time stamp value is `9`.)

Using Data Saved by a To File Block

The From File block reads data written by a To File block without any modifications to the data or other special provisions.

Using Bus Data

The data must be in a MATLAB structure that matches the bus hierarchy. Each leaf of the structure must be a MATLAB `timeseries` object.

The data can underspecify the bus signal, but cannot overspecify the bus signal. The structure cannot have any elements that do not have corresponding signals in the bus.

The structure does not require data for every element in the bus hierarchy, but the structure must have data for at least one of the signals in the bus. For signals that do not specify data, the From File block outputs the ground values.

Code Generation Requirements

For a From File block, simulating in Accelerator, Rapid Accelerator, or model reference Accelerator mode or building an RSim target behaves the same way, and has the same requirements, as simulating in Normal mode.

For a From File block, generating code that involves building ERT or GRT targets, or using SIL or PIL simulation modes, requires that:

• The MAT-file contains a non-empty finite real matrix with at least two rows.

• The matrix must have a data type of `double`.

• The matrix does not have any NaN, Inf, or -Inf elements.

• The From File block parameters dialog box has the following settings:

• Set the Data extrapolation before first data point and Data extrapolation after last data point parameters to `Linear extrapolation`.

• Set tthe Data interpolation within time range parameter to `Linear interpolation`

• Clear the Enable zero-crossing detection parameter.

Convert Version 7.0 and Earlier Version MAT-Files

For Version 7.0 or an earlier version of a MAT-file, the From File block reads only array-format data. The complete, uncompressed data from a MAT-file loads into memory at the start of the simulation.

If you have a Version 7.0 or earlier version MAT-file that you want to use with the From File block, consider converting the file to a Version 7.3 MAT-file. Use a Version 7.3 MAT-file if you want the From File block to incrementally read the data during simulation or you want to use MATLAB `timeseries` data. For example, to convert a Version 7.0 file named `my_data_file.mat` that contains the variable `var`, at the MATLAB command line, enter:

```load('my_data_file.mat') save('my_data_file.mat', 'var', '-v7.3')```

Data Type Support

For timeseries data, the From File block can read real or complex signal data of any data type that Simulink supports, except that fixed-point data cannot have a word length that exceeds 32 bits. The From File block supports reading nonvirtual bus signals in timeseries format.

For array data, the From File block can read only double signal data.

Parameters and Dialog Box

File name

The path or file name of the MAT-file that contains the data used as input. On UNIX® systems, the path name can start with a tilde (~) character signifying your home folder. The default file name is `untitled.mat`. If you specify a file name without path information, Simulink reads the file in the MATLAB current folder. (To determine the current folder, type `pwd` at the MATLAB command line.)

Output data type

The data type for the data that the From File block outputs. For non-bus types, you can use `Inherit: auto` to skip any data type verification. If you specify an output data type, then the From File block verifies that the data in the file matches the data type that you specified. For more information, see Specify Block Output Data Types.

If you set Output data type to be a bus object, the bus object must be available when you compile the model. For each signal in bus data, the From File block verifies that the data type, dimension, and complexity of the data matches the data type, dimension, and complexity that the bus object defines for the signal. For more information, see Using Bus Data.

• `Inherit: auto` — Default

• `double`

• `single`

• `int8`

• `uint8`

• `int16`

• `uint16`

• `int32`

• `uint32`

• `boolean`

• `fixdt(1,16,0)` — Data type is fixed-point (1,16,0).

• `fixdt(1,16,2^0,0)` — Data type is fixed-point (1,16,2^0,0).

• `Enum: <class_name>` — Data type is enumerated.

• `Bus: <bus_object>` — Data type is a bus object. For details, see the "Using Bus Data" section.

• `<data type expression>` — The name of a data type object, for example `Simulink.NumericType`. Do not specify a bus object as the expression.

>> (Show data type assistant)

Displays the Data Type Assistant, to help you to set the Output data type parameter.

Mode

The category of data to specify. For more information, see Specify Block Output Data Types.

• `Inherit` — Inheritance rule for data types. Selecting `Inherit` enables a second menu/text box to the right. (Default)

• `Built in` — Built-in data types. Selecting `Built in` enables a second menu/text box to the right. Select one of the following choices:

• `double` — Default

• `single`

• `int8`

• `uint8`

• `int16`

• `uint16`

• `int32`

• `uint32`

• `boolean`

• `Fixed point` — Fixed-point data types

• `Enumerated` — Enumerated data types. Selecting `Enumerated` enables a second menu/text box to the right, where you can enter the class name.

• `Bus` — Bus object. Selecting `Bus` enables a Bus object parameter to the right, where you enter the name of a bus object that you want to use to define the structure of the bus. If you need to create or change a bus object, click Edit to the right of the Bus object field to open the Simulink Bus Editor. For details, see Manage Bus Objects with the Bus Editor.

• `Expression` — Expression that evaluates to a data type. Selecting `Expression` enables a second menu/text box to the right, where you enter the expression. Do not specify a bus object as the expression.

Sample time

The sample period and offset.

The From File block reads data from a MAT-file using a sample time that either:

• You specify for the From File block

• The From File block inherits from the blocks into which the From File block feeds data

The default is `0`, which specifies a continuous sample time. The MAT-file is read at the base (fastest) rate of the model. For details, see Specify Sample Time.

Data extrapolation before first data point

Extrapolation method that Simulink uses for a simulation time hit that is before the first time stamp in the MAT-file. Choose one of the following extrapolation methods.

MethodDescription
`Linear extrapolation`

(Default)

If the MAT-file contains only one sample, then the From File block outputs the corresponding data value.

If the MAT-file contains more than one sample, then the From File block linearly extrapolates using the first two samples:

• For `double` data, linearly extrapolates the value using the first two samples

• For `Boolean` data, outputs the first data value

• For a built-in data type other than `double` or `Boolean`, upcasts the data to `double`, performs linear extrapolation (as described above for `double` data), and then downcasts the extrapolated data value to the original data type

You cannot use the `Linear extrapolation` option with enumerated (`enum`) data. All signals in a bus use the same extrapolation setting, so if any signal in a bus uses `enum` data, then you cannot use the `Linear extrapolation` option.

`Hold first value`

Uses the first data value in the file

`Ground value`

Uses a value that depends on the data type of MAT-file sample data values:

• Fixed-point data types — uses the ground value

• Numeric types other than fixed–point — uses `0`

• `Boolean` — uses `false`

• Enumerated data types — uses default value

Data interpolation within time range

The interpolation method that Simulink uses for a simulation time hit between two time stamps in the MAT-file. Choose one of the following interpolation methods.

MethodDescription
`Linear interpolation`

(Default)

The From File block interpolates using the two corresponding MAT-file samples:

• For `double` data, linearly interpolates the value using the two corresponding samples

• For `Boolean` data, uses `false` for the first half of the sample and `true` for the second half.

• For a built-in data type other than `double` or `Boolean`, upcasts the data to `double`, performs linear interpolation (as described above for `double` data), and then downcasts the interpolated value to the original data type

You cannot use the `Linear interpolation` option with enumerated (`enum`) data. All signals in a bus use the same interpolation setting, so if any signal in a bus uses `enum` data, then you cannot use the `Linear interpolation` option.

`Zero order hold`

Uses the data from the first of the two samples

Data extrapolation after last data point

The extrapolation method that Simulink uses for a simulation time hit that is after the last time stamp in the MAT-file. Choose one of the following extrapolation methods.

MethodDescription
`Linear extrapolation`

(Default)

If the MAT-file contains only one sample, then the From File block outputs the corresponding data value.

If the MAT-file contains more than one sample, then the From File block linearly extrapolates using data values of the last two samples:

• For `double` data, extrapolates the value using the last two samples

• For `Boolean` data, outputs the last data value

• For a built-in data type other than `double` or `Boolean`, upcasts the data to `double`, performs linear extrapolation (as described above for `double` data), and then downcasts the extrapolated value to the original data type

You cannot use the `Linear extrapolation` option with enumerated (`enum`) data. All signals in a bus use the same extrapolation setting, so if any signal in a bus uses `enum` data, then you cannot use the `Linear extrapolation` option.

`Hold last value`

Uses the last data value in the file

`Ground value`

Uses a value that depends on the data type of MAT-file sample data values:

• Fixed-point data types — uses the ground value

• Numeric types other than fixed–point — uses `0`

• `Boolean` — uses `false`

• Enumerated data types — uses default value

Enable zero-crossing detection

Select to enable zero-crossing detection.

The Zero-Crossing Detection parameter applies only if the Sample time parameter is set to `0` (continuous).

Simulink uses a technique known as zero-crossing detection to accurately locate a discontinuity, without resorting to excessively small time steps. This section uses "zero-crossing" to represent discontinuities.

For the From File block, zero-crossing detection can only occur at time stamps in the file. Simulink examines only the time stamps, not the data values.

For bus signals, Simulink detects zero-crossings across all leaf bus elements.

If the input array contains duplicate time stamps (more than one entry with the same time stamp), Simulink detects a zero crossing at that time stamp. For example, suppose the input array has this data:

```time: 0 1 2 2 3 signal: 2 3 4 5 6 ```

At time 2, there is a zero crossing from the input signal discontinuity.

For data with nonduplicate time stamps, zero-crossing detection depends on the settings of the following parameters:

• Data extrapolation before first data point

• Data interpolation within time range

• Data extrapolation after last data point

The From File block applies the following rules when determining when zero-crossing occurs for the first time stamp, for time stamps between the first and last time stamp, and for the last time stamp.

Time StampWhen Zero-Crossing Detection Occurs

First

Data extrapolation before first data point is set to `Ground value`.

Between first and last

Data interpolation within time range is set to `Zero-order hold`.

Last

One or both of these settings occur:

• Data extrapolation after last data point is set to `Ground value`.

• Data interpolation within time range is set to `Zero-order hold`.

The following figure illustrates zero-crossing detection for data accessed by a From File block that has the following settings:

• Data extrapolation before first data point```Linear extrapolation```

• Data interpolation within time range (for internal points) — `Zero order hold`

• Data extrapolation after last data point```Linear extrapolation```

The following figure is another illustration of zero-crossing detection for data accessed by a From File block. The block has the following settings for the time stamps (points):

• Data extrapolation before first data point```Hold first value```

• Data interpolation within time range```Zero order hold```

• Data extrapolation after last data point```Hold last value```

Characteristics

 Sample Time Specified in the Sample time parameter Scalar Expansion No Dimensionalized Yes Zero Crossing Yes, if enabled