NicholsPlot - Plot Nichols frequency response of dynamic system (2024)

Table of Contents
Description Creation Syntax Description Input Arguments sys — Dynamic systemdynamic system model | model array LineSpec — Line style, marker, and color string | character vector w — Frequencies {wmin,wmax} | vector | [] plotoptions — Nichols plot options nicholsoptions object parent — Parent container Figure object (default) | TiledChartLayout object | UIFigure object | UIGridLayout object | UIPanel object | UITab object Properties Responses — Model responses NicholsResponse object | array of NicholsResponse objects SourceData — Source datastructure Model — Dynamic systemdynamic system model | model array FrequencySpec — Frequencies{wmin,wmax} | vector | [] Name — Response name string | character vector Visible — Response visibility"on" (default) | on/off logical value LegendDisplay — Option to list response in legend"on" (default) | on/off logical value MarkerStyle — Marker style"none" | "o" | "+" | "*" | "." | ... Color — Plot colorRGB triplet | hexadecimal color code | color name LineStyle — Line style"-" | "--" | ":" | "-." MarkerSize — Marker sizepositive scalar LineWidth — Line widthpositive scalar Characteristics — Response characteristics CharacteristicsManager object FrequencyPeakResponse — Visibility of peak response CharacteristicOption object Visible — Peak response visibility "off" (default) | on/off logical value AllStabilityMargins — Visibility of all stability marginsCharacteristicOption object Visible — Margin visibility "off" (default) | on/off logical value MinimumStabilityMargins — Visibility of minimum stability marginsCharacteristicOption object Visible — Margin visibility "off" (default) | on/off logical value FrequencyUnit — Frequency units "rad/s" | "Hz" | "rpm" | ... MagnitudeUnit — Magnitude units "dB" | "abs" PhaseUnit — Phase units "deg" | "rad" PhaseWrappingEnabled — Option to enable phase wrapping on/off logical value PhaseWrappingBranch — Lower limit of phase-wrapping range scalar PhaseMatchingEnabled — Option to enable phase matching "off" (default) | on/off logical value PhaseMatchingFrequency — Phase matching frequency 0 (default) | scalar PhaseMatchingValue — Phase matching response value 0 (default) | scalar MinimumGainEnabled — Option to enable minimum gain "off" (default) | on/off logical value MinimumGainValue — Minimum gain value 0 (default) | scalar Visible — Chart visibility "on" (default) | on/off logical value IOGrouping — Grouping of inputs and outputs pairs "none" (default) | "inputs" | "outputs" | "all" InputVisible — Option to display inputs on/off logical value | array of on/off logical values OutputVisible — Option to display outputs on/off logical value | array of on/off logical values Object Functions Examples Customize Nichols Plot Custom Nichols Plot Settings Independent of Preferences Customized Nichols Plot of Transfer Function Customized Nichols Plot of MIMO System Nichols Response of Identified Parametric and Nonparametric Models Version History R2024b: Improved customization workflows and integration with MATLAB plotting tools See Also Topics MATLAB Command Americas Europe Asia Pacific References

Plot Nichols frequency response of dynamic system

expand all in page

    Description

    The nicholsplot function plots the Nichols response of a dynamic system model and returns a NicholsPlot chart object. To customize the plot, modify the properties of the chart object using dot notation. For more information, see Customize Linear Analysis Plots at Command Line.

    To obtain frequency response data, use nichols.

    Creation

    Syntax

    np = nicholsplot(sys)

    np = nicholsplot(sys1,sys2,...,sysN)

    np = nicholsplot(sys1,LineSpec1,...,sysN,LineSpecN)

    np = nicholsplot(___,w)

    np = nicholsplot(___,plotoptions)

    np = nicholsplot(parent,___)

    Description

    np = nicholsplot(sys) plots the frequency Nichols response of the dynamic system model sys and returns the corresponding chart object.

    If sys is a multi-input, multi-output (MIMO) model, then nicholsplot produces a grid of Nichols plots with each plot displaying the frequency response of one input-output pair.

    If sys is a model with complex coefficients, then nicholsplot shows a contour comprised of both positive and negative frequencies. For models with real coefficients, nicholsplot shows only positive frequencies.

    example

    np = nicholsplot(sys1,sys2,...,sysN) plots the Nichols frequency response of multiple dynamic systems sys1,sys2,…,sysN on the same plot. All systems must have the same number of inputs and outputs to use this syntax.

    example

    np = nicholsplot(sys1,LineSpec1,...,sysN,LineSpecN) sets the line style, marker type, and color for the Nichols response of each system.

    example

    np = nicholsplot(___,w) plots Nichols responses for frequencies specified in w. You can specify a frequency range or a vector of frequencies. You can use w with any of the previous syntaxes.

    You can use w with any of the input-argument combinations in previous syntaxes.

    See logspace to generate logarithmically spaced frequency vectors.

    example

    np = nicholsplot(___,plotoptions) plots the Nichols frequency response with the plotting options specified in plotoptions. Settings you specify in plotoptions override the plotting preferences for the current MATLAB® session. This syntax is useful when you want to write a script to generate multiple plots that look the same regardless of the local preferences.

    example

    np = nicholsplot(parent,___) plots the Nichols response in the specified parent graphics container, such as a Figure or TiledChartLayout, and sets the Parent property. Use this syntax when you want to create a plot in a specified open figure or when creating apps in App Designer.

    Input Arguments

    expand all

    Dynamic system, specified as a SISO or MIMO dynamic system model or array of dynamic system models. Dynamic systems that you can use include:

    • Continuous-time or discrete-time numeric LTI models, such as tf, zpk, or ss models.

    • Sparse state-space models, such as sparss or mechss models. Frequency grid w must be specified for sparse models.

    • Generalized or uncertain LTI models such as genss or uss (Robust Control Toolbox) models. Using uncertain models requires Robust Control Toolbox™ software.

      • For tunable control design blocks, the function evaluates the model at its current value to plot the response.

      • For uncertain control design blocks, the function plots the nominal value and random samples of the model.

    • Frequency-response data models such as frd models. For such models, the function plots the response at the frequencies defined in the model.

    • Identified LTI models, such as idtf (System Identification Toolbox), idss (System Identification Toolbox), or idproc (System Identification Toolbox) models. Using identified models requires System Identification Toolbox™ software.

    If sys is an array of models, the plot shows responses of all models in the array on the same axes.

    Line style, marker, and color, specified as a string or character vector containing symbols. The symbols can appear in any order. You do not need to specify all three characteristics (line style, marker, and color). For example, if you omit the line style and specify the marker, then the plot shows only the marker and no line.

    Example: '--or' is a red dashed line with circle markers

    Line StyleDescription
    "-"Solid line
    "--"Dashed line
    ":"Dotted line
    "-."Dash-dotted line
    MarkerDescription
    "o"Circle
    "+"Plus sign
    "*"Asterisk
    "."Point
    "x"Cross
    "_"Horizontal line
    "|"Vertical line
    "s"Square
    "d"Diamond
    "^"Upward-pointing triangle
    "v"Downward-pointing triangle
    ">"Right-pointing triangle
    "<"Left-pointing triangle
    "p"Pentagram
    "h"Hexagram
    ColorDescription
    "r"red
    "g"green
    "b"blue
    "c"cyan
    "m"magenta
    "y"yellow
    "k"black
    "w"white

    Frequencies at which to compute and plot frequency response, specified as the cell array {wmin,wmax} or as a vector of frequency values.

    • If w is a cell array of the form {wmin,wmax}, then the function computes the response at frequencies ranging between wmin and wmax.

    • If w is a vector of frequencies, then the function computes the response at each specified frequency. For example, use logspace to generate a row vector with logarithmically spaced frequency values. The vector w can contain both positive and negative frequencies.

    • [] — Automatically select frequencies based on system dynamics.

    For models with complex coefficients, if you specify a frequency range of [wmin,wmax] for your plot, then the plot shows a contour comprised of both positive frequencies [wmin,wmax] and negative frequencies [–wmax,–wmin].

    Specify frequencies in units of rad/TimeUnit, where TimeUnit is the TimeUnit property of the model.

    Nichols plot options, specified as a nicholsoptions object. You can use these options to customize the Nichols plot appearance. Settings you specify in plotoptions override the preference settings for the current MATLAB session.

    Parent container of the chart, specified as one of the following objects:

    • Figure

    • TiledChartLayout

    • UIFigure

    • UIGridLayout

    • UIPanel

    • UITab

    Properties

    expand all

    Note

    The properties listed here are only a subset. For a complete list, see NicholsPlot Properties.

    Model responses, specified as a NicholsResponse object or an array of such objects. Use this property to modify the dynamic system model or appearance for each response in the plot. Each NicholsResponse object has the following fields.

    Source data for the response, specified as a structure with the following fields.

    Dynamic system, specified as a SISO or MIMO dynamic system model or array of dynamic system models.

    When you initially create a plot, Model matches the value you specify for sys.

    Frequencies at which to compute the response, specified as one of the following:

    Specify frequencies in units of rad/TimeUnit, where TimeUnit is the TimeUnit property of the model.

    When you initially create a plot:

    • FrequencySpec matches the value you specify for the w argument.

    • If you do not specify w, FrequencySpec is empty and frequencies are selected based on the system dynamics.

    Response name, specified as a string or character vector and stored as a string.

    Response visibility, specified as one of the following logical on/off values:

    • "on", 1, or true — Display the response in the plot.

    • "off", 0, or false — Do not display the response in the plot.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Option to list response in legend, specified as one of the following logical on/off values:

    • "on", 1, or true — List the response in the legend.

    • "off", 0, or false — Do not list the response in the legend.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Marker style, specified as one of the following values.

    MarkerDescription
    "none"No marker
    "o"Circle
    "+"Plus sign
    "*"Asterisk
    "."Point
    "x"Cross
    "_"Horizontal line
    "|"Vertical line
    "s"Square
    "d"Diamond
    "^"Upward-pointing triangle
    "v"Downward-pointing triangle
    ">"Right-pointing triangle
    "<"Left-pointing triangle
    "p"Pentagram
    "h"Hexagram

    Plot color, specified as an RGB triplet or a hexadecimal color code and stored as an RGB triplet.

    Alternatively, you can specify some common colors by name. The following table lists these colors and their corresponding RGB triplets and hexadecimal color codes.

    Color NameRGB TripletHexadecimal Color Code

    "red" or "r"

    [1 0 0]#FF0000

    "green" or "g"

    [0 1 0]#00FF00

    "blue" or "b"

    [0 0 1]#0000FF

    "cyan" or "c"

    [0 1 1]#00FFFF

    "magenta" or "m"

    [1 0 1]#FF00FF

    "yellow" or "y"

    [1 1 0]#FFFF00

    "black" or "k"

    [0 0 0]#000000

    "white" or "w"

    [1 1 1]#FFFFFF

    Line style, specified as one of the following values.

    Line StyleDescription
    "-"Solid line
    "--"Dashed line
    ":"Dotted line
    "-."Dash-dotted line

    Marker size, specified as a positive scalar.

    Line width, specified as a positive scalar.

    Response characteristics to display in the plot, specified as a CharacteristicsManager object with the following properties.

    Visibility of peak response in plot, specified as a CharacteristicOption object with the following property.

    Peak response visibility, specified as one of the following logical on/off values:

    • "on", 1, or true — Display the peak response.

    • "off", 0, or false — Do not display the peak response.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Visibility of all stability margins, specified as a CharacteristicOption object with the following property.

    Margin visibility, specified as one of the following logical on/off values:

    • "on", 1, or true — Display the margins.

    • "off", 0, or false — Do not display the margins.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Visibility of minimum stability margins, specified as a CharacteristicOption object with the following property.

    Margin visibility, specified as one of the following logical on/off values:

    • "on", 1, or true — Display the margins.

    • "off", 0, or false — Do not display the margins.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Frequency units, specified as one of the following values:

    • "Hz"

    • "rad/s"

    • "rpm"

    • "kHz"

    • "MHz"

    • "GHz"

    • "rad/nanosecond"

    • "rad/microsecond"

    • "rad/millisecond"

    • "rad/minute"

    • "rad/hour"

    • "rad/day"

    • "rad/week"

    • "rad/month"

    • "rad/year"

    • "cycles/nanosecond"

    • "cycles/microsecond"

    • "cycles/millisecond"

    • "cycles/hour"

    • "cycles/day"

    • "cycles/week"

    • "cycles/month"

    • "cycles/year"

    Dependencies

    By default, the response uses the frequency units of the plotted linear system. You can override the default units by specifying toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Magnitude units, specified as one of the following:

    • "dB" — Decibels

    • "abs" — Absolute value

    Dependencies

    The default magnitude units depend on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Phase units, specified as one of the following:

    • "deg" — Degrees

    • "rad" — Radians

    Dependencies

    The default phase units depend on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Option to enable phase wrapping, specified as one of the following logical on/off values:

    • "on", 1, or true — Enable phase wrapping. The phase shown in the response wraps to remain in the range defined by PhaseWrappingBranch.

    • "off", 0, or false — Disable phase wrapping.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Dependencies

    • The default phase-wrapping configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    • When both phase wrapping and phase matching are enabled, the software performs the phase matching followed by the phase wrapping.

    Lower limit of phase-wrapping range, specified as a scalar value in degrees. The phase-wrapping range is [B,B+360), where B is equal to PhaseWrappingBranch.

    Dependencies

    • This value is ignored when PhaseMatchingEnabled is "off".

    • The default phase-wrapping configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Option to enable phase matching, specified as one of the following logical on/off values:

    • "on", 1, or true — Enable phase matching such that the phase response matches the value specified in PhaseMatchingValue at the frequency specified in PhaseMatchingFrequency. The remaining phase response shifts to maintain the same phase profile.

    • "off", 0, or false — Disable phase matching.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Dependencies

    When both phase wrapping and phase matching are enabled, the software performs the phase matching followed by the phase wrapping.

    Phase matching frequency, specified as a scalar.

    Dependencies

    This value is ignored when PhaseMatchingEnabled is "off".

    Phase matching response value, specified as a scalar.

    Dependencies

    This value is ignored when PhaseMatchingEnabled is "off".

    Option to enable minimum gain for plotting, specified as one of the following logical on/off values:

    • "on", 1, or true — Set the minimum gain for plotting to the MinimumGainValue property value.

    • "off", 0, or false — Set the minimum gain for plotting automatically based on the system dynamics.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Dependencies

    The default minimum-gain configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Minimum gain value for plotting, specified as a scalar.

    Dependencies

    • To apply the minimum gain value, set the MinimumGainEnabled property to "on".

    • The default minimum-gain configuration depends on the toolbox preferences. For more information, see Specify Toolbox Preferences for Linear Analysis Plots.

    Dependencies

    Chart visibility, specified as one of the following logical on/off values:

    • "on", 1, or true — Display the chart.

    • "off", 0, or false — Hide the chart without deleting it. You still can access the properties of chart when it is not visible.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

    Grouping of inputs and outputs pairs, specified as one of the following:

    • "none" — Do not group inputs or outputs.

    • "inputs" — Group only inputs.

    • "outputs" — Group only outputs.

    • "all" — Group all input-output pairs.

    Option to display inputs, specified as one of the following logical on/off values or an array of such values:

    • "on", 1, or true — Display the corresponding input.

    • "off", 0, or false — Hide the corresponding input.

    InputVisible is an array when the plotted system has multiple inputs. By default, all inputs are visible in the plot.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState or an array of such values.

    Option to display outputs, specified as one of the following logical on/off values or an array of such values:

    • "on", 1, or true — Display the corresponding output.

    • "off", 0, or false — Hide the corresponding output.

    OutputVisible is an array when the plotted system has multiple outputs. By default, all outputs are visible in the plot.

    The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState or an array of such values.

    Object Functions

    addResponseAdd dynamic system response to existing response plot
    showConfidence (System Identification Toolbox)Display confidence regions on response plots for identified models

    Examples

    collapse all

    Customize Nichols Plot

    Open Live Script

    For this example, use the plot handle to change the title, turn on the grid, and set axis limits.

    Generate a random state-space model with 5 states and create the Nichols plot with chart object np.

    rng("default")sys = rss(5);np = nicholsplot(sys);

    NicholsPlot - Plot Nichols frequency response of dynamic system (1)

    Change the title, enable the grid, and set axis limits.

    np.Title.String = "Nichols Frequency Response";xlim([-2 4])ylim([3.3 4.3])grid on

    NicholsPlot - Plot Nichols frequency response of dynamic system (2)

    Alternatively, you can also use the nicholsoptions command to specify the required plot options. First, create an options set based on the toolbox preferences.

    plotoptions = nicholsoptions('cstprefs');

    Change the desired properties of the options set.

    plotoptions.Title.String = 'Nichols Frequency Response';plotoptions.Grid = 'on';plotoptions.XLim = {[-2,4]};plotoptions.YLim = {[3.3,4.3]};nicholsplot(sys,plotoptions);

    NicholsPlot - Plot Nichols frequency response of dynamic system (3)

    Depending on your own toolbox preferences, the plot you obtain might look different from this plot. Only the properties that you set explicitly, in this example Title, Grid, XLim and YLim, override the toolbox preferences.

    Custom Nichols Plot Settings Independent of Preferences

    Open Live Script

    For this example, create a Nichols plot that uses 15-point red text for the title. This plot should look the same, regardless of the preferences of the MATLAB session in which it is generated.

    First, create a default options set using nicholsoptions.

    plotoptions = nicholsoptions;

    Next, change the required properties of the options set plotoptions.

    plotoptions.Title.FontSize = 15;plotoptions.Title.Color = [1 0 0];plotoptions.FreqUnits = 'Hz';plotoptions.Grid = 'on';

    Now, create a Nichols plot using the options set plotoptions.

    nicholsplot(tf(1,[1,1]),{0,15},plotoptions);

    NicholsPlot - Plot Nichols frequency response of dynamic system (4)

    Because plotoptions begins with a fixed set of options, the plot result is independent of the toolbox preferences of the MATLAB session.

    Customized Nichols Plot of Transfer Function

    Open Live Script

    For this example, create a Nichols plot of the following continuous-time SISO dynamic system. Then, turn the grid on and rename the plot.

    sys(s)=s2+0.1s+7.5s4+0.12s3+9s2.Continuous-time SISO dynamic system

    Create the transfer function sys.

    sys = tf([1 0.1 7.5],[1 0.12 9 0 0]);

    Next, create the options set using nicholsoptions and change the required plot properties.

    plotoptions = nicholsoptions;plotoptions.Grid = 'on';plotoptions.Title.String = 'Nichols Plot of Transfer Function';

    Now, create the Nichols plot with the custom option set plotoptions.

    nicholsplot(sys,plotoptions)

    NicholsPlot - Plot Nichols frequency response of dynamic system (5)

    nicholsplot automatically selects the plot range based on the system dynamics.

    Customized Nichols Plot of MIMO System

    Open Live Script

    For this example, consider a MIMO state-space model with 3 inputs, 3 outputs and 3 states. Create a Nichols plot with phase units in radians.

    Create the MIMO state-space model sys_mimo.

    J = [8 -3 -3; -3 8 -3; -3 -3 8];F = 0.2*eye(3);A = -J\F;B = inv(J);C = eye(3);D = 0;sys_mimo = ss(A,B,C,D);size(sys_mimo)
    State-space model with 3 outputs, 3 inputs, and 3 states.

    Create a Nichols plot with chart object np.

    np = nicholsplot(sys_mimo);

    NicholsPlot - Plot Nichols frequency response of dynamic system (6)

    Set the phase unit ad radians.

    np.PhaseUnit = "rad";

    NicholsPlot - Plot Nichols frequency response of dynamic system (7)

    The Nichols plot automatically updates when you modify the chart object. For MIMO models, nicholsplot produces an array of Nichols plots, each plot displaying the frequency response of one I/O pair.

    Nichols Response of Identified Parametric and Nonparametric Models

    Open Live Script

    For this example, compare the Nichols response of a parametric model, identified from input/output data, to a non-parametric model identified using the same data. Identify parametric and non-parametric models based on the data.

    Load the data and create the parametric and non-parametric models using tfest and spa, respectively.

    load iddata2 z2;w = linspace(0,10*pi,128);sys_np = spa(z2,[],w);sys_p = tfest(z2,2);

    spa and tfest require System Identification Toolbox™ software. The model sys_np is a non-parametric identified model while, sys_p is a parametric identified model.

    Create an options set to turn phase matching and the grid on. Then, create a Nichols plot that includes both systems using this options set.

    plotoptions = nicholsoptions; plotoptions.PhaseMatching = 'on';plotoptions.Grid = 'on';plotoptions.XLim = {[-240,0]};h = nicholsplot(sys_p,'r.-.',sys_np,'b.-.',w,plotoptions);legend('Parametric Model','Non-Parametric model');

    NicholsPlot - Plot Nichols frequency response of dynamic system (8)

    Version History

    Introduced before R2006a

    expand all

    See Also

    nichols | nicholsoptions

    Topics

    • Customize Linear Analysis Plots at Command Line

    MATLAB Command

    You clicked a link that corresponds to this MATLAB command:

     

    Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

    NicholsPlot - Plot Nichols frequency response of dynamic system (9)

    Select a Web Site

    Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

    You can also select a web site from the following list:

    Americas

    • América Latina (Español)
    • Canada (English)
    • United States (English)

    Europe

    • Belgium (English)
    • Denmark (English)
    • Deutschland (Deutsch)
    • España (Español)
    • Finland (English)
    • France (Français)
    • Ireland (English)
    • Italia (Italiano)
    • Luxembourg (English)
    • Netherlands (English)
    • Norway (English)
    • Österreich (Deutsch)
    • Portugal (English)
    • Sweden (English)
    • Switzerland
      • Deutsch
      • English
      • Français
    • United Kingdom (English)

    Asia Pacific

    • Australia (English)
    • India (English)
    • New Zealand (English)
    • 中国
    • 日本 (日本語)
    • 한국 (한국어)

    Contact your local office

    NicholsPlot - Plot Nichols frequency response of dynamic system (2024)

    References

    Top Articles
    Latest Posts
    Recommended Articles
    Article information

    Author: Jeremiah Abshire

    Last Updated:

    Views: 5573

    Rating: 4.3 / 5 (54 voted)

    Reviews: 93% of readers found this page helpful

    Author information

    Name: Jeremiah Abshire

    Birthday: 1993-09-14

    Address: Apt. 425 92748 Jannie Centers, Port Nikitaville, VT 82110

    Phone: +8096210939894

    Job: Lead Healthcare Manager

    Hobby: Watching movies, Watching movies, Knapping, LARPing, Coffee roasting, Lacemaking, Gaming

    Introduction: My name is Jeremiah Abshire, I am a outstanding, kind, clever, hilarious, curious, hilarious, outstanding person who loves writing and wants to share my knowledge and understanding with you.