unit.m

Go to the documentation of this file.

classdef unit < handle    
    properties (GetAccess=public,SetAccess=protected,Hidden=true)
        inputBuffer = {}; 
        nextNodes = {}; 
        destInputs = []; 
    end
    
    properties (GetAccess=public,SetAccess=public)
        results; 
        label;
        draw = [];
    end
    
    properties (GetAccess=public,SetAccess=private,Hidden)
        ID;
    end
    
    properties (Abstract=true,Hidden=true)
        nInputs; 
        nOutputs; 
    end
    
    methods (Abstract)
        varargout = traverse(obj,varargin);
    end
    
    methods
        
        function obj = unit
            obj.ID = java.rmi.server.UID();
            obj.label = class(obj);
            
            % Draw by default
            if isempty(obj.draw), obj.draw = true; end
        end
        
        function traverseNode(obj)
            robolog('Traversing ...');
            %Check # of inputs and outputs
            if obj.nInputs~=numel(obj.inputBuffer);
                robolog('Number of connected inputs must be equal to the number of module inputs. %s has %d inputs; %d in were given', 'ERR', obj.label, obj.nInputs, numel(obj.inputBuffer));
            end
            if obj.nOutputs~=numel(obj.nextNodes);
                robolog('Number of outputs must be equal to the number of connected units. %s has %d outputs; %d destination units were specified', 'ERR', obj.label, obj.nOutputs, numel(obj.nextNodes));
            end
            
            % Helper function with one argument. Checks if all elements of
            % a cell array are of class signal_interface
            areallsignalinterfaces = @(var)all(cellfun(@(obj)isa(obj,'signal_interface'),var));
            
            % Check if inputs are ready
            if ~areallsignalinterfaces(obj.inputBuffer)
                robolog('The inputs are not ready yet. Incorrect topology ordering.', 'ERR');
            end
            [outputs{1:obj.nOutputs}] = traverse(obj,obj.inputBuffer{:}); % Traverse the unit
            if(~ispref('robochameleon','debugMode') || ~getpref('robochameleon','debugMode'))
                obj.inputBuffer = {}; % Remove processed inputs to save memory
            end
            
            % Draw figures
            if obj.draw, drawnow; end
            
            % Check if outputs are correctly returned: as a cell array, all
            % of class signal_interface and their number agrees with
            % nOutputs
            if ~iscell(outputs) || ~areallsignalinterfaces(outputs)
                robolog('Output from the traverse function is not a cell array or not all of its elements are of class signal_interface.', 'ERR');
            end
            if numel(outputs)~=obj.nOutputs
                %Changed from error to warning on June 12 2014 by Molly
                %robolog('Size of the outputs cell is incorrect (expected vector with length %d, got %d).',obj.nOutputs,numel(outputs));
                robolog('Size of the outputs cell has changed (expected vector with length %d, got %d).', 'WRN', obj.nOutputs,numel(outputs));
            end
            
            % Find all connected outputs
            conn = find(cellfun(@(obj)inherits_from(obj,'unit'),obj.nextNodes));
            % Write all outputs to the inputBuffer of the connected units
            for i=conn
                writeInputBuffer(obj.nextNodes{i},outputs{i},obj.destInputs(i));
            end
        
        end
        
        function connectOutput(obj,uobj,unitOutput,nextUnitInput)
            % Connects a single output to a single input
            if ~inherits_from(uobj,'unit')
                robolog('All successive nodes must inherit from unit.', 'ERR');
            end
            obj.nextNodes{unitOutput} = uobj;
            obj.destInputs(unitOutput) = nextUnitInput;
        end
        
        function connectOutputs(obj,units,destInputs)
            
            %convert input array of units to cell array
            %necessary to keep this to deal with 1x1 case - overwriting
            %horzcat and vertcat doesn't cover this case
            if ~iscell(units)
                units = mat2cell(units(:), ones(1, numel(units)), 1);
            end
            
            % If destination port not specified, assign based on context.
            % Throw an error if this is not possible.
            if nargin<3 
                if numel(units)==obj.nOutputs
                    destInputs = ones(1,obj.nOutputs);
                elseif (numel(units)==1) && (units{1}.nInputs == obj.nOutputs)
                    destInputs = 1:obj.nOutputs;
                    units = repmat(units, obj.nOutputs, 1);
                else
                    robolog('Destination inputs must be specified.', 'ERR');
                end
            elseif ~isnumeric(destInputs)||~isvector(destInputs)
                robolog('Destination inputs must be specified as a vector of integers.', 'ERR');
            end
             
            if numel(units)~=obj.nOutputs || ~isvector(units)
                robolog('Number of connected units must be equal to the number of output signals. %s has %d outputs; %d destination units were specified', 'ERR', obj.label, obj.nOutputs, numel(units));
            end
            
            % Check that destination makes basic sense
            destMax = cellfun(@(x)x.nInputs, units);
            if any(destInputs(:)>destMax(:))
                badone = find(destInputs(:)>destMax(:));
                robolog('Specified input exceeds allowed number of inputs.  \n%s has %d inputs, so you cannot connect to port %d.', 'ERR', units{badone}.label, units{badone}.nInputs, destInputs(badone));
            end
            if any(destInputs(:)<1)
                robolog('Input numbers must be 1 or greater', 'ERR');
            end
            
                
            for i=1:obj.nOutputs
                obj.connectOutput(units{i},i,destInputs(i));
            end
        end
        
        function writeInputBuffer(obj,sig,inputId)
            obj.inputBuffer{inputId} = sig;
        end
        
        function newobj = horzcat(varargin)
            for jj = 1:nargin
                newobj{jj} = varargin{jj};
            end
        end
        
        function newobj = vertcat(varargin)
            for jj = 1:nargin
                newobj{jj} = varargin{jj};
            end
            newobj = newobj.';
        end
           
        function setparams(obj,params,REQUIRED_PARAMS, QUIET_PARAMS)
            DEFAULT_QUIET_PARAMS = {'nInputs', 'nOutputs', 'results', 'label', 'draw'};
            if nargin<3, REQUIRED_PARAMS = {}; end
            if nargin<4
                QUIET_PARAMS = DEFAULT_QUIET_PARAMS;
            else
                QUIET_PARAMS = [QUIET_PARAMS DEFAULT_QUIET_PARAMS];
            end
            PROTECTED_NAMES = {'inputBuffer', 'nextNodes', 'destInputs'};
            %get cell array of params
            if isstruct(params)
                f = fieldnames(params);
            elseif iscell(params)
                f = params;     %Some units pass empty cell to setparams - this is not ideal, but not a huge problem
            else
                f = {};
            end
            
            %Check if required properties are specified
            reqm = ismember(REQUIRED_PARAMS,f);
            if ~isempty(reqm) && ~all(reqm)
                robolog('Required parameters %s were not passed.', 'ERR', strjoin(strcat('''',REQUIRED_PARAMS(~reqm),''''),', '));
            end
            
            % Remove protected properties
            [protected,protected_idx] = intersect(f,PROTECTED_NAMES);
            if ~isempty(protected)
                robolog('Protected class properties %s were removed from being assigned.', 'WRN', strjoin(strcat('''',protected,''''),', '), 'WRN');
            end
            xi2 = false(size(f)); xi2(protected_idx)=true;
            f = f(~xi2);
            
            % Find unused parameters
            props = properties(obj); props=props(:)';
            [fassign,ai,bi] = intersect(f,props);
            [~,~,ci] = intersect(QUIET_PARAMS,props);
            ai2 = false(size(f)); ai2(ai)=true; ai2=~ai2;
            bi2 = false(size(props)); bi2(bi)=true; bi2(ci)=true; bi2=~bi2;
            if any(ai2), robolog('Following properties: %s are not used by the class.', 'NFO0', strjoin(strcat('''',f(ai2),''''),', ')); end
            if any(bi2)
                robolog('The following properties use default value from %s (%s):', 'NFO0', obj.label, class(obj));
                defProp = props(bi2);
                mTxtL = max(cellfun(@(x) numel(x), defProp));
                for pri=1:numel(defProp)
                    prVal = obj.(defProp{pri});
                    if isnumeric(prVal) || islogical(prVal)
                        strVal = num2str(prVal);
                    elseif ischar(prVal)
                        strVal = prVal;
                    else
                        strVal = sprintf('Default value of type %s', class(prVal));
                    end
                    robolog(['%' num2str(mTxtL + 3) 's: %s'], 'NFO0', defProp{pri}, strVal);
                end
            end
            for i=1:numel(fassign)
                mp = findprop(obj,fassign{i});
                if strcmp(mp.SetAccess, 'public') % Assign only public properties
                    obj.(fassign{i}) = params.(fassign{i});
                else
                    robolog('Private property: ''%s'' not assigned.', 'NFO0', fassign{i});
                end
            end
        end
        
        function view(obj)
           unit_view(obj.nextNodes,obj.destInputs,obj.label);
        end
    end
end