sshell.m

Lattice coding and decoding

function pts = sshell(latt,element,varargin)

%SSHELL Find a lattice spherical shell
%   SH = SSHELL(L,P) returns the sublattice including all neighbours of
%   given element P without element itself. 
%
%   SH = SSHELL(L,P,'PropertyName',PropertyValue,...)
%
%   Sshell Propety List
%
%   Order          value
%   Thickness      value
%   Echo           'on' | {'off'}
%
%   NOTE: SSHELL function gives sensible results only for geometrically
%         uniform lattices.
%
%   Example:
%       pts = 3 ^ 5;
%       Z3 = makelatt('Z',pts,3);
%       SH = sshell(Z3,94,2);
%       showlatt(SH,'Style',1); hold on;
%       showlatt(Z3,'Labeling','num'); 
% 
%   See also NBHOOD, KISS, SPAN.

%   Copyright 2001-2003 Kamil Anis, [e-mail]
%   Dept. of Radioelectronics, 
%   Faculty of Electrical Engineering
%   Czech Technical University in Prague
%   $Revision: 0.1 $  $Date: 2003/1/16 17:33:28 $
%   --
%   <additional stuff goes here>

global ECHO

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

% checking whether there are any additional options
nopts = length(varargin) / 2;
opts = reshape(varargin,[2 nopts])';

ord1 = strmatch('Echo',opts(:,1));
ord2 = strmatch('Order',opts(:,1));
ord3 = strmatch('Thickness',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

% Order
if isempty(ord2) % there's no such option
	ord = 1; % default value
else % there's relevant option
	ord = opts{ord2,2};
end

% Thick
if isempty(ord3) % there's no such option
	thick = 1; % default value
else % there's relevant option
	thick = opts{ord3,2};
end

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

[npts,dim] = size(latt);

% check the element position
if (npts < element) | (element < 0)
	if ech
		disp(' ');
		disp([tag,'Not a lattice element!']);
		disp([idt,'Returning an empty output...']);
		disp(' ');
	end
	pts = [];
	return
end

coord = latt(element,:);
center = repmat(coord,[npts 1]);
dist = abs(latt - center);

% find n-th smallest non-zero element
q = mapsto(dist,0,realmax);
u = unique(q);

% order check
if ord > length(u)
	if ech
		disp(' ');
		disp([tag,'Shell order exceeds lattice dimensions.']);
		disp([idt,'Try to grab smaller shell or enlarge the lattice.']);
		disp([idt,'Returning an empty output...']);
		disp(' ');
	end
	pts = [];
	return
else
   m = u(ord);
end

m_hi = m + thick - 1;

% STEP I: determine shell elements
% (only for geometrically uniform lattices)
r_lo = (dist >= m);
r_hi = (dist <= m_hi);
r = r_lo .* r_hi;

s = sum(r,2);
pos = find(s > 0);
pts = latt(pos,:);

% STEP II: get rid of undesirable elements 
[npts,foo] = size(pts);
center = repmat(coord,[npts 1]);
dist = abs(pts - center);
r = (dist > m_hi);

s = sum(r,2);
pos = find(s == 0);
pts = pts(pos,:);

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