Transport_Interface_Keldysh.m

Go to the documentation of this file.

%%    Eotvos Quantum Transport Utilities - Transport_Interface_Keldysh
%    Copyright (C) 2009-2015 Peter Rakyta, Ph.D.
%
%    This program is free software: you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation, either version 3 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see http://www.gnu.org/licenses/.
%
%> @addtogroup basic Basic Functionalities
%> @{
%> @file Transport_Interface_Keldysh.m
%> @brief A class to evaluate the Dyson equation derived from class #Transport_Interface with specific modifications for steady state non-equilibrium processes.
%> @} 
%> @brief A class to evaluate the Dyson equation derived from class #Transport_Interface with specific modifications for steady state non-equilibrium processes.
%%
classdef Transport_Interface_Keldysh < Transport_Interface


    properties ( Access = protected )
        
    end




methods

%% Contructor of the class
%> @brief Constructor of the class.
%> @param Opt An instance of the structure #Opt.
%> @param param An instance of the structure #param.
%> @param varargin Cell array of optional parameters. For details see #InputParsing.
%> @return An instance of the class
function obj = Transport_Interface_Keldysh(E, Opt, param, varargin)
    obj = obj@Transport_Interface( E, Opt, param, varargin{:} );
    
    obj.Initialize();

    
end


%% LeadCalc
%> @brief Invokes the function #SurfaceGreenFunctionCalculator for each lead.
%> @param varargin Cell array of optional parameters (https://www.mathworks.com/help/matlab/ref/varargin.html):
%> @param 'shiftLeads' A real number. If given, the on-site potentials of the sites in the lead are shifted by this value.
%> @param 'transversepotential' A function handle pot = f( #coordinates ) or pot=f( #CreateLeadHamiltonians, Energy) of the transverse potential applied in the lead. (Instead of #CreateLeadHamiltonians can be used its derived class)
%> @param 'coordinates_shift' An integer. If given, the coordinates of the sites in the lead are shifted by coordinates_shift*lattice vector.
%> @param 'gauge_field' Function handle S = f( x,y) of the gauge transformation on the Hamiltonians of the leads. (S is a N x 1 vector, where N is the number of the points given by the x and y coordinates.)
%> @param 'createCore' Set 1 for creating the class instances #Lead but omitting any further calculations, or false (default) to continue with the calculations.
%> @param 'SelfEnergy' Logical value. Set true to calculate the self energies of the leads. (default is false)
%> @param 'SurfaceGreensFunction' Logical value. Set true to calculate the surface Green functions of the leads. (default is true)
%> @param 'leads' Array of lead identification numbers for which the calculations should be performed. (Default is a list of all leads)
%> @param 'leadmodel' A function handle #Lead=f( idx, E, varargin ) of the alternative lead model with equivalent inputs and return values as #Transport_Interface.SurfaceGreenFunctionCalculator and with E standing for the energy.
%> @param 'CustomHamiltonian' An instance of class #Custom_Hamiltonians or its derived class to create custom Hamiltonians in the leads.
%> @param 'Just_Create_Hamiltonians' Logical value. Set true to create the Hamiltonians of the leads, but stop further calculations. Default value is false.
%> @param 'q' The tranverse momentum for transverse computations.
%> @param 'T' The absolute temperature in Kelvins.
%> @param 'mu_leads' An array containing the chemical potentials of the leads in the same unit as other energy scales in the Hamiltonians.
%> @return Returns with an array of the created #Lead instances.
function lead_ret = LeadCalc( obj, varargin )
        
    p = inputParser;
    p.addParameter('shiftLeads', zeros(length(obj.param.Leads),1));
    p.addParameter('transversepotential', []); 
    p.addParameter('coordinates_shift', zeros(length(obj.param.Leads),1) );
    p.addParameter('gauge_field', [] );
    p.addParameter('createCore', 0);
    p.addParameter('SelfEnergy',false); % set true to calculate the self energy of the semi-infinite lead
    p.addParameter('SurfaceGreensFunction', true );% set true to calculate the surface Greens function of the semi-infinite lead
     p.addParameter('leads', 1:length(obj.param.Leads) );% list of leads to be calculated
    p.addParameter('leadmodel', []); %function handle for an individual physical model for the contacts
    p.addParameter('CustomHamiltonian', []);  
    p.addParameter('Just_Create_Hamiltonians', 0);
    p.addParameter('q', [] ) %transverse momentum
    p.addParameter('T', 0 ) %transverse momentum
    p.addParameter('mu_leads', zeros( size(obj.param.Leads) ) ) %chemical potentials in the leads
    p.addParameter('bias_leads', zeros( size(obj.param.Leads) ) ) %array containign the bias of the leads
    p.parse(varargin{:});
    
    shiftLeads             = p.Results.shiftLeads;
    transversepotential              = p.Results.transversepotential;
    coordinates_shift      = p.Results.coordinates_shift; % shifts coordinates by "coordinates_shift" times of a lattice vector.
    gauge_field            = p.Results.gauge_field; % if a valid function handle is given, it is used to perform gauge transformation on Lead Hamiltonians
    createCore             = p.Results.createCore;
    SelfEnergy             = p.Results.SelfEnergy;
    SurfaceGreensFunction  = p.Results.SurfaceGreensFunction;
     leads                  = p.Results.leads;
    Just_Create_Hamiltonians = p.Results.Just_Create_Hamiltonians;
    q                      = p.Results.q;
    CustomHamiltonian      = p.Results.CustomHamiltonian;
    leadmodel              = p.Results.leadmodel;
    T                      = p.Results.T;
    mu_leads               = p.Results.mu_leads;
    bias_leads             = p.Results.bias_leads;
        
     if isempty(obj.Leads)
         obj.Leads = cell(length(obj.param.Leads),1);
     end
    obj.display(' ')
    obj.display('Creating surface_Greens_function interfaces:')
    obj.display(' ')
    idx = 1;
    while idx <= length(leads)
        obj.display('------------------------------')
        obj.display(['Lead: ',num2str(leads(idx))]) 
        obj.Leads{leads(idx)} = obj.SurfaceGreenFunctionCalculator(leads(idx), 'shiftLead', shiftLeads(leads(idx)), 'transversepotential', transversepotential, 'coordinates_shift', coordinates_shift(leads(idx)),...
            'gauge_field', gauge_field, 'createCore', createCore, ...
            'SelfEnergy', SelfEnergy, 'SurfaceGreensFunction', SurfaceGreensFunction, 'q', q, 'leadmodel', leadmodel, 'CustomHamiltonian', CustomHamiltonian, 'Just_Create_Hamiltonians', Just_Create_Hamiltonians, ...
            'T', T, 'mu', mu_leads(idx), 'bias', bias_leads(idx) );
        obj.display(' ')
        idx = idx + 1;
    end

    lead_ret = obj.Leads;

end

%% setTemperature
%> @brief Sets the temperature in the calculations
%> @param T The value of the temperature in Kelvins.
    function setTemperature( obj, T )

        % set the temperature in the leads
        if ~isempty( obj.Leads )
            for idx = 1:length( obj.Leads )
                obj.Leads{idx}.setTemperature(T);
            end
        end
        
        
    end          

%% SurfaceGreenFunctionCalculator
%> @brief Calculates the surface Green's function or the self energy of a Lead.
%> @param idx the identification number of the lead in the attribute Leads (see attribute #CreateLeadHamiltonians.Hanyadik_Lead).
%> @param varargin Cell array of optional parameters (https://www.mathworks.com/help/matlab/ref/varargin.html):
%> @param 'shiftLeads' A real number. If given, the on-site potentials of the sites in the lead are shifted by this value.
%> @param 'transversepotential' A function handle pot = f( #coordinates ) or pot=f( #CreateLeadHamiltonians, Energy) of the transverse potential applied in the lead. (Instead of #CreateLeadHamiltonians can be used its derived class)
%> @param 'Lead' An instance of class #Lead_Keldysh (or its subclass) that is intended to be used in the calculations. 
%> @param 'coordinates_shift' An integer. If given, the coordinates of the sites in the lead are shifted by coordinates_shift*lattice vector.
%> @param 'gauge_field' Function handle S = f( x,y) of the gauge transformation on the Hamiltonians of the leads. (S is a N x 1 vector, where N is the number of the points given by the x and y coordinates.)
%> @param 'createCore' Set 1 for creating the class instances #Lead but omitting any further calculations, or false (default) to continue with the calculations.
%> @param 'SelfEnergy' Logical value. Set true to calculate the self energies of the leads. (default is true)
%> @param 'SurfaceGreensFunction' Logical value. Set true to calculate the surface Green functions of the leads. (default is false)
%> @param 'leads' Array of lead identification numbers for which the calculations should be performed. (Default is a list of all leads)
%> @param 'leadmodel' A function handle #Lead_keldysh=f( idx, E, varargin ) of the alternative lead model with equivalent inputs and return values as #Transport_Interface_Keldysh.SurfaceGreenFunctionCalculator and with E standing for the energy.
%> @param 'CustomHamiltonian' An instance of class #Custom_Hamiltonians or its derived class to create custom Hamiltonians in the leads.
%> @param 'Just_Create_Hamiltonians' Logical value. Set true to create the Hamiltonians of the leads, but stop further calculations. Default value is false.
%> @param 'q' The tranverse momentum for transverse computations.
%> @param 'T' The absolute temperature in Kelvins.
%> @param 'mu' The Chemical potential in the same unit as other energy scales in the Hamiltonians.
%> @return Returns with the created #Lead_Keldysh instance.
function Lead_ret = SurfaceGreenFunctionCalculator( obj, idx, varargin)
    
    p = inputParser;
    p.addParameter('createCore', 0);
    p.addParameter('Just_Create_Hamiltonians', 0);
    p.addParameter('shiftLead', 0);
    p.addParameter('coordinates_shift', 0);
    p.addParameter('transversepotential',[]);
    p.addParameter('Lead',[]);
    p.addParameter('gauge_field', [] );% gauge field for performing gauge transformation
    p.addParameter('SelfEnergy',true); % set true to calculate the self energy of the semi-infinite lead
    p.addParameter('SurfaceGreensFunction', false );% set true to calculate the surface Greens function of the semi-infinite lead
    p.addParameter('leadmodel', []); %function handle for an individual physical model for the contacts
    p.addParameter('CustomHamiltonian', []); 
    p.addParameter('q', [] ) %transverse momentum
    p.addParameter('T', 0 ) %transverse momentum
    p.addParameter('mu', 0 ) %chemical potential in the lead
    p.addParameter('bias', 0 ) %electrical bias in the lead
    p.parse(varargin{:});
    
    createCore            = p.Results.createCore;
    Lead_ret              = p.Results.Lead;
    q                     = p.Results.q;    
    SurfaceGreensFunction = p.Results.SurfaceGreensFunction;
    SelfEnergy            = p.Results.SelfEnergy;
    mu                    = p.Results.mu;   
    bias                  = p.Results.bias;  
    T                     = p.Results.T;   
    
    
    if ~isempty( Lead_ret )
        % do not create a new class instance if Lead_ret was given
        Lead_ret.Reset();                                    
                                        
    elseif ~isempty(idx) && ~isempty(obj.param.Leads{idx}.Lead_Orientation)     
        Lead_ret = Lead_Keldysh(obj.Opt, obj.param,...
                                            'Hanyadik_Lead', idx,....
                                            'Lead_Orientation', obj.param.Leads{idx}.Lead_Orientation, ...
                                            'q', q, ...
                                            'mu', mu, ...
                                            'bias', bias, ...
                                            'T', T);
    else
        Lead_ret = Lead_Keldysh(obj.Opt, obj.param,...
                                            'Hanyadik_Lead', idx, ...
                                            'mu', mu, ...
                                            'bias', bias, ...
                                            'T', T, ...
                                            'q', q);
    end
    
    % calculate the retarded surface Green operator/self-energy
    SurfaceGreenFunctionCalculator@Transport_Interface( obj, idx, 'createCore', createCore, ...
    'Just_Create_Hamiltonians', p.Results.Just_Create_Hamiltonians, ...
    'shiftLead', p.Results.shiftLead, ...
    'coordinates_shift', p.Results.coordinates_shift, ...
    'transversepotential', p.Results.transversepotential, ...
    'Lead', Lead_ret, ...
    'gauge_field', p.Results.gauge_field, ...
    'SelfEnergy', SelfEnergy, ...
    'SurfaceGreensFunction', SurfaceGreensFunction, ...
    'q', p.Results.q, ...
    'CustomHamiltonian', p.Results.CustomHamiltonian, ...
    'leadmodel', p.Results.leadmodel);

    if createCore
        return
    end

    
    % lesser surface Green operator
    if SurfaceGreensFunction
        Lead_ret.LesserSurfaceGreenFunction();
    end
        
    % lesser SelfEnergy
    if SelfEnergy
        Lead_ret.LesserSelfEnergy();
    end
    
    
end

    

%% replaceLead
%> @brief Adds/replaces a lead to/in the system.
%> @param Lead_tmp An instance of class #Lead_Keldysh or its subclass
%> @param idx Identification number of the lead. (see attribute #CreateLeadHamiltonians.Hanyadik_Lead).
    function replaceLead( obj, Lead_tmp, idx )
        
        if ~strcmpi( class(obj.junction), 'Lead_Keldysh' )        
            supClasses = superclasses(Lead_tmp);
            if sum( strcmp( supClasses, 'Lead_Keldysh' ) ) == 0
                error(['EQuUs:', class(obj), ':replaceLead'], 'Input Lead_tmp is not valid.');
            end
        end
        
        obj.Leads{ idx } = Lead_tmp;   
        obj.Opt.NofLeads = length(obj.Leads);
    end


%% CreateClone
%> @brief Creates a clone of the present class.
%> @return Returns with the cloned object.
    function ret = CreateClone( obj )
        
        if isempty( obj.CreateH )
            CreateH_loc = [];
        else
            CreateH_loc = obj.CreateH.CreateClone();
        end
        
        if isempty( obj.PeierlsTransform )
            PeierlsTransform_loc = [];
        else
            PeierlsTransform_loc = obj.PeierlsTransform.CreateClone();
        end
        
        ret = Transport_Interface_Keldysh(obj.E, obj.Opt, obj.param, ...
            'CreateH', CreateH_loc, ...
            'PeierlsTransform', PeierlsTransform_loc );
        
        for idx = 1:length(obj.Leads)
            ret.replaceLead( obj.Leads{idx}.CreateClone(), idx );
        end      
        
    end 
    
%% Write
%> @brief Sets the value of an attribute in the class.
%> @param MemberName The name of the attribute to be set.
%> @param input The value to be set.
    function Write(obj, MemberName, input)
        
        if strcmp(MemberName, 'param')
            obj.param = input;
            obj.Reset();
            return 
        elseif strcmp(MemberName, 'E')
            obj.setEnergy( input );
        elseif strcmp(MemberName, 'T')
            obj.setTemperature( input );
        else
               try
               obj.(MemberName) = input;
               catch
                    error(['EQuUs:', class(obj), ':Read'], ['No property to write with name: ',  MemberName]);
               end
        end        
        
    end 
    
%% Reset
%> @brief Resets all elements in the class.
    function Reset(obj)
        
        if strcmpi( class(obj), 'Transport_Interface_Keldysh' )
            meta_data = metaclass(obj);
            
            for idx = 1:length(meta_data.PropertyList)
                prop_name = meta_data.PropertyList(idx).Name;
                if strcmp(prop_name, 'Opt') || strcmp( prop_name, 'param') || strcmp(prop_name, 'varargin') || strcmp(prop_name, 'E')
                    continue
                end
                obj.Clear( prop_name ); 
            end   
        end 
        
        obj.Initialize();      
          
    
    end    
          

end % method public


methods ( Access = protected )
    
%% Initialize
%> @brief Initializes object attributes.
    function Initialize(obj)
        
        Initialize@Transport_Interface(obj);
        
        if strcmpi( class(obj), 'Transport_Interface_Keldysh')         
            obj.InputParsing( obj.varargin{:});
        end
        
    end        

%% InputParsing
%> @brief Parses the optional parameters for the class constructor.
%> @param varargin Cell array of optional parameters (https://www.mathworks.com/help/matlab/ref/varargin.html):
%> @param 'CreateH' An instance of class #CreateHamiltonians storing the Hamiltonian of the scattering center.
%> @param 'PeierlsTransform' An instance of class #Peierls for the Peierls transformations.
    function InputParsing( obj, varargin )
        
        p = inputParser;
        p.addParameter('CreateH', []);
        p.addParameter('PeierlsTransform', []);
        
        p.parse(varargin{:});
        
        InputParsing@Transport_Interface( obj, 'PeierlsTransform', p.Results.PeierlsTransform, ...
            'CreateH', p.Results.CreateH);

    end

end % methods protected

end