SparseZeroPoleTruncationOptions

Options for model order reduction with zero-pole truncation

Since R2025a

Description

This object contains model order reduction options of zero-pole truncation and is contained in the Options property of a SparseZeroPoleTruncation object R created using reducespec. To configure these options, use dot notation, for example, R.Options.Focus = [0,15].

Properties

UseParallel — Option to perform computation in parallel

"off" (default) | "auto" | "on"

Option to perform zero-pole computations in parallel using a parallel pool of workers, specified as one of these values:

• "off" — Run in serial on the MATLAB^® client. Enabling parallel computing may result in improved performance during zero-pole computation. However, even with UseParallel set to "off", the algorithm can use built-in multithreading to make best use of the local resources. For more information, see MATLAB Multicore.

• "auto" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, run in serial on the MATLAB client.

• "on" — Use a parallel pool if one is open or if MATLAB can automatically create one. If a parallel pool is not available, throw an error.

If you do not have a parallel pool open and automatic pool creation is enabled, MATLAB opens a pool using the default cluster profile. To use a parallel pool to run computations in MATLAB, you must have Parallel Computing Toolbox™. For more information, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Before R2026a: To run in parallel , set UseParallel to true (1).

Focus — Frequency range of interest

[0 Inf] (default) | vector

Frequency range of interest, specified as a vector of form [0,fmax]. When you specify a frequency range of focus, the algorithm computes only the poles with natural frequency in this range. For discrete-time models, the software approximates the equivalent natural frequency through Tustin transform.

Since this method computes all poles and zeros in the specified frequency range, you typically specify a low-frequency range to limit computing a large number of poles and zeros. By default, the focus is unspecified ([0 Inf]) and the algorithm computes up to MaxNumber poles and zeros.

MaxNumber — Maximum number of poles and zeros to compute

1000 (default) | positive integer

Maximum number of poles and zeros to compute, specified as a positive integer. This value limits the number of poles and zeros computed by the algorithm and the order of the approximation of the original sparse model.

Shift — Spectral shift

0 (default) | finite scalar

Spectral shift, specified as a finite scalar.

The software computes poles with the natural frequency in the specified range [0,fmax] using inverse power iterations for A-sigma*E, which obtains eigenvalues closest to the shift sigma. When A is singular and sigma is zero, the algorithm fails as no inverse exists. Therefore, for sparse models with integral action (s = 0 or at z = 1 for discrete-time models), you can use this option to implicitly shift poles or zeros to the value closest to this shift value. Specify a shift value that is not equal to an existing pole or zero value of the original model.

Tolerance — Accuracy of computed poles

1e-12 (default) | positive finite scalar

Tolerance for accuracy of computed poles, specified as a positive finite scalar. This value controls the convergence of computed eigenvalues in inverse power iterations.

Display — Show or hide progress report

"on" (default) | "off"

Show or hide progress report, specified as either "off" or "on".

Version History

Introduced in R2025a

R2026a: Enhanced control over parallel execution with UseParallel option

The UseParallel option now accepts "off", "auto", or "on" values instead of true or false. This change gives you more control over when to use a parallel pool for parallel execution.

Specifying the UseParallel option as true or false is not recommended.

This table shows how to update your code depending on your goal.

Goal	Not recommended	Recommended
Write code that runs on the MATLAB client and uses built-in multithreading to make best use of the local resources.	R.Options.UseParallel=false	R.Options.UseParallel="off" (default)
Write portable code that runs on a parallel pool and, if a pool is not available, runs on the MATLAB client.	R.Options.UseParallel=true	R.Options.UseParallel="auto"
Write code that runs on a parallel pool and errors if a pool is not available.	N/A	R.Options.UseParallel="on"

There are no plans to remove support for the true or false values.