分析matlab中agwn函数

agwn代码分析注释：

function y = awgn(varargin)
  % varargin 输入参数可变，根据输入参数的个数执行相应的程序。
%AWGN Add white Gaussian noise to a signal.
  % 向信号添加高斯白噪声
%%   Y = AWGN(X,SNR) adds white Gaussian noise to X.  The SNR is in dB.
%   The power of X is assumed to be 0 dBW.  If X is complex, then  AWGN adds complex noise.
  % 两个输入参数的情况。
  % 向信号X添加高斯白噪声， 信噪比为dB。
  % 假设 信号功率 是0 dBW，如果X是复数，则AWGN会添加复数噪声。
%
%%   Y = AWGN(X,SNR,SIGPOWER) when SIGPOWER is numeric, it represents the signal power in dBW. When SIGPOWER is 'measured', AWGN measures   the signal power before adding noise.
  % 输入三个参数的情况。
  % 当SIGPOWER为数值时，表示dBW中的信号功率，当SIGPOWER为'measured'时，AGWN在添加噪声之前测量信号的功率。
%
%%   Y = AWGN(X,SNR,SIGPOWER,S) uses S to generate random noise samples with   the RANDN function. S can be a random number stream specified by RandStream. S can also be an integer, which seeds a random number  stream inside the AWGN function. If you want to generate repeatable   noise samples, then either reset the random stream input before calling   AWGN or use the same seed input.
  % 输入四个参数的情况。
  % 使用randn函数使用S生成随机噪声样本。S可以是RandStream指定的随机数流，S也可以是整数，它在AWGN函数中植入随机数流。如果要生成可重复的噪声样本，请在调用AWGN之前重置随机流输入或使用相同的种子输入。
%
%%   Y = AWGN(..., POWERTYPE) specifies the units of SNR and SIGPOWER.
%   POWERTYPE can be 'db' or 'linear'.  If POWERTYPE is 'db', then SNR   is measured in dB and SIGPOWER is measured in dBW.  If POWERTYPE is   'linear', then SNR is measured as a ratio and SIGPOWER is measured  in Watts.
  % 输入第5个参数的情况 。
  % 指定SNR和SIGPOWER的单位。
  % POWERTYPE可以是'db'或'linear'。如果POWERTYPE为'db',则以dB为单位表示SNR，用dBW为单位表示SIGPOWER。如果POWERTYPE为'linear'，则以比率表示SNR，以Watts（瓦特）为单位表示SIGPOWER。
%




%#codegen 
narginchk(2,5); % 输入参数的个数范围为2-5个

% Validate signal input  %1.验证信号输入
sig = varargin{1}; % 输入参数的第一个量赋值给信号sig
validateattributes(sig, {'numeric'}, {'nonempty'}, 'awgn', 'signal input');
% 检查数组的有效性：属性是否符合，否则将会抛出错误信息

% Validate SNR input  %2. 验证SNR输入
reqSNR = varargin{2}; % 输入参数的第2个量赋值给reqSNR
validateattributes(reqSNR, {'numeric'}, {'real','scalar','nonempty'}, 'awgn', 'SNR input');

% Validate signal power  %3. 验证信号功率
if nargin >= 3 % 输入信号大于等于3
  if strcmpi(varargin{3}, 'measured') % 比较字符串是否相等，忽略大小写， 如果vararigin{3}= 'measured'
      sigPower = sum(abs(sig(:)).^2)/numel(sig); % linear % 线性，
      % 信号功率 = 信号绝对值的平方和/所有元素的数量
  else 
      validateattributes(varargin{3}, {'numeric'}, {'real','scalar','nonempty'}, 'awgn', 'signal power input');
      % 定义属性
      sigPower = varargin{3}; % linear or dB  
      %第3个输入值为'measured'线性或dB
  end 
else 
  sigPower = 1; % linear, default 
  % 默认为1，线性
end

% Validate state or power type %4. 验证状态或功率类型
if nargin >= 4
  coder.internal.errorIf(comm.internal.utilities.isCharOrStringScalar(varargin{4}) && all(~strcmpi(varargin{4}, {'db','linear'})), 'comm:awgn:InvalidPowerType');
  % 报错信息
  isStream = ~isempty(varargin{4}) && ~comm.internal.utilities.isCharOrStringScalar(varargin{4});
  % 第4个量非空 并且 确定输入是字符向量还是MATLAB字符串标量
    % isCharOrStringScalar(S)是字符或字符串标量返回1。 否则，它返回0。

  if isStream && ~isa(varargin{4}, 'RandStream') % Random stream seed
      % isStream 为真（有第四个值），并且第4个量未指定数据类型为“RandStream”则为真，执行以下语句
      validateattributes(varargin{4}, {'double'}, {'real','scalar','nonnegative','integer','<',2^32}, 'awgn', 'seed input');
  end 
else % Default 
  isStream = false; 
  % 默认 isStream 为假
end

% Validate power type 验证功率类型
if nargin == 5coder.internal.errorIf(comm.internal.utilities.isCharOrStringScalar(varargin{4}), 'comm:awgn:InputAfterPowerType');
% Type has been specified as the 4th input
% 类型指定为第4个输入

coder.internal.errorIf(all(~strcmpi(varargin{5}, {'db','linear'})), 'comm:awgn:InvalidPowerType');
end 

isLinearScale = ((nargin == 4) && ~isStream && strcmpi(varargin{4}, 'linear')) || ((nargin == 5) && strcmpi(varargin{5}, 'linear')); % 第5个输入为'linear'

% Cross-validation % 交叉验证 
coder.internal.errorIf(isLinearScale && (sigPower < 0), 'comm:awgn:InvalidSigPowerForLinearMode');

coder.internal.errorIf(isLinearScale && (reqSNR < 0), 'comm:awgn:InvalidSNRForLinearMode');

if ~isLinearScale  % 如果是非linear的，即dB值
  % Convert signal power and SNR to linear scale 将信号功率和信噪比转换为线性比例
  if (nargin >= 3) && ~comm.internal.utilities.isCharOrStringScalar(varargin{3}) 
  % User-specified signal power 用户指定的信号功率
    sigPower = 10^(sigPower/10); %信号功率 dB值转换为线性值
  end 
  reqSNR = 10^(reqSNR/10); % 所需信噪比 dB值转换为线性值
end 

noisePower = sigPower/reqSNR;
%  噪声功率 = 信号功率/信噪比； 信噪比 = 信号功率/噪声功率

if isStream 
  if isa(varargin{4}, 'RandStream')
    stream = varargin{4};
  elseif isempty(coder.target)
    stream = RandStream('shr3cong', 'Seed', varargin{4});
  else 
    stream = coder.internal.RandStream('shr3cong', 'Seed', varargin{4});
  end 

  if ~isreal(sig)
    noise = sqrt(noisePower/2)* (randn(stream, size(sig)) + 1i*randn(stream, size(sig)));
  else 
    noise = sqrt(noisePower)* randn(stream, size(sig));
  end 
else 
  if ~isreal(sig)
    noise = sqrt(noisePower/2)* (randn(size(sig)) + 1i*randn(size(sig)));
  else 
    noise = sqrt(noisePower)* randn(size(sig));
  end 
end 

y = sig + noise;

% [EOF]

例子：

%% Example 1:

%        % To specify the power of X to be 0 dBW and add noise to produce an SNR of 10dB, use:
%        % 将X的功率指定为0dBW，并添加SNR=10dB的噪声。
%        X = sqrt(2)*sin(0:pi/8:6*pi);
%        Y = awgn(X,10,0);

%%% Example 2:

%        % To specify the power of X to be 3 Watts and add noise to produce a linear SNR of 4, use:
%        % 指定X的功率为3瓦特。添加SNR = 4 的线性噪声。
%        X = sqrt(2)*sin(0:pi/8:6*pi);
%        Y = awgn(X,4,3,'linear');

%%% Example 3:

%        % To cause AWGN to measure the power of X and add noise to produce a linear SNR of 4, use:
%        % 使AWGN测量X的幂并添加噪声以产生SNR = 4的线性噪声。
%        X = sqrt(2)*sin(0:pi/8:6*pi);
%        Y = awgn(X,4,'measured','linear');

%%% Example 4:

%        % To specify the power of X to be 0 dBW, add noise to produce an SNR of 10dB, and utilize a local random stream, use:
%        % 将X的功率指定为0dBW，添加SNR = 10dB的噪声，并利用本地随机流。
%        S = RandStream('mt19937ar','Seed',5489);
%        X = sqrt(2)*sin(0:pi/8:6*pi);
%        Y = awgn(X,10,0,S);

%%% Example 5:

%        % To specify the power of X to be 0 dBW, add noise to produce an SNR of 10dB, and produce reproducible results, use:
%        reset(RandStream.getGlobalStream)%        X = sqrt(2)*sin(0:pi/8:6*pi);
%        Y = awgn(X,10,0);