getlatt.m

Lattice coding and decoding

function [varargout] = getlatt(latt,element,varargin)

%GETLATT Count for a lattice parameters.
%   VOL = GETLATT(L,P)
%   [VOL,D2] = GETLATT(L,P)
%   [VOL,D2,ERR] = GETLATT(L,P)
%   [VOL,D2,ERR,HERMITE] = GETLATT(L,P)
%   [VOL,D2,ERR,HERMITE,TAU] = GETLATT(L,P)
% 
%   [...] = GETLATT(L,P) computes fundamental volume, minimum squared
%   distance, hermite's parameter and kissing number of the Voronoi cell
%   the element P belongs to. To obtain parameters of all lattice
%   elements use the tracelatt function. 
%
%   [...] = GETLATT(L,P,'PropertyName',PropertyValue,...)
%
%   Getlatt Property List
%
%   Echo           'on' | {'off'}
%
%   NOTE: GETLATT function gives sensible results only for geometrically
%         uniform lattices. 
%
%   Example:
%       pts1 = 4 ^ 4;
%       pts2 = 2 ^ 4;
%       [D4,G1] = makelatt('D',pts1,4);
%       [Hex,G2] = makelatt('Hex',pts2,2);
%       [vol1,dist1,hermite1,tau1] = getlatt(D4,87)
%       [vol2,dist2,hermite2,tau2] = getlatt(Hex,5)
% 
%       vol_D4 = sqrt(det(G1));
%       vol_Hex = sqrt(det(G2));
%
%  See also TRACELATT.

%   Copyright 2001-2003 Kamil Anis, [e-mail]
%   Dept. of Radioelectronics, 
%   Faculty of Electrical Engineering
%   Czech Technical University in Prague
%   $Revision: 0.2 $  $Date: 2003/09/28 14:08:22 $
%   --
%   <additional stuff goes here>

global ECHO

name = 'GETLATT';
[idt,tag] = iecho(name);

nopts = length(varargin) / 2;
opts = reshape(varargin,[2 nopts])';

ord1 = strmatch('Echo',opts(:,1));

% Echo
if ~isempty(ord1) % first check whether local option exists
  value1 = opts{ord1,2};
  switch value1
  case 'on'
    ech = 1;
  case 'off'
    ech = 0;
  otherwise
    disp(' ');
    disp([tag,'Invalid option for Echo property.']);
    disp([idt,'Possible values are ''on''|{''off''}.']);
    disp(' ');
    ech = 0;
  end
else
  if ~isempty(ECHO) % than check whether global option exists
    switch ECHO
    case 'on'
      ech = 1;
    case 'off'
      ech = 0;
    otherwise
      disp(' ');
      disp([tag,'Invalid option for Echo property.']);
      disp([idt,'Possible values are ''on''|{''off''}.']);
      disp(' ');
      ech = 0;
    end
  else % if there are no settings use the defaults
    ech = 0; % default value
  end
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% BODY BEGIN %%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

[m,n] = size(latt);

if (element <= 0) | (element > m)
  if ech
    disp(' ');
    disp([tag,'There is no such element in the lattice.']);
    disp([idt,'Returning an empty output.']);
    disp(' ');
  end

  varargout = {[],[],[],[],[]};
  return
end

coord = latt(element,:);
empty_latt = 0; i = 1;

% kissing numbers etc.
[tau,sh] = kiss(latt,element);
% sh = sshell(latt,element);

% the splitter algorithm
while (i <= n) & (empty_latt == 0)
  % determining the cutt-off lanes
  dist = abs(latt(:,i) - coord(:,i));
  
  % removing zero component and finding the shortest distance
  if sum(dist ~= 0) == 0
    edges(i) = 1;
    empty_latt = 1;
    empty_dim = i;
        
    if ech
      str1 = num2str(element); str2 = num2str(i);
      disp(' ');
      disp([tag,'Unable to compute lattice parameters.']);
      disp([idt,'Splitter failed at dimension ',str2,'.']);
      disp([idt,'Voronoi cell of element #',...
        str1,' is used for the computation.']);
      disp([idt,...
        'This might be caused by the edge effects of the finite lattice.']);
      disp([idt,...
        'Try another element or use TRACELATT to trace for all cells.']);
      disp([idt,'Returning an empty output.']);
      disp(' ');
    end
        
    % if the splitter fails leave the function
    varargout = {[],[],[],[],empty_dim};
    return
      
  else
    edges(i) = min(dist(find(dist)));
    empty_dim = [];
  end
  
  % splitting lattice...
  [pos,num] = find(abs(latt(:,i) - coord(:,i)) < edges(i));
  latt = latt(pos,:);
  i = i + 1;
end

% counting minimum squared distance to the neighbours
% [na,foo] = size(sh);
% [na,foo] = size(tau);

if tau > 0
  coords = repmat(coord,tau,1);
  d2 = sum(abs(sh - coords) .^ 2,2); % ||x-y||^2 = sum(abs(x-y)^2) 
  volume = prod(edges);
  d2(find(d2 == 0)) = NaN; 
  d2_min = min(d2); % minimum nonzero distance
  hermite = d2_min / (volume ^ (2 / n));

  varargout = {volume,d2_min,hermite,tau,empty_dim};
else
  varargout = {[],[],[],[],empty_dim};
end

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% BODY END %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%