dspunfold - Generates a multi-threaded MEX file from a MATLAB function - MATLAB (original) (raw)

Generates a multi-threaded MEX file from a MATLAB function

Syntax

Description

dspunfold [file](#buxgz0h-1-file) generates a multi-threaded MEX file from the entry-point MATLAB® function specified by file, using the unfolding technology. Unfolding is a technique to improve throughput through parallelization. The multi-threaded MEX file leverages the multicore CPU architecture of the host computer and can improve speed significantly. In addition to the multi-threaded MEX file, the function generates a single-threaded MEX file, a self-diagnostic analyzer function, and the corresponding help files.

dspunfold [options](#buxgz0h-1-options) [file](#buxgz0h-1-file) generates a multi-threaded MEX file from the entry-point MATLAB function specified by file, using the function arguments specified by options.

Note

This function requires a MATLAB Coder™ license.

Input Arguments

collapse all

Entry-point MATLAB function from which dspunfold generates the multi-threaded MEX file. The function must support code generation.

Example: dspunfold fcn -args {randn(10,1),randn(10,2),randn(20,1)}

fcn is the entry-point MATLAB function and {randn(10,1),randn(10,2),randn(20,1)} are its input arguments.

Output Files

When you invoke dspunfold on an entry-point MATLAB function, dspunfold generates the following files.

Limitations

General Limitations:

• On Windows and Linux, you must use a compiler that supports the Open Multiprocessing (OpenMP) application interface. See Supported Compilers.
• If you have a macOS with an Xcode version 12.0 or later, using the dspunfold function is not supported.
• If the input MATLAB function has runtime errors, the errors are not caught when you run the multi-threaded MEX file. Before you use the dspunfold function, callcodegen on the MATLAB function and make sure that the MEX file is generated successfully.
• If the generated code uses a large amount of memory to store the local variables, around 4 MB on Windows platform, the generated multi-threaded MEX file can have unexpected behavior. This limit varies with each platform. As a workaround, reduce the size of the input signals or restructure the MATLAB function to use less local memory.
• dspunfold does not support:
  • varargin and varargout inside the MATLAB function
  • Variable-size inputs and outputs
  • Input signals with an arbitrary frame length to System objects that use theDecimationFactor property. The input signal is considered to have an arbitrary frame length when its frame length is not a multiple of the decimation factor. When this is the case, the output of the object in the generated code is a variable-size signal, and dspunfold does not support variable-size output signals.
    In the case of the dsp.FarrowRateConverter object, you can determine the decimation factor using the getRateChangeFactors function.
  • P-coded entry-point MATLAB functions
  • Cell arrays as inputs and outputs

Analyzer Limitations:

The following limitations apply to the analyzer function generated by thedspunfold function. For more information on the analyzer function, see 'Self-Diagnostic Analyzer’ in the 'More About' section of dspunfold.

• If multiple frames of the analyzer input are identical, the analyzer might throw false positive pass results. It is recommended that you provide at least two different frames for each input of the analyzer.
• If the algorithm in the entry-point MATLAB function chooses its state length based on the input values, the analyzer might provide different pass results for different input values. For an example, see the FIR_Mean function in Why Does the Analyzer Choose the Wrong State Length?.
• If the input to the entry-point MATLAB function does affect the output immediately, the analyzer might throw false positive pass results. For an example, see theInput_Output function in Why Does the Analyzer Choose a Zero State Length?.
• If the output results of the multi-threaded MEX file and single-threaded MEX file match statistically but do not match numerically, the analyzer does not pass. Consider theFilterNoise function that follows, which filters a random noise signal with an FIR filter. The function calls randn from within itself to generate random noise. Hence, the output results of theFilterNoise function match statistically but not match numerically.
  function Output = FilterNoise(x)
  persistent FIRFilter
  if isempty(FIRFilter)
  FIRFilter = dsp.FIRFilter('Numerator',fir1(12,0.4));
  end
  Output = FIRFilter(x+randn(1000,1));
  end
  When you run the automatic state length detection tool run on FilterNoise, the tool detects an infinite state length. Because the tool cannot find a numerical match for a finite state length, it chooses an infinite state length.
  dspunfold FilterNoise -args {randn(1000,1)} -s auto
  Analyzing input MATLAB function FilterNoise
  Creating single-threaded MEX file FilterNoise_st.mexw64
  Searching for minimal state length (this might take a while)
  Checking stateless ... Insufficient
  Checking 1 ... Insufficient
  Checking Infinite ... Sufficient
  Checking 2 ... Insufficient
  Minimal state length is Inf
  Creating multi-threaded MEX file FilterNoise_mt.mexw64
  Warning: The multi-threading was disabled due to performance considerations.
  This happens when the state length is greater than or
  equal to (Threads-1)*Repetition frames (3 frames in this case).

  In coder.internal.warning (line 8)
  In unfoldingEngine/BuildParallelSolution (line 25)
  In unfoldingEngine/generate (line 207)
  In dspunfold (line 234)
  Creating analyzer file FilterNoise_analyzer
  The algorithm does not need an infinite state. The state length of the FIR filter, hence the algorithm is 12.
  Call dspunfold with state length set to 12.
  dspunfold FilterNoise -args {randn(1000,1)} -s 12 -f true
  Analyzing input MATLAB function FilterNoise
  Creating single-threaded MEX file FilterNoise_st.mexw64
  Creating multi-threaded MEX file FilterNoise_mt.mexw64
  Creating analyzer file FilterNoise_analyzer
  Run the analyzer function.
  FilterNoise_analyzer(randn(1000*4,1))
  Analyzing multi-threaded MEX file FilterNoise_mt.mexw64 ...
  Latency = 8 frames
  Speedup = 0.5x
  Warning: The output results of the multi-threaded MEX file FilterNoise_mt.mexw64 do not
  match the output results of the single-threaded MEX file FilterNoise_st.mexw64. Check that
  you provided the correct state length value to the dspunfold function when you generated the
  multi-threaded MEX file FilterNoise_mt.mexw64. For best practices and possible solutions to
  this problem, see the 'Tips' section in the dspunfold function reference page.
  In coder.internal.warning (line 8)
  In FilterNoise_analyzer
  ans =
  Latency: 8
  Speedup: 0.4970
  Pass: 0

The analyzer looks for a numerical match and fails the verification, even though the generated multi-threaded MEX file is valid.

Speedup Limitations:

• If the entry-point MATLAB function contains code with low complexity, MATLAB overhead or multi-threaded MEX overhead overshadow any performance gains. In such cases, do not use dspunfold.
• If the number of operations in the input MATLAB function is small compared to the size of the input or output data, the multi-threaded MEX file does not provide any speedup gain. Sometimes, it can result in a speedup loss, even if the repetition value is increased. In such cases, do not usedspunfold.

More About

collapse all

State length of the algorithm.

Most of the time, the state length used by dspunfold matches the state length of the algorithm in the entry-point MATLAB function. If the algorithm is simple, state length is easy to determine. For example, the state length of an FIR filter is the number of taps in the filter –1. In some scenarios, to optimize speedup, dspunfold chooses a state length that is different from the algorithm state length or the state length specified using the -s option. For example, when the state length is greater than (threads – 1) ×repetition frames, dspunfold considers the state length to be infinite. Also, multi-threading gets disabled due to performance considerations.

You can automatically detect the minimum state length for which the outputs of the multi-threaded MEX and single-threaded MEX match.

In complex algorithms, it is not easy to determine the state length analytically. In such scenarios, use the analyzer to compute the state length. When you set-s to auto, dspunfold invokes the analyzer. The analyzer computes the outputs for different state lengths and detects the minimum state length for which the outputs of the multi-threaded MEX file and single-threaded MEX file match. The analyzer uses the numeric value of the inputs given to-args. To detect the most efficient state length, provide random inputs to -args. In this mode, you cannot input coder.typeof to arguments. Due to the extra analysis this tool requires, the time to generate the MEX file increases.

When you use automatic state length detection on an algorithm with code paths that depend on the input values, use inputs that choose the code path with the longest state length. Also, the inputs must have an immediate effect on the output. If inputs choose a code path that triggers runtime errors, automatic state length detection stops, and so does the analyzer. Make sure that the MATLAB function supports code generation and does not have run-time errors for the inputs under test. Before invoking dspunfold, callcodegen on the entry-point MATLAB function. In addition, simulate the entry-point MATLAB function to make sure it has no run-time errors.

The -t option specifies the number of threads used by the multi-threaded MEX file.

Increasing this value can improve the multi-threaded MEX speedup, at the cost of a larger latency. Decreasing this value reduces the latency and potentially decreases the multi-threaded MEX speedup.

Repetition factor is the number of consecutive frames processed by each thread in one processing step.

Increasing this value reduces the overhead per frame of data, potentially improving the speedup at the cost of larger latency. Decreasing this value reduces the latency, and potentially decreases the multi-threaded MEX speedup.

The self-diagnostic analyzer function is a help tool that is generated with the MEX file. This function measures the speedup gain of the multi-threaded MEX file compared to the single-threaded MEX file. The analyzer function also verifies that the outputs of the multi-threaded MEX file and single-threaded MEX file match.

If you specify an incorrect state length value, the outputs usually do not match. To check for the numerical match between the multi-threaded MEX file and the single-threaded MEX file, provide at least two different frames for each input argument of the analyzer. The frames are appended along the first dimension. The analyzer alternates between these frames while verifying that the outputs match. Failure to provide multiple frames for each input can decrease the effectiveness of the analyzer and can lead to false positive verification results. In other words, the analyzer might produce pass = 1 results even when an incorrect state length value is specified. The analyzer alternates through a maximum of 3 × (2 ×threads × repetition) frames. If your algorithm requires more than 3 × (2 × threads ×repetition) frames to verify the results, then the analyzer cannot verify accurately.

Tips

General

• Do not display plots, scopes, or execute other user interface operations from within the multi-threaded MEX file. The generated MEX file can have unexpected behavior.
• Do not use coder.extrinsic inside the input MATLAB function. The generated MEX file can have unexpected behavior.

When the state length is less than or equal to (threads – 1) × repetition frames:

• Do not use a random number inside the MATLAB function. The outputs of the single-threaded MEX file and the multi-threaded MEX file might not match. Also, the outputs of the consecutive executions of the multi-threaded MEX file might not match. The analyzer might not pass the numerical match verification.
  It is recommended that you generate the random number outside the entry-point MATLAB function and pass it as an argument to the function.
• Do not use global or persistent variables anywhere other than in the entry-point MATLAB function. For example, avoid using persistent variables in subfunctions. The generated MEX file can produce inaccurate results. In general, global variables are not recommended.
• Do not access I/O resources from within the multi-threaded MEX file. The generated MEX file can have unexpected behavior. These resources include file writers and readers, UDP sockets, and audio players and recorders.
• Do not use functions with interactive inputs (for example, the keyboard) inside the multi-threaded MEX file. The generated MEX file can have unexpected behavior.

Workflow

• To generate a valid multi-threaded MEX file with the required speedup and latency, follow the Workflow for Generating a Multithreaded MEX File using dspunfold.
• Before using dspunfold, call codegen on the entry-point MATLAB function and make sure that the function generates a MEX file successfully.
• After generating the multi-threaded MEX file using dspunfold, run the analyzer function. Make sure that the analyzer function passes. The exception to this rule is when the algorithm produces results that match statistically, but not numerically. In this exception, the analyzer function does not pass, even though thedspunfold function generates a valid multi-threaded MEX file. See 'Analyzer Limitations' for an example.
• For help on using the MEX file and analyzer, at the MATLAB command prompt, enter help _`<mexfile name>`_ and help _`<analyzer name>`_.

State Length

• If you choose a state length that is greater than or equal to the value of the exact state length, the analyzer passes. If the analyzer fails, increase the state length, regenerate the MEX file, and verify again.
• If the state length is greater than 0, the inputs marked as frames (through -f option) must all have the same dimensions.
• When generating the MEX file and running the analyzer, use inputs that invoke the same state length.

Automatic State Length Detection

When you set -s to auto:

• If the algorithm in the entry-point MATLAB function chooses a code path based on the input values, use inputs that choose the code path with the longest state length.
• Provide random inputs to -args.
• Choose inputs that have an immediate effect on the output. See Why Does the Analyzer Choose a Zero State Length?.

Analyzer

• Make sure the outputs of the multi-threaded MEX file and the single-threaded MEX file do not contain NaN or an Inf. The analyzer cannot do numeric checks and returns pass as false. The automatic state length detection tool detects infinite state length and displays a warning
  Warning
  The output results of the multi-threaded MEX file do not match the output results of the single-threaded MEX file even for Infinite state length. A possible reason is that input MATLAB function generates different output results between consecutive runs even for the same input values.
• Provide multiple frames with different values for each input of the analyzer. To improve the analyzer effectiveness, append successive frames along the first dimension.
• Provide inputs to the analyzer that lead to efficient code coverage.

Speedup

• To improve the speedup of the multi-threaded MEX file, specify the exact state length in samples. You can specify the state length in samples by setting at least one entry offrameinputs to true. The use of samples reduces the overhead and increases the speedup.
• To increase the speedup at the cost of larger latency, you can:
  • Increase the repetition factor. Use the -r option.
  • Increase the number of threads. Use the -t option.
• For each input that can be divided into samples without altering the algorithm behavior, set frame status to true using the -f option. The input is then considered in samples, which can increase the speedup of the generated multi-threaded MEX file.

Algorithms

The multi-threaded MEX file buffers multiple-input signal frames into a buffer of2 × threads × repetition frames, where threads is the number of threads, and_repetition_ is the repetition factor. The MEX file processes these frames simultaneously, using multiple cores. This process introduces some deterministic latency, where latency = 2 × threads × repetition. Latency is traded off with the speedup you might gain by increasing the number of threads or the repetition factor.

Version History

Introduced in R2015b

See Also

Topics

• Multithreaded MEX File Generation
• How Is dspunfold Different from parfor?
• Workflow for Generating a Multithreaded MEX File using dspunfold
• Why Does the Analyzer Choose the Wrong State Length?
• Why Does the Analyzer Choose a Zero State Length?
• MATLAB Algorithm Acceleration (MATLAB Coder)