defant.m

阵列信号处理的工具箱

function ant = defant(antennaType, in1, in2, in3, in4, in5, in6, in7)

%DEFANT Defines an antenna and receiver.
%
%--------
%Synopsis:
%  ant = defant(antennaType, ...)
%
%Description:
%  Defines an antenna and receiver.
%  This function must be used once before acquiring received antenna
%  signals (with for example function "compsim4" or "expsig"). The antenna 
%  definition is stored in all radar signals (RxRadarSigT).
%
%Output and Input:
%  ant (AntDefT): Returned antenna definition.
%  antennaType (StringT): Antenna type.
%    = 'array': A physical antenna array with physical antenna elements.
%    = 'beamform': A new top level due to done beamforming.
%    = 'BFArray': An array antenna with antenna elements and beamforming.
%    = 'isotropElem' : An isotropical antenna element
%    = 'pattFuncElem' : Antenna element whose pattern is given by a function.
%    = 'LA' : Linear array with antenna elements placed arbitrary along a line.
%    = 'ULA' : Linear array with equal distant antenna elements.
%    = 'isotropULA' : Linear array with equal distant isotropical antenna
%       elements.
%    = 'aimtEx2' : The antenna in the AIMT application example. Implementation
%       by svabj. Position error can be specified.
%    = 'aimtEx' : The antenna in the AIMT application example. Implementation
%       by FA.
%    = 'expAnt' : The AIMT experimental antenna.
%
%--------
%Array antenna ('array').
%Synopsis:
%  ant = defant('array', elemPos, [], element,[], elemOrient,
%    couplingMat)
%
%Description:
%  A physical antenna array with physical (one-channel) antenna elements. 
%  Antenna elements can be placed at arbitray positions.
%
%Output and Input:
%  elemPos (Vector of PosT): The positions of the antenna elements. The
%    number of antenna elements is determined from the number of elements
%    positions in this input parameter.
%  element (AntDefT or (Cell) Array of AntDefT): Antenna element definition.
%    This can either be a single antenna defintion and then the same
%    definition is used for all antenna elements or this can be a (cell)
%    array of antenna deinitions, one definition for each antenna element.
%  elemOrient [D](Vector of PosT): Orientation of the elements. Not implemented.
%  couplingMat [D](CxMatrixT) : Element coupling matrix. Not implemented.
%
%--------
%Beamforming Virtual Antenna ('beamform').
%Synopsis:
%  ant = defant('beamform',  element, beamSpaceTrans)
%
%Description:
%  A virtual array antenna with the aid of a beamforming operation of the
%  output channels from an other array antenna (the "element").
%
%Output and Input:
%  element (AntDefT): An array antenna definition, probably of type 'array'.
%    Beamforming is done on this antenna.
%  beamSpaceTrans (CxMatrixT): Beamforming weights (CxVectorT) for the
%    signals from input channels.
%    z = beamSpaceTrans'*x , where
%    z : beamspace signals (CxVectorT) = signal(s) from this array.
%    x : elementspace signals (CxVectorT) = signals from the elements of
%      this array.
%    The number of rows in beamSpaceTrans must be equal to the number of
%    input channels of this antenna. The number of columns in beamSpaceTrans
%    must be equal to the number of output channels.
%
%--------
%Array antenna with beamforming ('BFArray').
%Synopsis:
%  ant = defant('BFArray', elemPos, [], element, beamSpaceTrans, elemOrient,
%    couplingMat)
%
%Description:
%  An array antenna with antenna elements and with one level of beamforming,
%  e.g. to subarrays.
%
%Output and Input:
%  beamSpaceTrans (CxMatrixT): Beamforming weights (CxVectorT) for the
%    signals from input channels.
%    z = beamSpaceTrans'*x , where
%    z : beamspace signals (CxVectorT) = signal(s) from this array.
%    x : elementspace signals (CxVectorT) = signals from the elements of
%      this array.
%    The number of rows in beamSpaceTrans must be equal to
%    the number of input channels. The number of columns in beamSpaceTrans
%    must be equal to
%    the number of output channels of this antenna.
%
%--------
%Isotropical Antenna Elements ('isotropElem').
%Synopsis:
%  ant = defant('isotropElem')
%
%Description:
%
%Output and Input:
%
%--------
%Antenna Elements with Arbitrary Antenna Pattern ('pattFuncElem').
%Synopsis:
%  ant = defant('pattFuncElem', pattern, elemOrient)
%
%Description:
%
%Output and Input:
%  pattern (FuncStringT): The name of the function that gives the element
%    pattern.
%  elemOrient (DoaT): Orientation of the element in polar coordinates.
%
%--------
%Non-Uniform Linear Array ('LA').
%Synopsis:
%  ant = defant('LA', elemPos, [], element, beamSpaceTrans)
%
%Description:
%  Linear array with equal antenna elements that can be placed at arbitrary
%  positions along the line.
%
%Output and Input:
%  elemPos (RealVectorT): This is a vector that describes the relative position
%    between the elements. The first element should always be 0 (zero). [m].
%    length(elemPos) = noElem.
%  element (AntDefT): Defintion of the antenna elements.
%  beamSpaceTrans (CxMatrixT): Beamforming weights (CxVectorT) for the
%    signals from the elements. These weights are only used if this ULA
%    is a subarray. Otherwise, if this ULA is the main antenna, the
%    weights are supplied at conventional beamforming by the beamforming
%    function.
%    z = beamSpaceTrans'*x , where
%    z : beamspace signals (CxVectorT) = signal(s) from this ULA (only used
%      if this ULA is a subarray).
%    x : elementspace signals (CxVectorT) = signals from the elements of
%      this ULA.
%
%--------
%Uniform Linear Array ('ULA').
%Synopsis:
%  ant = defant('ULA', [noElem, distElem], element, beamSpaceTrans)
%
%Description:
%  Linear array with equal antenna elements that are placed at equal
%  distance from eachother.
%
%Output and Input:
%  noElem (RealScalarT): Number of antenna elements.
%  distElem (RealScalarT): Distance between antenna elements [m].
%  element (AntDefT): Defintion of the antenna elements.
%  beamSpaceTrans (CxMatrixT): Beamforming weights (CxVectorT) for the
%    signals from the elements. These weights are only used if this ULA
%    is a subarray. Otherwise, if this ULA is the main antenna, the
%    weights are supplied at conventional beamforming by the beamforming
%    function.
%    z = beamSpaceTrans'*x , where
%    z : beamspace signals (CxVectorT) = signal(s) from this ULA (only used
%      if this ULA is a subarray).
%    x : elementspace signals (CxVectorT) = signals from the elements of
%      this ULA.
%
%--------
%Isotropical ULA ('isotropULA').
%Synopsis:
%  ant = defant('isotropULA', [noElem, distElem])
%
%Description:
%  Linear array with isotropical antenna elements that are placed at equal
%  distance from eachother.
%
%Output and Input:
%  noElem (RealScalarT): Number of antenna elements.
%  distElem (RealScalarT): Distance between antenna elements [m].
%
%--------
%AIMT Application Example ('aimtEx2').
%Synopsis:
%  ant = defant('aimtex')
%  ant = defant('aimtex',posErr)
%
%Description:
%  For a description, see reference [2]. Position errors can be specified.
%
%Output and Input:
%  posErr (Vector of PosT): Position errors [m] for the 51 elements.
%    Size = (51 X 1).
%
%--------
%AIMT Application Example ('aimtEx').
%Synopsis:
%  ant = defant('aimtex', )
%
%Description:
%  For a description, see reference [2]. Position errors can not be specified.
%
%Output and Input:
%
%--------
%AIMT Experimental Antenna ('expAnt').
%Synopsis:
%  ant = defant('expAnt')
%
%Description:
%  For a description, see references [3,4].
%
%Output and Input:
%
%Global Variables:
%  c0 (RealScalarT): The speed of light in vacuum. Defined for the 'expAnt'
%    antenna type.
%
%--------
%Notations:
%  Data type names are shown in parentheses and they start with a capital
%  letter and end with a capital T. Data type definitions can be found in [1]
%  or by "help dbtdata".
%  [D] = This parameter can be omitted and then a default value is used.
%  When the [D]-input parameter is not the last used in the call, it must be
%  given the value [], i.e. an empty matrix.
%  ... = There can be more parameters. They are explained under respective
%  metod or choice.
%
%Examples:
%  Example 1:
%    ant = defant('isotropULA',[K,D]);
%    sig = compsim4(ant, lambda, T, tgtModel, [theta, phi, SNR, alpha, ...
%      dalpha, dist, ones(size(theta,1))], 'rndn', eye(K));
%    splot2(sdoaspc('music',sig,[],MMu))
%
%  Exmaple 2:
%    % Creating an antenna equal to the AIMT application example ('aimtex')[2].
%    lambda	= 0.1;
%
%    % Create antenna elements.
%    nElem = 51;
%    elem21 = defant('pattFuncElem', 'sqrt(cos(x))');
%    elem2 = cell(1,nElem);
%    for n = 1:nElem, elem2{n}=elem21; end%for n
%    %elem2 = repmat({},1,nElem);	% Alternative way to create elem2.
%
%    % Create beamforming matrix to do subarray beamforming.
%    T = zeros(nElem,25);
%    for n=1:25
%      T((2*n-1):(2*n-1)+2,n) = [0.5 1 0.5].';
%    end%for n
%    ant2 = defant('BFArray',[0:0.5:25]*lambda,[],elem2,T);
%
%    % Plot an antenna pattern.
%    figure,spantpat3(ant2,{'lambda',lambda,  'mainPointDoa', d2r(20)})
%    % Note the grating lobe.
%    ylim([-50 0])
%    xlim([-60 60])
%
%Software Quality:
%  (About what is done to ascertain software quality. What tests are done.)
%  The 'expAnt' antenna type was used in the work done by A. Heydarkhan [5].
%
%Known Bugs:
%  The use of the field 'beamSpaceTrans' in the new antenna types
%  described above is not consistent with the use of the same field in the
%  old antenna types. This should be no problem as long as no mixing of
%  new and old (one-channel elements excluded) antenna types is done.
%
%References:
%  [1]: Bj鰎klund S.: "DBT, A MATLAB Toolbox for Radar Signal Processing.
%    Reference Guide", FOA-D--9x-00xxx-408--SE, To be published.
%  [2]: Athley F.:"Till鋗pningsexempel f鰎 studie av modellbaserad
%    lobformning", Ericsson Microwave Systems 1996, No FY/XU-96:299.
%  [3]: Pettersson L., Danestig M., Sj鰏tr鰉 U.: "An Experimental S-Band
%    Digital Beamforming Antenna", IEEE AES Systems Magazine, November 1997,
%    p.19-26.
%  [4]: Bj鰎klund S.:"A MATLAB Toolbox for Radar Signal Processing",
%    Proceedings of Nordic MATLAB Conference `97, Stockholm 27-28 October 1997.
%  [5]: Heydarkhan A.: "Model Based Direction of Arrival Estimation Methods
%    Applied to Experimental Antenna Data", Master's Thesis, Chalmers
%    University of Technology 1997. FOA-R--97-00631-408--SE, FOA November 1997.
%  []: Danestig M., Pettersson L., Sj鰏tr鰉 U.: "An Experimental S-Band
%    Digital Beamforming Antenna", IEEE International Symposium on Phased
%    Array Antennas, Boston, 15-18 October 1996.
%
%See Also:
%  dbtex80, compsim4, compsim5, expsig, setcal2, spastemat

%   *  DBT, A Matlab Toolbox for Radar Signal Processing  *
% (c) FOA 1994-2000. See the file dbtright.m for copyright notice.
%
%  Start        : 96xxxx Svante Bj鰎klund (svabj).
%  Latest change: $Date: 2000/10/21 14:07:20 $ $Author: svabj $.
%  $Revision: 1.50 $
% *****************************************************************************

%Remaining comments.
%  The intention is to use an array antenna as "element" and not an
%  one-channel antenna element.

antDefVersion = 3;	% 980525: Version 3 = The field beamSpaceTrans
  % is moved from the element to the current level.

% ----------------------------------------------------------------------- %
%  Global constants
% ----------------------------------------------------------------------- %

global thSign

thSign = +1;
  % Defines the reference direction for the theta angle in DOA:s.
  % -1 : As DBT standard in release 1.9 and earlier.
  % +1 : To conform to Lars Pettersson standard.


% ----------------------------------------------------------------------- %
% Handle input parameters
% ----------------------------------------------------------------------- %

if (nargin < 0)
  error('To few input parameters.')
end

% ****************** Add missing input parameters ******************

arginNo=1;
if (nargin < arginNo)
  antennaType = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in1 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in2 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in3 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in4 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in5 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in6 = [];
end
arginNo = arginNo +1;
if (nargin < arginNo)
  in7 = [];
end
arginNo = arginNo +1;


% ****************** Default values ******************