Documentation

To File

Write data to file

Library

Sinks

Description

The To File block inputs a signal and writes the signal data into a MAT-file. Use the To File block to log signal data.

The To File block icon shows the name of the output 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 simulation is complete or paused. If simulation terminates abnormally, the To File block saves the data it has logged up until the point of the abnormal termination.

Specifying the Format for Writing Data

Use the Save format parameter to specify the format for writing data:

  • Timeseries (default)

  • Array

Use the Array format only for vector, double, noncomplex signals. To save bus data, use the Timeseries format.

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 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:

    [t1t2tfinalu11u12u1finalun1un2unfinal]

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

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

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

Simulation ModeTimeseriesArray
NormalSupported.Supported.
AcceleratorSupported.Supported.
Rapid AcceleratorSupported.Supported.
Software-in-the-Loop (SIL) Not supported.Supported if MAT-file logging is enabled.
Processor-in-the-Loop (PIL)Not supported.Supported if MAT-file logging is available and enabled.
ExternalNot supported.Supported if MAT-file logging is enabled.
RSim targetSupported.Supported if MAT-file logging is enabled.

Controlling When Data Is Written to the File

The To File block Decimation and Sample Time parameters control when data is written to the file.

Saving Data for Use by a From File Block

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.

Saving Data for Use by a From Workspace Block

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.

Simulation Stepper Interaction with To File Block

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 of To File blocks in a Referenced Model

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 General Reusability Limitations for more information.

Compressing MAT-File Data

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.

Saving Bus Data

The To File block supports virtual and nonvirtual bus input.

To save bus data, set the Save format parameter to Timeseries.

If the input signal is a bus, then the To File block creates a MATLAB structure that matches the bus hierarchy. Each leaf of the structure is a MATLAB timeseries object.

Pausing a 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.

Data Type Support

The To File block accepts real or complex signal data of any data type that Simulink supports, with the exception that the word length for fixed-point data must be 32 bits or less.

The To File block accepts bus data.

Parameters and Dialog Box

File name

The path or file name of the MAT-file in which to store the output. On UNIX® systems, the pathname 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 stores the file in the MATLAB working folder. (To determine the working folder, type pwd at the MATLAB command line.) If the file already exists, Simulink overwrites it.

Variable name

The name of the matrix contained in the named file. The default name is ans.

Save format

The data format that the To File block uses for writing data:

  • Timeseries (default)

  • Array

Decimation

The decimation factor, n, where n specifies writing data at every nth time that the block executes. The default decimation is 1, which writes data at every time step.

Sample time

Specifies the sample period and offset at which to collect points. This parameter is useful when you are using a variable-step solver where the interval between time steps might not be constant. The default is-1, which inherits the sample time from the driving block. See Specify Sample Time for more information.

Characteristics

Sample Time

Specified in the Sample time parameter

Dimensionalized

Yes

Was this topic helpful?