Main Content

shapespectrum

Generate waveform with desired frequency spectrum shape

Since R2024b

collapse all in page

    Syntax

    Y = shapespectrum(ds,X)
    Y = shapespectrum(ds,X,Magnitude=mag)
    Y = shapespectrum(ds,X,DesiredSpectrumRange=dsr)
    Y = shapespectrum(ds,X,MaxIterations=maxiters)
    Y = shapespectrum(ds,X,SpectrumRMSEThreshold=rmse)
    [Y,info] = shapespectrum(___)
    shapespectrum(___)

    Description

    Generate waveform with a desired frequency spectrum shape.

    Y = shapespectrum(ds,X) generates a waveform Y with a desired frequency spectrum shape, ds. The input X specifies an initial waveform whose spectrum is modified to achieve the desired spectral shape. The magnitude of the waveform Y in the time-domain is constrained to equal the magnitude of the initial waveform X in the time-domain.

    Y = shapespectrum(ds,X,Magnitude=mag) specifies the time-domain magnitudes, mag, of the output waveform Y. The absolute value of Y is exactly equal to mag. If no value is specified, the magnitude of X is used as a default.

    Y = shapespectrum(ds,X,DesiredSpectrumRange=dsr) also specifies the range, dsr, of the desired spectrum ds.

    example

    Y = shapespectrum(ds,X,MaxIterations=maxiters) specifies the maximum number of iterations,maxiters, performed.

    Y = shapespectrum(ds,X,SpectrumRMSEThreshold=rmse) specifies the acceptable root-mean-square error (RMSE), rmse, between the desired spectrum and the actual spectrum.

    [Y,info] = shapespectrum(___) also returns the info struct containing additional information about the returned waveform Y, and the algorithm used to generate the waveform.

    shapespectrum(___) plots the output waveform magnitude and spectrum.

    example

    Examples

    collapse all

    Open Live Script

    Use the shapespectrum function to create a waveform with a gaussian spectrum.

    Create a 100-sample waveform with random phases.

    nsamp = 100;
x = exp(1i*2*pi*rand(nsamp,1));

    Create and plot a gaussian spectrum (in dB).

    linspectrum = gausswin(nsamp);
spectrum = mag2db(linspectrum);
[y,info] = shapespectrum(spectrum,x,DesiredSpectrumRange="centered");

    Plot the waveform with a centered spectrum.

    shapespectrum(spectrum,x,DesiredSpectrumRange="centered")

    Figure contains 3 axes objects. Axes object 1 with title Frequency Spectrum (RMSE = 0.2019), xlabel Normalized Frequency (fs), ylabel Magnitude (dB) contains 3 objects of type line. These objects represent Initial, Final, Desired Shape. Axes object 2 with title Time Domain Magnitude, xlabel Normalized Time (1/fs), ylabel Magnitude contains 3 objects of type line. These objects represent Initial, Final, Required. Axes object 3 with title Time Domain Phase, xlabel Normalized Time (1/fs), ylabel Phase (Degrees) contains 2 objects of type line. These objects represent Initial, Final.

    Input Arguments

    collapse all

    Desired spectrum shape of output waveform Y, specified as an N-by-1 real-valued vector or N-by-2 real-valued matrix where N≥3.

    The magnitude of the values in the desired spectrum shape are scaled so that the power in the desired spectrum matches the power in the output waveform.

    • If ds is an N-by-1 real-valued vector, the function fits output waveform spectrum magnitude to the desired spectrum shape.

    • If ds is an N-by-2 real-valued matrix, the first column is the lower bound of the desired spectrum shape and the second column is the upper bound of the desired spectrum shape. The function fits the output waveform so that the spectrum does not fall below the lower bound or exceed the upper bound. The output is not guaranteed to converge to the desired spectrum.

    Spectrum shape units are in dB.

    Data Types: single | double

    Initial waveform, specified as a complex-valued N-by-1 vector. X specifies the initial waveform whose spectrum is modified to achieve the desired spectral shape.

    Data Types: single | double
    Complex Number Support: Yes

    Magnitude of the output waveform Y in the time domain, specified as a real-valued N-by-1 vector. This means that the absolute value of Y is exactly equal to mag,. If no value is specified, the magnitude of X is used as a default. Use this argument with the Magnitude Name-value pair. Units are linear units.

    Example: Magnitude=mag

    Data Types: single | double

    Spectrum range, specified as "twosided" or "centered". The following options are available:

    • "twosided" – creates a two-sided spectrum which spans the normalized frequency range [0,1).

    • "centered" – creates a centered spectrum which spans the normalized frequency range [-0.5,0.5) for an even number of samples and (-0.5,0.5) for an odd number of samples.

    Use this argument with the DesiredSpectrumRange Name-value pair.

    Example: DesiredSpectrumRange="centered"

    Maximum number of iterations, specified as a positive integer. A higher number of iterations means that the function outputs a waveform with a frequency spectrum more closely matched to the desired spectrum. Use this argument with the MaxIterations Name-value pair.

    Example: MaxIterations=maxiters

    Data Types: single | double

    Acceptable root-mean-square error (RMSE) between the desired spectrum and the actual spectrum, specified as a nonnegative scalar. If a lower and upper bound are specified, any spectral sample in between those bounds has an error of zero. If the threshold rmse is reached, the algorithm stops iterating before maxiters is reached. Use this argument with the SpectrumRMSEThreshold Name-value pair.

    Example: SpectrumRMSEThreshold=rmse

    Data Types: single | double

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: DesiredSpectrumRange="centered"

    Time-domain magnitude of the output waveform set using the mag input argument.

    Desired spectrum range of the output waveform set using the dsr input argument.

    Maximum number of iterations set using the maxiters input argument.

    Acceptable root-mean-square error (RMSE) between the desired spectrum and the actual spectrum set using the rmse input argument.

    Output Arguments

    collapse all

    Output waveform with desired frequency shape, returned as a complex-valued N-by-1 vector.

    Data Types: single | double

    Waveform information, returned as a struct. The fields of the struct are:

    • InitialWaveform – Initial waveform used to produce the final waveform.

    • NumIterations – Number of iteration steps taken to produce the final waveform.

    • SpectrumRMSEThreshold – Spectrum RMSE threshold value used as a stopping criteria.

    • SpectrumRMSEFinal – Best RMSE value achieved by the iterative algorithm.

    • DesiredSpectrumScaling – Scaling factor used to scale desired spectrum shape input magnitude to the same level as the actual signal spectrum magnitude, but does not change the shape of the desired spectrum.

    • ExitFlag – Reason for stopping the iterative algorithm.

      • 0 – Indicates that the algorithm stopped because the maximum number of iterations was reached.

      • 1 – Indicates that the error threshold was achieved.

    Data Types: struct

    References

    [1] Rowe, William, et al. “Spectrally Constrained Waveform Design [Sp Tips&Tricks].” IEEE Signal Processing Magazine, vol. 31, no. 3, May 2014, pp. 157–62. DOI.org (Crossref), https://doi.org/10.1109/MSP.2014.2301792.

    [2] Jakabosky, John, et al. “Spectral-Shape Optimized FM Noise Radar for Pulse Agility.” 2016 IEEE Radar Conference (RadarConf), IEEE, 2016, pp. 1–6. DOI.org (Crossref), https://doi.org/10.1109/RADAR.2016.7485298.

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Version History

    Introduced in R2024b

    See Also

    Topics