signal_interface.m

Go to the documentation of this file.

classdef signal_interface
    properties (SetAccess=protected) % Read-only (can be changed only by a method)
        Fc = 0;
        Fs;
        Rs; % Symbol rate
        P; % Power
        PCol; % Power per column in signal field
    end

    properties (SetAccess=protected,Hidden=true)
        E;
    end

    methods
        function obj = signal_interface(signal,param)
            if isfield(param,'Fc') && isscalar(param.Fc), obj.Fc = param.Fc; else obj.Fc = 1; end
            if isfield(param,'Fs') && isscalar(param.Fs), obj.Fs = param.Fs; else robolog('Sampling frequency must be specified','ERR'); end
            if isfield(param,'Rs') && isscalar(param.Rs), obj.Rs = param.Rs; else obj.Rs = 1; end
            if isvector(signal)
                signal = signal(:);
            end
            obj.E = signal;
            if isfield(param, 'PCol')
                if ~isa(param.PCol,'pwr')
                    robolog('Power needs to be specified as object of "pwr" class.','ERR');
                else
                    if numel(param.PCol) ~= size(obj.E, 2)
                        robolog('The number of "pwr" objects in PCol must match the number of columns of the signal.', 'ERR');
                    end
                    obj.PCol = param.PCol;
                    obj.P = setPtot(obj);
                end
            elseif isfield(param,'P')
                if ~isa(param.P,'pwr')
                    robolog('Power needs to be specified as object of "pwr" class.','ERR');
                end
                if length(param.P) > 1
                    robolog('Power cannot be an array of "pwr" object. Use PCol instead.','ERR');
                end
                obj.P = param.P;
                avpow = pwr.meanpwr(signal);
                pwrfraction = avpow/sum(avpow);
                obj.PCol = repmat(obj.P, obj.N, 1).*pwrfraction;
            else
                robolog('Calculating power automatically - may be wrong', 'NFO0');
                robolog('  Set power using pwr object constructor:', 'NFO0');
                robolog('    signal = signal_interface(waveform, struct(''P'', pwr(SNR, Ptot), ...);', 'NFO0');
                robolog('  where SNR is in dB and Ptot is in dBm', 'NFO0');
                robolog('  See signal_interface and pwr documentation for more options', 'NFO0');
                avpow = pwr.meanpwr(signal);
                obj.PCol = pwr(inf, {avpow(1),'W'});
                for jj=2:obj.N
                    obj.PCol(jj) = pwr(inf, {avpow(jj),'W'});
                end
                obj.P = setPtot(obj);
            end
            %Check that user is not specifying properties that do not exist
            f = fieldnames(param);
            props = {'Fc', 'Fs', 'Rs', 'PCol', 'P'};
            [~,ai,~] = intersect(f,props);
            ai2 = false(size(f)); ai2(ai)=true; ai2=~ai2;
            if any(ai2), robolog('Following properties: %s are not used by signal_interface.', 'WRN', strjoin(strcat('''',f(ai2),''''),', ')); end


        end

        function obj = fun1(obj,fun)
            obj.enforceLhs(nargout);
            s = cellfun(fun,mat2cell(get(obj),obj.L,ones(1,obj.N)),'UniformOutput',false);
            if ~all(cellfun(@(c)isequal(size(c),size(s{1})),s))
                robolog('Outputs after fun1 have different lengths. Cannot concatenate.','ERR');
            end
            obj.E = cell2mat(s);
            % Compute new power.
            % WARNING: SNR is not updated
            Pout = pwr.meanpwr(obj.getRaw);
            for i=1:length(obj.PCol)
                PCol_new(i) = pwr(obj.PCol(i).SNR, {Pout(i), 'W'});
            end
            obj.PCol = PCol_new;
            obj.P = setPtot(obj);
        end

        function p = params(obj)
            p = struct( ...
                'Fs', obj.Fs, ...
                'Rs', obj.Rs, ...
                'Fc', obj.Fc, ...
                'P', obj.P, ...
                'PCol', obj.PCol ...
            );
        end
        
        function L = L(obj)
            L = size(obj.E,1);
        end
        
        function N = N(obj)
            N = size(obj.E,2);
        end
        
        function obj = mtimes(obj,M)
            if isscalar(M)
                M = M*eye(obj.N);
            end
            if ~isequal(size(M),([obj.N obj.N]))
                robolog('Jones matrix must be a NxN square matrix.','ERR');
            end

            Fnew=zeros(size(get(obj)));
            Pscale=zeros(obj.N, 1);
            for i=1:obj.N
                Fnew(:,i) = get(obj)*M(i,:).';
                Pscale(i) = norm(M(:,i), 2)^2;
            end
            obj.E = Fnew;
            %power scaling
            obj.PCol = obj.PCol.*Pscale;
            obj.P = setPtot(obj);
        end

        function Nss = Nss(obj)
            % Oversampling rate of the signal
            Nss = obj.Fs/obj.Rs;
        end

        function Ts = Ts(obj)
            % Sampling time of the signal
            Ts = 1/obj.Fs;
        end

        function Tb = Tb(obj)
            % Symbol time of the signal
            Tb = 1/obj.Rs;
            robolog('Don''t use Tb for symbol time. Use 1/Rs. This function will be soon removed','WRN');
        end

        function Pout = setPtot(obj)
            Pout = obj.PCol(1);
            for jj=2:numel(obj.PCol)
                Pout = Pout + obj.PCol(jj);
            end
        end

        function ind = end(obj, k, n)
            if n == 1
                ind=obj.L*obj.N;
            elseif n == 2
                if k==1
                    ind=obj.L;
                elseif k==2
                    ind=obj.N;
                end
            else
                robolog('signal_interface has only two dimensions', 'ERR');
            end
        end
        
        function sref = subsref(obj,s)
            switch s(1).type
                case '.'
                    sref = builtin('subsref',obj,s);
                case '()'
                    % If length(obj) > 1 obj is a vector fo signal_interface and the builtin method should be
                    % called
                    % length(s) <= 2 seems unuseful. Can be removed?
                    if length(s) <= 2 && length(obj) == 1
                        EScaled = obj.get;
                        sref = builtin('subsref',EScaled,s);
                        return
                    else
                        sref = builtin('subsref',obj,s);
                    end
                case '{}'
                    error('MYDataClass:subsref',...
                      'Not a supported subscripted reference')
            end
        end

        function s = get(obj)
            s = getScaled(obj);
        end

        function s = getRaw(obj)
            s = obj.E;
        end

        function s = getScaled(obj)
            % Modified by Robert to include power scaling (28.08.2014).
            s = obj.E;
            Pin = pwr.meanpwr(s);
            for jj=1:obj.N
                Pout(jj) = obj.PCol(jj).Ptot('W');
            end
            if Pin ~=0
                s = bsxfun(@times, s, sqrt(Pout./Pin));
            else
                s = s;
                if Pout>0;
                    robolog('Cannot scale waveform with 0 power to %.2e W','WRN', Pout)
                end
            end
        end

        function s = getNormalized(obj)
            snorm = obj.normalize();
            s = snorm.E;
        end

        function sigout=normalize(obj)
            s = obj.E;
            s = s/sqrt(mean(pwr.meanpwr(s)));
            sigout = set(obj, s);
        end

        function obj = plus(obj1,obj2)
            %check inputs
            param = struct('Fs',obj1.Fs);
            N = obj1.N;
            L = obj1.L;
            if param.Fs~=obj2.Fs || N~=obj2.N || L~=obj2.L
                robolog('Sampling rate, and signal sizes of both signals must be equal.','ERR');
            end
            param.Rs = obj1.Rs;
            if param.Rs~=obj2.Rs
                robolog('Assuming symbol rate of the first signal (%sBd).', 'WRN', formatPrefixSI(param.Rs,'%1.1f'));
            end
            param.PCol = obj1.PCol+obj2.PCol;   %TEMPORARY - for SNR only; power should be calculated numerically b/c of coherence issues
            
            %frequency offset
            Fc1 = obj1.Fc;
            Fc2 = obj2.Fc;
            param.Fc = (Fc1+Fc2)/2;
            s1 = bsxfun(@times,getScaled(obj1),exp(2j*pi*(Fc1-param.Fc)/param.Fs*(0:L-1)'));
            s2 = bsxfun(@times,getScaled(obj2),exp(2j*pi*(Fc2-param.Fc)/param.Fs*(0:L-1)'));
            
            % waveform addition
            s = s1+s2;
            
            %power tracking
            avpower = pwr.meanpwr(s);
            for jj = 1:N
                param.PCol(jj) = pwr(param.PCol(jj).SNR, {avpower(jj), 'W'});
            end
            
            obj = signal_interface(s,param);
            obj.P = setPtot(obj);
        end

        function obj = truncate(obj, L)
            obj.enforceLhs(nargout);
            sig = get(obj);
            obj = set(obj, sig(1:L, :));
        end

        function obj = combine(varargin)
            obj=Combiner_v1.combine(varargin);
        end

        function disp(obj)
            % Overload display function (for easy viewing in the console and
            % debugger)
            if isreal(get(obj))
                txt_sig = 'Real';
            else
                txt_sig = 'Complex';
            end
            if obj.Fc == 1
                strFc = 'Undefined ';
                strWavelength = 'Undefined ';
            else
                strFc = formatPrefixSI(obj.Fc,'%1.3f');
                strWavelength = formatPrefixSI(const.c/obj.Fc,'%1.5f');
            end
            if obj.Rs == 1
                strRs = 'Undefined ';
                strTs = 'Undefined ';
                strNss = 'Undefined ';
            else
                strRs = formatPrefixSI(obj.Rs,'%1.1f');
                strTs = formatPrefixSI(1/obj.Rs,'%1.1f');
                strNss = formatPrefixSI(obj.Nss,'%1.2f');
            end
            fprintf(1,[
                '%s signal\n' ...
                '              Length: %sSa\n'...
                'Number of components: %d\n'...
                '       Sampling rate: %sHz (%ss)\n'...
                '         Symbol rate: %sBd (%ss)\n'...
                '  Oversampling ratio: %sSa/symbol\n'...
                '   Carrier frequency: %sHz (%sm)\n'...
                '\n' ],...
                txt_sig,...
                formatPrefixSI(obj.L,'%1.0f'),...
                obj.N,...
                formatPrefixSI(obj.Fs,'%1.2f'),formatPrefixSI(obj.Ts,'%1.2f'),...
                strRs, strTs,...
                strNss,...
                strFc, strWavelength);

            disp(obj.P);
        end

        function obj = set(obj,varargin)
            rescaleP = 0;
            rescalePCol = 0;
            obj.enforceLhs(nargout);
            if numel(varargin)==1
                obj.E = varargin{1}; % TODO input checking --- can only be a matrix
                if numel(obj.PCol)~=size(obj.E, 2)
                    robolog('The number of "pwr" objects in PCol must match the number of columns of the signal.', 'WRN');
                    robolog('Resetting quasi-arbitrarily.  This warning will become an error in the future.', 'WRN');
                    if numel(obj.PCol)>size(obj.E, 2);
                        obj.PCol = obj.PCol(1:size(obj.E, 2));
                    else
                        obj.PCol = repmat(obj.P/obj.N, obj.N, 1);
                    end
                    obj.P = setPtot(obj);
                end
            elseif rem(nargin,2)
                for i=1:(nargin-1)/2
                    obj.(varargin{2*i-1}) = varargin{2*i};
                    if strcmp(varargin{2*i-1}, 'P'), rescalePCol=1; end
                    if strcmp(varargin{2*i-1}, 'PCol')
                        if numel(varargin{2*i}) ~= size(obj.E, 2)
                            robolog('The number of "pwr" objects in PCol must match the number of columns of the signal.', 'ERR');
                        end
                        rescaleP=1;
                    end
                end
            else
                robolog('Bad key-value pairs.','ERR');
            end
            if rescaleP, obj.P = setPtot(obj); end
            if rescalePCol, obj.PCol = repmat(obj.P/obj.N, obj.N, 1); end
            if rescalePCol && rescaleP
                robolog('Both power per column and total power were specified.  Power per column takes precedence')
            end
        end

    end

    methods (Access=private,Hidden,Static)

        function enforceLhs(n,minimum)
            %ENFORCELHS   Enforces assignment on the LHS to a certain
            %number of arguments
            if nargin<2
                minimum = 1;
            end
            if n<minimum
                robolog('When using this method, you must ensure that LHS exists. Due to memory considerations, overwriting the original object is recommended.','ERR');
            end
        end

    end

end