Documentation

# To File

Write data to file

• Library:

HDL Coder / Sinks

## Description

The To File block writes input signal data into a MAT-file. The block writes to the output file incrementally, with minimal memory overhead during simulation. If the output file exists when the simulation starts, the block overwrites the file. The file automatically closes when you pause the simulation or the simulation completes. If simulation terminates abnormally, the To File block saves the data it has logged up until the point of the abnormal termination.

The To File block icon shows the name of the output file.

### Control Amount of Data Saved

If you specify data logging intervals with the Configuration Parameters > Data Import/Export > Logging intervals parameter, the To File block logs only data inside of the intervals. For example, the block logs no data if the intervals are empty ([]). The block stores the logged data in the file associated with the block instead of in the variable that you specify for the Single simulation output parameter.

For variable-step solvers, to control the amount of data available to the To File block, use the Configuration Parameters > Data Import/Export > Additional parameters > Output options parameter. For example, to write data at identical time points over multiple simulations, select the Produce specified output only option.

Block parameters also control the amount of data saved. See Decimation and Sample time.

### Pause Simulation

After pausing a simulation, do not alter any file that a To File block logs into. For example, do not save such a file with the MATLAB® save command. Altering the file can cause an error when you resume the simulation. If you want to alter the file after pausing, copy the file and work with the copy of the file.

If you pause using the Simulation Stepper, the To File block captures the simulation data up to the point of the pause. When you step back, the To File data file no longer contains any simulation data past the new reduced time of the last output.

## Limitations

When a To File block is in a referenced model, that model must be a single-instance model. Only one instance of such a model can exist in a model hierarchy. See Model Reuse for more information.

## Ports

### Input

expand all

Signal to store in file. Each sample consists of a timestamp and an associated data value. The data can be in array format or MATLAB timeseries format. The To File block accepts real or complex signal data of any data type that Simulink® software supports, except fixed-point data with a word length greater than 32 bits.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | Boolean | fixed point | enumerated | bus

## Parameters

expand all

Specify the path or file name of the MAT-file in which to store the output. On UNIX® systems, the path name can start with a tilde (~) character signifying your home folder. If you specify a file name without path information, Simulink software stores the file in the MATLAB working folder. (To determine the working folder, at the MATLAB command line, enter pwd.) If the file exists, Simulink software overwrites it.

#### Programmatic Use

 Block Parameter: FileName Type: character vector Values: MAT-file path or name Default: 'untitled.mat'

Specify the name of the matrix contained in the file.

#### Programmatic Use

 Block Parameter: MatrixName Type: character vector Values: character vector Default: 'ans'

Specify the data format that the To File block uses for writing data.

Use the Array format only for vector, double, noncomplex signals.

For the Timeseries format, the To File block:

• Writes data in a MATLAB timeseries object.

• Supports writing multidimensional, real, or complex output values.

• Supports writing output values that have any built-in data type, including Boolean, enumerated (enum), and fixed-point data with a word length of up to 32 bits.

• For virtual and nonvirtual bus input signals, creates a MATLAB structure that matches the bus hierarchy. Each leaf of the structure is a MATLAB timeseries object.

For the Array format, the To File block:

• Writes data into a matrix containing two or more rows. The matrix has 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]$

Simulink software writes one column to the matrix for each data sample. The first element of the column contains the timestamp. The remainder of the column contains data for the corresponding output values.

• Supports writing data that is one-dimensional, double, and noncomplex.

The From File block can use data written by a To File block in any format (Timeseries or Array) without any modifications to the data or other special provisions.

The From Workspace block can read data that is in the Array format and is the transposition of the data written by the To File block. To provide the required format, use MATLAB commands to load and transpose the data from the MAT-file.

The following table shows how simulation mode support depends on the Save format value.

Simulation ModeTimeseriesArray
NormalSupportedSupported
AcceleratorSupportedSupported
Rapid AcceleratorSupportedSupported
Software-in-the-loop (SIL) Not supportedSupported if MAT-file logging is enabled
Processor-in-the-loop (PIL)Not supportedSupported if MAT-file logging is available and enabled
ExternalNot supportedSupported if MAT-file logging is enabled
RSim targetSupportedSupported if MAT-file logging is enabled

#### Programmatic Use

 Block Parameter: SaveFormat Type: character vector Values: 'Timeseries' | 'Array' Default: 'Timeseries'

Specify the decimation factor, n, that writes data at every nth time that the block executes. The default value has this block writing data at every time step.

#### Programmatic Use

 Block Parameter: Decimation Type: character vector Values: scalar | vector Default: '1'

Specifies the sample period and offset at which to collect data points. This parameter is useful when you are using a variable-step solver where the interval between time steps is not constant. The default value causes the block to inherit the sample time from the driving block. See Specify Sample Time.

#### Programmatic Use

 Block Parameter: SampleTime Type: character vector Values: scalar | vector Default: '-1'

## Block Characteristics

 Data Types Boolean | bus | double | enumerated | fixed point[a] | integer | single Direct Feedthrough no Multidimensional Signals yes Variable-Size Signals no Zero-Crossing Detection no [a] Supports up to 32-bit fixed-point data types.

## Tips

• If MATLAB encounters memory issues when you log many signals in a long simulation that has many time steps, consider logging to persistent storage. When you log to persistent storage, the Dataset format logging data is stored in a MAT-file. Compared to logging to persistent storage, connecting a To File block to signals:

• Is a per-signal approach that can clutter a model with several To File blocks attached to individual signals.

• Creates a separate MAT-file for each To File block, compared to the one MAT-file that logging to persistent storage uses.

For details, see Log Data to Persistent Storage.

• To avoid the overhead of compressing data in real time, the To File block writes an uncompressed Version 7.3 MAT-file. To compress the data within the MAT-file, load and save the file in MATLAB. The resaved file is smaller than the original MAT-file that the To File block created, because the Save command compresses the data in the MAT-file.