XMLinput.m

Go to the documentation of this file.

%%    Eotvos Quantum Transport Utilities - XMLinput
%    Copyright (C) 2009-2017 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 filters Filters
%> @{
%> @file XMLinput.m
%> @brief This function is an input filter that parses XML file and fills up the parameter structures necessary to initialize EQuUs classes.
%> @}
%> @brief This function is an input filter that parses XML file and fills up the parameter structures necessary to initialize EQuUs classes.
%> @param filename A string containing the filename of the XML file.
%> @return [1] An instance of structure #Opt
%> @return [2] An instance of structure #param
function [Opt, param] = XMLinput( filename )



parameter_names = { 'Decimation', 'Decimation_block', 'magnetic_field', 'magnetic_field_trans_invariant', 'Lattice_Type', ...
    'Simple_Green_Function', 'Linear_Regression_in_B', 'BdG', 'Spin', 'Silent', 'usingDualModes', 'debug', 'workers', 'custom_Hamiltonians' };

setDefaults()
parseXML( filename )

[Opt, param] = ValidateStructures( Opt, param );

%TODO
% check data consistency like LeadNum, orientation VS Lead_orientation

    %% setDefaults
    %> @brief This function sets default values to the parameter structures
    function setDefaults()
       
        Opt = structures('Opt');
        Opt.Decimation = 4;
        Opt.Decimation_block = 151;
        Opt.NofLeads = 0;
        Opt.magnetic_field = 0;
        Opt.magnetic_field_trans_invariant = true;
        Opt.Lattice_Type = [];
        Opt.Simple_Green_Function = 0;
        Opt.Linear_Regression_in_B = 1;
        Opt.BdG       = 0;
        Opt.Spin      = 0;
        Opt.Silent    = 0;
        Opt.usingDualModes = 1;
        Opt.debug = 0;
        Opt.workers = [];
        Opt.custom_Hamiltonians = [];
        
        param = structures('param');
        
        % skeletons for physical parameters of the scattering region and leads
        param.scatter = struct();
        
        param.scatter.shape = structures('shape');
        
        param.Leads = cell(0);
        
    end
    
    %% parseXML
    %> @brief This opens the XML file and fills up the parameter structures
    %> @param filename A string containing the filename of the XML file.
    function parseXML(filename)

          cCommonFunctions = CommonFunctions();
          if cCommonFunctions.isOctave()
               parser = javaObject('org.apache.xerces.parsers.DOMParser');
               parser.parse(filename); 
               tree = parser.getDocument;
          else        
             tree = xmlread(filename); 
          end

        traverseNodes( tree );
        
    end


    %% traverseNodes
    %> @brief This function parses over the attributes of the tree node
    %> @param theNode An instance of XML DOM node.
    function traverseNodes( theNode )
        % Recurse over node children.
        
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end


        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);
            
            if strcmpi(char(theChild.getNodeName), 'parameters' )
                traverseNodes( theChild )
            elseif strcmpi(char(theChild.getNodeName), 'computing_parameters' )
                setComputingParameters( theChild )
            elseif strcmpi(char(theChild.getNodeName), 'Scatter_region' )
                setScatterParameters( theChild )
            elseif strcmpi(char(theChild.getNodeName), 'Lead_parameters' )
                setLeadParameters( theChild )
            end
            
           
            
            %children(count) = makeStructFromNode(theChild);
        end
    end

    %% setComputingParameters
    %> @brief This function sets computing parameters in the structure #Opt
    %> @param theNode An instance of XML DOM node.
    function setComputingParameters( theNode )
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end
        
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);
            
            if ismember(char(theChild.getNodeName), parameter_names )
                attributes = parseAttributes(theChild);
                setOptValue( attributes, char(theChild.getNodeName) )
            end
        end
        
    end


    %% setScatterParameter
    %> @brief This function sets parameters for the scattering region
    %> @param theNode An instance of XML DOM node.
    function setScatterParameters( theNode )
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end
        
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);
            
            if ismember(char(theChild.getNodeName), parameter_names )
                attributes = parseAttributes(theChild);
                setOptValue( attributes, char(theChild.getNodeName) )
            elseif strcmpi(char(theChild.getNodeName), 'shape' )
                param.scatter = createShape( theChild, param.scatter );     
            elseif strcmpi(char(theChild.getNodeName), 'Atom' )
                param.scatter = createAtom( theChild, param.scatter );                   
            else 
                param.scatter = setParamValue( param.scatter, theChild );
            end
        end
        
    end

    %% createAtom
    %> @brief This function creates a structure Atom consisting of the atomic data of the sites
    %> @param theNode A node of an XML DOM.
    %> @return Returns with the modificated parameter structure
    function param_structure = createAtom( theNode, param_structure )
        
        % determine, whether the node has child nodes or not
        if ~theNode.hasChildNodes
            return
        end
        
        % initialize cell array of Atoms if necessary
        if ~isfield(param_structure, 'Atom') || isempty( param_structure.Atom )
            param_structure.Atom = structures('Atom');
        end
        
        % determine the new length of the cell array
        atom_idx = length( param_structure.Atom ) + 1;      
            
        % fill in input data
        childNodes = theNode.getChildNodes;
        numChildNodes = childNodes.getLength;
                    
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);      
                        
            if strcmpi(char(theChild.getNodeName), 'PL' )
                % the principal layer
                attributes = parseAttributes( theChild );
                param_structure.Atom(atom_idx).PL = str2double(attributes.value);  
            elseif strcmpi(char(theChild.getNodeName), 'Id' )
                % the identification umber
                attributes = parseAttributes( theChild );
                param_structure.Atom(atom_idx).Id = str2double(attributes.value);                             
            end
            
        end                    
        
    end

    %% createShape
    %> @brief This function creates structure shape for the scattering region
    %> @param theNode A node of an XML DOM. 
    %> @return Returns with the modificated parameter structure
    function param_structure = createShape( theNode, param_structure )
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end
        
        shape = structures('shape');
        
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);
            
            if strcmpi(char(theChild.getNodeName), 'width' )
                attributes = parseAttributes( theChild );
                shape.width = str2double( attributes.value );
            elseif strcmpi(char(theChild.getNodeName), 'height' )
                attributes = parseAttributes( theChild );
                shape.height = str2double( attributes.value );            
            end  
        end
       
        param_structure.shape = shape;
    end


    %% setLeadParameters
    %> @brief This function sets parameters of the Leads
    %> @param theNode A node of an XML DOM.
    %> @return Returns with a cell array of lead parameters
    function setLeadParameters( theNode )
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end
        
        % do a for loop to cover all the leads
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);
            
            if strcmpi(char(theChild.getNodeName), 'lead' )
                param.Leads = createLeadNode( theChild, param.Leads );  
            elseif strcmpi(char(theChild.getNodeName), 'NofLeads' )
                attributes = parseAttributes(theChild);
                setOptValue( attributes, char(theChild.getNodeName) )                
            end
            
            
        end
        
    end

    %% createLeadNode
    %> @brief This function fills up data from one particular lead node
    %> @param theNode A node of an XML DOM.
    %> @param Leads A cell array of lead parameters.
    %> @return Returns with the updated cell array of lead parameters.
    function Leads = createLeadNode( theNode, Leads )
        lead_attributes = parseAttributes( theNode );
        num = str2double(lead_attributes.num);
        
        try 
            params = Leads{num}; 
        catch err
            params = structures('lead_param'); 
        end
            
        if theNode.hasChildNodes
           childNodes = theNode.getChildNodes;
           numChildNodes = childNodes.getLength;
        else
            return
        end
        
        
        
        for count = 1:numChildNodes
            theChild = childNodes.item(count-1);            
            params = setParamValue( params, theChild );
        end
        
        
        Leads{num}      = params;
        
    end


    %% setOptValue
    %> @brief This sets a value for a field in the Opt structure 
    %> @param attributes A sata structure extracted from the XML DOM node.
    %> @param attribname String of the attribute name to be set
    function setOptValue( attributes, attribname )
        
        if ( isfield( attributes, 'value') )
            if ~isnan( str2double( attributes.('value') ) )
                Opt.( attribname ) = str2double( attributes.('value') );
            else
                Opt.( attribname ) = attributes.('value');
            end
        else
            display(['bad attribute: ', attribname ])
        end
        
    end

    %% setParamValue
    %> @brief This function sets a value for a field in the #param_structure 
    %> @param param_structure Data structure containing the physical parameters
    %> @param node An instance of XML DOM node.
    %> @return Returns with the updated structure of parameters
    function param_structure = setParamValue( param_structure, node )
        
        attributes = parseAttributes( node );        

        if isfield( attributes, 'value' )
            % make a difference between character and numeric type values (if the type of the input parameter was mistaken or missing)
            value = str2double(attributes.value);
            if isnan( value )
                param_structure.(char(node.getNodeName)) = attributes.value;   
            else
                param_structure.(char(node.getNodeName)) = value; 
            end            
            
        elseif isfield( attributes, 'abs' ) && isfield( attributes, 'phase' )
            param_structure.(char(node.getNodeName)) = str2double(attributes.abs)*exp(1i*str2double(attributes.phase));
        end
        
    end



    %% parseAttributes
    %> @brief This function parses the attributes of the XML node
    %> @param theNode An instance of XML DOM node.
    %> @return Returns with the structure of the extracted parameters
    function attributes = parseAttributes(theNode)
    % Create attributes structure.

    attributes = [];
    if theNode.hasAttributes
        theAttributes = theNode.getAttributes;
        numAttributes = theAttributes.getLength;
        attributes = struct();
    else
        return
    end

    for count = 1:numAttributes
        attrib = theAttributes.item(count-1);
        attributes.( char(attrib.getName) ) = char(attrib.getValue);
    end


    end

end