% -*- texinfo -*-
% @deftypefn {Function File} {[@var{mag}, @var{phase}, @var{w}] =} nichols (@var{sys}, @var{w}, @var{outputs}, @var{inputs})
% Produce Nichols plot of a system.
%
% @strong{Inputs}
% @table @var
% @item sys
% System data structure (must be either purely continuous or discrete;
% see @command{is_digital}).
% @item w
% Frequency values for evaluation.
% @itemize
% @item if sys is continuous, then nichols evaluates @math{G(jw)}.
% @item if sys is discrete, then nichols evaluates @math{G(exp(jwT))},
% where @var{T}=@var{sys}. @var{tsam} is the system sampling time.
% @item the default frequency range is selected as follows (These
% steps are @strong{not} performed if @var{w} is specified):
% @enumerate
% @item via routine @command{__bodquist__}, isolate all poles and zeros away from
% @var{w}=0 (@math{jw=0} or @math{exp(jwT)=1}) and select the frequency range
% based on the breakpoint locations of the frequencies.
% @item if sys is discrete time, the frequency range is limited to jwT in
% @iftex
% @tex
% $ [0, 2p\pi] $.
% @end tex
% @end iftex
% @ifinfo
% [0,2p*pi].
% @end ifinfo
% @item A ``smoothing'' routine is used to ensure that the plot phase does
% not change excessively from point to point and that singular points
% (e.g., crossovers from +/- 180) are accurately shown.
% @end enumerate
% @end itemize
% @item outputs
% @itemx inputs
% the names or indices of the output(s) and input(s) to be used in the
% frequency response; see @command{sysprune}.
% @end table
% @strong{Outputs}
% @table @var
% @item mag
% @itemx phase
% The magnitude and phase of the frequency response @math{G(jw)} or
% @math{G(exp(jwT))} at the selected frequency values.
% @item w
% The vector of frequency values used.
% @end table
% If no output arguments are given, @command{nichols} plots the results to the screen.
% Descriptive labels are automatically placed. See @command{xlabel},
% @command{ylabel}, and @command{title}.
%
% Note: if the requested plot is for an @acronym{MIMO} system, @var{mag} is set to
% @iftex
% @tex
% $ \Vert G(jw) \Vert $ or $ \Vert G( {\rm exp}(jwT) \Vert $
% @end tex
% @end iftex
% @ifinfo
% |G(jw)| or |G(exp(jwT))|
% @end ifinfo
% and phase information is not computed.
% @end deftypefn