ipxact-ruby 0.11.1

data/lib/ipxact/parser/component_data_parser.rb

@@ -0,0 +1,309 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# 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/>.
+#
+
+# Module for parsing IPXACT XML data and creating component objects.
+#
+# @author Guillaume Godet-Bar
+#
+module IPXACT::Parser::ComponentData
+
+  # The list of authorized connections (between two component instances in an
+  # interconnection).
+  #
+  AUTHORIZED_CONNECTIONS = [
+    {
+      :from => :mirrored_slave,
+      :to   => :slave
+    },
+    {
+      :from => :master,
+      :to   => :mirrored_master
+    },
+    {
+      :from => :master,
+      :to   => :slave
+    }
+  ]
+
+  # Parses the component identified by +component_id+, assigns the +variables+
+  # associated to +instance_name+, and produces a {IPXACT::Component} object.
+  #
+  # @param [Array<String>,String] component_id the component identifier, which
+  #                        should appear in one of the component_docs. This
+  #                        identifier can either be a String (in which
+  #                        circumstance the most recent component with the
+  #                        given name will be returned, if any) or an Array of
+  #                        2 elements, composed as follows:
+  #                         [<component_identifier>, <component_version>]
+  # @param [String] instance_name the name of the component instance (if any)
+  #                 that is being parsed.
+  # @param [Array<Hash>] variables the variables associated with the
+  #                      +instance_name+.
+  # @param [Hash<String, Nokogiri::Node>] component_docs the Hash of Nokogiri
+  #                   component documents that was extracted from the
+  #                   platform's IPXACT specification.
+  # @param [Hash<String, Nokogiri::Node>] design_docs the Hash of Nokogiri
+  #                   design documents that was extracted from the platform's
+  #                   IPXACT specification.
+  # @param [Array<String>] contraints an Array of constraints imposed on
+  #                   components. A constraint is an Array of 2 elements,
+  #                   composed as follows:
+  #                     [<component_identifier>, <component_version>]
+  #                   For each component instanciated during the parsing of the
+  #                   platform, the parser will verify if any of the
+  #                   constraints may apply and then select the appropriate
+  #                   component.
+  #
+  # @return [Component] the corresponding component
+  #
+  def self.parse_component(component_id, instance_name, variables, component_docs, design_docs, constraints)
+    component_name, component_version = select_component(component_id, component_docs)
+
+    root_component = component_docs[[component_name, component_version]]
+    component_vendor = root_component.xpath("./spirit:component/spirit:vendor").text
+    views = root_component.xpath("//spirit:model/spirit:views/spirit:view")
+
+    instances, interconnections, hierconnections = parse_design_views(views, component_docs, design_docs, constraints)
+
+    ports = root_component.xpath(".//spirit:busInterface").collect do |a_bus_interface|
+      IPXACT::Parser::BusData.parse_bus(a_bus_interface, root_component, variables)
+    end
+
+    component = IPXACT::Component.new(instance_name, component_name, component_vendor, component_version)
+    component.interconnections = interconnections
+    component.hierconnections = hierconnections
+    component.subcomponents = instances
+    component.ports = ports
+    component
+  end
+
+  # Selects from the component_docs the component that corresponds to the 
+  # +component_id+.
+  # @param [String, Array<String>] component_id the component identifier, which
+  #                   should appear in one of the +component_docs+. This
+  #                   identifier can either be a String (in which circumstance
+  #                   the most recent component with the given name will be
+  #                   returned, if any) or an Array of 2 elements, composed as
+  #                   follows:
+  #                     [<component_identifier>, <component_version>]
+  # @param [Hash<String, Nokogiri::Node>] component_docs the Hash of Nokogiri
+  #                   component documents that was extracted from the
+  #                   platform's IPXACT specification.
+  #
+  # @return [Component] the component identified by +component_id+.
+  # @raise [ArgumentError] if no component could be found.
+  #
+  def self.select_component(component_id, component_docs)
+    if component_id.kind_of?(Array) && component_id.size == 2
+      # A version must have been specified
+      raise ArgumentError, 'Component could not be found!' unless component_docs.has_key? component_id 
+      component_name, component_version = component_id
+    else
+      component_name = component_id
+      component_version = component_docs.keys.select{|name, version| name == component_name} \
+                                             .collect{|name, version| version} \
+                                             .sort{|a, b| 
+                                                1 if IPXACT::is_most_recent_version?(a,b)
+                                                0 if IPXACT::is_same_version?(a,b)
+                                                -1
+                                             }.last
+    end
+    [component_name, component_version]
+  end
+
+  # Scans the given views for a hierarchical view. If such a view is found, the
+  # method loads the referenced design document, and parses all component
+  # instances, interconnections and hierconnections that are described by the
+  # view.
+  #
+  # @param [Array<Nokogiri::Node>] views the views from an IPXACT XML that
+  #                   should be scanned for a hierarchical view.
+  # @param [Hash<String, Nokogiri::Node>] component_docs the Nokogiri component
+  #                   documents that were extracted from the platform's IPXACT
+  #                   specification.
+  # @param [Hash<String, Nokogiri::Node>] design_docs the design documents that
+  #                   were extracted from the platform's IPXACT specification.
+  # @param [Array<Array>] constraints an Array of constraints imposed on
+  #                   components. A constraint is an Array of 2 elements,
+  #                   composed as follows:
+  #                     [<component_identifier>, <component_version>]
+  #                   For each component instanciated during the parsing of the
+  #                   platform, the parser will verify if any of the constraints
+  #                   may apply and then select the appropriate component.
+  #
+  # @return [Array<Hash>] an Array containing 3 Hashes, respectively: the
+  #   component instances Hash, the interconnections Hash and the
+  #   hierconnections Hash. Empty hashes are returned by default.
+  # @raise an exception if any duplicate interconnection is found.
+  #
+  def self.parse_design_views(views, component_docs, design_docs, constraints)
+    design_view = views.select{|view| view.xpath("./spirit:name").text == 'spirit-design' && view.xpath("./spirit:envIdentifier").text == '::Hierarchy'}
+    if design_view.size == 1
+      design_ref = IPXACT::parse_reference(design_view.first.xpath("./spirit:hierarchyRef").first)
+
+      design_doc = design_docs[[design_ref[:name], design_ref[:version]]]
+
+      instances_map = parse_component_instances(design_doc)
+      instances = instances_map.inject({}) do |acc, entry|
+        local_instance_name = entry[0]
+        component_reference = entry[1][:reference]
+        local_variables =  entry[1][:variables]
+        
+        constraint = constraints.select{|constraint| constraint[0] == component_reference[:name]}.first
+        if constraint.nil?
+          acc[local_instance_name] = parse_component([component_reference[:name], component_reference[:version]], local_instance_name, local_variables, component_docs, design_docs, constraints)
+        else
+          acc[local_instance_name] = parse_component(constraint, local_instance_name, local_variables, component_docs, design_docs, constraints)
+        end
+        acc
+      end
+
+      interconnections = parse_interconnections(design_doc, instances)
+      interconnection_sources = interconnections.values.collect{|v| v[0]}
+      interconnection_targets = interconnections.values.collect{|v| v[1]}
+      raise 'Duplicate connections!' \
+        if interconnection_sources.size != interconnection_sources.uniq.size ||
+           interconnection_targets.size != interconnection_targets.uniq.size
+
+      hierconnections = parse_hierconnections(design_doc, instances)
+    end
+
+    [(instances || {}), (interconnections || {}), (hierconnections || {})]
+
+  end
+
+  # Parses the IPXACT's design document for constructing the corresponding
+  # component instance interconnection.
+  #
+  # @param [Nokogiri::Node] design_doc the IPXACT design document that should
+  #                         be parsed for extracting the interconnection's
+  #                         data.
+  # @param [Array<Component>] component_instances the list of Component
+  #                       instances (i.e. parsed components) that correspond to
+  #                       the +design_doc+'s root component's subcomponents.
+  # @return [Hash] a Hash that associates the interconnection's name with an
+  #   ordered Array (see {ComponentData#reorder_connection}) of
+  #   Hashes, composed as follows:
+  #     :port_name          - The subcomponent's port name.
+  #     :port_type          - The subcomponent's port type.
+  #     :component_instance - The subcomponent instance.
+  #
+  def self.parse_interconnections(design_doc, component_instances)
+    design_doc.xpath("//spirit:interconnection").inject({}) do |acc, inter|
+      unordered_connection = inter.xpath("./spirit:activeInterface").collect do |active_interface|
+        component_instance = component_instances[active_interface['componentRef']]
+        port = component_instance.ports.select{|port| port[:name] == active_interface['busRef']}.first
+        {
+          :port_name => port[:name],
+          :port_type => port[:type],
+          :component_instance => active_interface['componentRef']
+        }
+      end
+
+      ordered_connection = reorder_connection(unordered_connection)
+
+      acc[inter.xpath("./spirit:name").first.text] = ordered_connection
+      acc
+    end
+  end
+
+  # Parses a design document's hierconnections. A hierconnection corresponds to
+  # a connection between a port from the outside interface of the component
+  # instanciated by the design document with one of the component's
+  # subcomponents' ports.
+  #
+  # @param [Nokogiri::Node] design_doc the IPXACT design document that
+  #                         should be parsed for extracting the
+  #                         hierconnections.
+  # @param [Array<Component>] component_instances the list of Component
+  #                           instances (i.e. parsed components) that
+  #                           correspond to the +design_doc+ design document's
+  #                           root component's subcomponents.
+  #
+  # @return [Hash] a Hash that associates the outside port's name with the
+  #   the following Hash:
+  #     :port_name          - The corresponding subcomponent's port name.
+  #     :port_type          - The corresponding subcomponent's port type.
+  #     :component_instance - The subcomponent's instance.
+  #
+  def self.parse_hierconnections(design_doc, component_instances)
+    design_doc.xpath("//spirit:hierConnection").inject({}) do |acc, hier|
+      interface = hier.xpath("./spirit:interface").first
+      port = component_instances[interface['componentRef']].ports.select{|port| port[:name] == interface['busRef']}.first
+      acc[hier['interfaceRef']] = {
+        :port_name => interface['busRef'],
+        :port_type => port[:type],
+        :component_instance => interface['componentRef']
+      }
+      acc
+    end
+  end
+
+  # Extracts relevant data from an IPXACT design document (i.e., variable
+  # configurations)
+  #
+  # @param [Nokogiri::Node] design_doc a valid IPXACT design document.
+  #
+  # @return [Hash] a Hash that associates the component instance names with
+  #   variable configurations. A variable configuration is composed of:
+  #     :variables  - The list of variables (name - value associations)
+  #     :reference  - The component type of the instance to which the variables
+  #                 should be affected.
+  #
+  def self.parse_component_instances(design_doc)
+    design_doc.xpath("//spirit:componentInstance").inject({}) do |acc, instance|
+
+      variables = instance.xpath(".//spirit:configurableElementValue").inject({}) do |acc, value|
+          acc[value['referenceId']] = value.text
+          acc
+      end
+      acc[instance.xpath("./spirit:instanceName").text] = 
+        {
+          :reference => IPXACT::parse_reference(instance.xpath("./spirit:componentRef").first),
+          :variables => variables
+        }
+      acc
+    end
+  end
+
+  # Reorders IPXACT connections (which are not oriented in IPXACT
+  # specifications), following the list of authorized connections described in
+  # +AUTHORIZED_CONNECTIONS+.
+  #
+  # @param [Array<Hash>] connection a connection Array, that should contain 2
+  #              elements. Each element must be a Hash with at least one
+  #              +:port_type+ key.
+  #
+  # @return [Array] the connection Array, reversed if necessary.
+  # @raise an exception if no permutation of the connection elements corresponds
+  #   to an authorized connection.
+  #
+  def self.reorder_connection(connection)
+    if AUTHORIZED_CONNECTIONS.include?({
+      :from => connection[0][:port_type],
+      :to => connection[1][:port_type]
+    })
+      connection
+    elsif AUTHORIZED_CONNECTIONS.include?({
+      :from => connection[1][:port_type],
+      :to => connection[0][:port_type]
+    })
+      connection.reverse
+    else
+      raise 'Invalid interconnect list!'
+    end
+  end
+end

data/lib/ipxact/parser/platform_data_parser.rb

@@ -0,0 +1,63 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# 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/>.
+#
+
+# Module for parsing IPXACT XML data and creating a platform object. Only this
+# parser module should be used for working with IPXACT data.
+#
+# @author Guillaume Godet-Bar
+#
+module IPXACT::Parser::PlatformData
+
+  # Parses the +component_docs+ and +design_docs+ for creating a new
+  # {Platform} instance.
+  #
+  # @param [String, Array<String>] platform_id the platform identifier, which
+  #                                should appear in one of the +design_docs+.
+  #                                This identifier can either be a String (in
+  #                                which circumstance the most recent component
+  #                                with the given name will be returned, if
+  #                                any) or an Array of 2 elements, composed as
+  #                                follows:
+  #                                 [<platform_identifier>, <platform_version>]
+  # @param [Hash<String, Nokogiri::Node>] component_docs the Hash of Nokogiri
+  #                                       component documents that was
+  #                                       extracted from the platform's IPXACT
+  #                                       specification.
+  # @param [Hash<String, Nokogiri::Node>] design_docs the Hash of Nokogiri
+  #                                       design documents that was extracted
+  #                                       from the platform's IPXACT
+  #                                       specification.
+  # @param [Array<String>] constraints the constraints imposed on components. A
+  #                        constraint is an Array of 2 elements, composed as
+  #                        follows:
+  #                         [<component_identifier>, <component_version>]
+  #                        For each component instanciated during the parsing
+  #                        of the platform, the parser will verify if any of
+  #                        the constraints may apply and then select the
+  #                        appropriate component.
+  #
+  # @return [Platform] the {Platform} instance. All the design documents
+  #   related to the platform or any platform component are used for completing
+  #   the {Platform} object. Additionally, all the variable elements, if any, are
+  #   applied where appropriate.
+  #
+  def self.parse_platform(platform_id, component_docs, design_docs, constraints=[])
+    base_component = IPXACT::Parser::ComponentData.parse_component(
+                                       platform_id, "", {}, component_docs,
+                                       design_docs, constraints)
+    IPXACT::Platform.new(base_component)
+  end
+end

data/lib/ipxact/pathfinder/graph_pathfinder.rb

@@ -0,0 +1,191 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# 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/>.
+#
+
+# {IPXACT::GraphPathFinder} instances are used by {IPXACT::Component} instances
+# for handling Branch-And-Bound type data path searches within a given IPXACT
+# architecture. The {IPXACT::Component} is responsible for translating the IPXACT
+# architecture into a list of connections and transition weights, which may
+# then be queried for optimal paths between two nodes from the connection
+# graph. As such, even though the path finder is pretty generic, it should not
+# be used directly for IPXACT-related work.
+#
+# @example
+#   @pathfinder = IPXACT::GraphPathFinder.new({
+#     :nodes => ['component_a', 'component_b', 'component_c']
+#     :connections =>
+#       [
+#         {:link => [0,1]},
+#         {:link => [1,2], :cost => 2},
+#         {:link => [2,0]}
+#       ]
+#   })
+#   @data_path = @pathfinder.resolve('component_a', 'component_b')
+#
+# @author Guillaume Godet-Bar
+#
+class IPXACT::GraphPathFinder
+
+  # The initializer is essentially used for passing a structured connection
+  # Hash.
+  #
+  # @param [Hash] hash the connection Hash, which should be structured as follows:
+  #
+  #         :nodes        - An Array of node names (String).
+  #
+  #         :connections  - An Array of connection elements, which are defined as
+  #                         :link - A 2-element Array, which describes an oriented
+  #                                 connection between two nodes. The nodes are
+  #                                 expressed using their index in the :nodes
+  #                                 Array.
+  #                         :cost - A positive Integer expressing the cost of
+  #                                 the transition (in the sense of a
+  #                                 Branch-And-Bound algorithm) (optional,
+  #                                 default: 1).
+  #
+  def initialize(hash)
+    @hash = hash
+  end
+
+  # Searches an optimal path between the start and _end elements, which
+  # should be defined in the Hash structured used for instanciating the
+  # {IPXACT::GraphPathFinder} instance. Optimal should be understood as "the
+  # cheapest path given the cost of each connection". Additionally, validates
+  # the latter Hash structure before executing the search algorithm.
+  #
+  # @param [String] start a String that corresponds to an element that was
+  #         registered when the pathfinder was created. The latter will be used
+  #         as the start node by the pathfinder algorithm.
+  # @param [String] _end a String that corresponds to an element that was
+  #         registered when the pathfinder was created. The latter will be used
+  #         as the target node by the pathfinder algorithm.
+  #
+  # @return [Array<Integer>] an Array of Integers corresponding to connection
+  #   indices for the optimal data path between the +start+ and +_end+
+  #   elements, or an empty Array if the +start+ and +_end+ elements are
+  #   identical.
+  # 
+  # @raise an exception if the Hash structure for the connections is empty.
+  # @raise an exception unless all the node names are unique.
+  # @raise an exception if the start or end element does not exist.
+  # @raise an exception if no optimal data path could be found.
+  #
+  def resolve(start, _end)
+    raise "Empty connection table!" if @hash.empty?
+    return [] if start == _end
+    raise "Duplicate connection node found!" if @hash[:nodes].uniq.size != @hash[:nodes].size
+    raise "The source or target node does not exist!" unless @hash[:nodes].include?(start) && @hash[:nodes].include?(_end)
+
+    @interconnect_table = (0..@hash[:nodes].size - 1).collect do |i|
+      (0..@hash[:nodes].size - 1).collect do |j|
+        result_hash = { 
+          :connection =>
+            @hash[:connections].any?{|connection| connection[:link] == [j,i]},
+          :total => Float::INFINITY,
+          :previous => nil
+        }
+        if @hash[:connections].any?{|connection| connection[:link] == [j,i]}
+          result = @hash[:connections].select{|connection| connection[:link] == [j,i]}.first[:cost] || 1
+          result_hash.merge!({:cost => result})
+        end
+
+        result_hash
+      end
+    end
+
+    start_index = @hash[:nodes].index(start)
+    end_index = @hash[:nodes].index(_end)
+    @interconnect_table[start_index][start_index][:total] = 0
+
+
+    rec_resolve([start_index, start_index], end_index, 0)
+
+    last_writer_index = nil
+    @interconnect_table[end_index].each_with_index do |el, i|
+      last_writer_index = i if el[:total] < Float::INFINITY
+    end
+    raise "Destination could not be reached!" if last_writer_index.nil?
+    
+    
+    dump_trajectory(end_index).reverse
+
+  end
+
+private
+
+  # Recursive function for the pathfinder search algorithm.
+  # 
+  # @param [Array] current the current node that is being traversed by the 
+  #                algorithm.
+  # @param [Integer] _end the index of the target node.
+  # @param [Integer] current_total current Integer cost of the trajectory that
+  # is being explored by this branch of the algorithm.
+  # 
+  def rec_resolve(current, _end, current_total)
+    current_writer_index = current[0]
+    (0..@interconnect_table.size - 1).each do |i|
+      if @interconnect_table[i][current_writer_index][:connection]
+        new_total = current_total + (@interconnect_table[i][current_writer_index][:cost] || 1)
+
+        if @interconnect_table[i][current_writer_index][:total] > new_total
+          @interconnect_table[i][current_writer_index] = {:total => new_total, :connection => true, :previous => current.reverse}
+
+          unless @interconnect_table[_end].any?{|el| el[:total] < new_total}
+            rec_resolve([i, current_writer_index], _end, new_total)
+          end
+        end
+      end
+    end
+  end
+
+  # Scans the interconnect table, starting with the end_index, and traces a
+  # trajectory back to its source, using the traceback references in each cell
+  # from the interconnect table. The source cell is considered as the cell for
+  # which there is no traceback reference.
+  #
+  # @param [Integer] end_index an Integer that corresponds to the last
+  #             element (from the original Hash structure) for which there
+  #             should be a trajectory calculated by the search algorithm.
+  #
+  # @return [Array<Integer>] the connection indices from the original Hash
+  #   structure.
+  #
+  def dump_trajectory(end_index)
+    result = []
+    
+    # Get the path with the cheapest result
+    min_element = @interconnect_table[end_index].min{|a,b| a[:total] <=> b[:total]}
+    min_index = @interconnect_table[end_index].index(min_element)
+
+    previous = [min_index, end_index]
+    begin
+      connection_index = @hash[:connections].index(@hash[:connections].detect{|el| el[:link] == previous})
+      result << connection_index unless connection_index.nil?
+      previous = @interconnect_table[previous[1]][previous[0]][:previous]
+    end while not previous.nil?
+
+    result
+  end
+
+  # Commodity method for printing the interconnect table during the execution of the search algorigthm.
+  #
+  def dump_table
+    @interconnect_table.inject('') do |row_acc, row|
+      row_acc + "\n" + row.inject('') do |col_acc, col|
+        col_acc + (col[:total] == Float::INFINITY ? 'I' : col[:total].to_s) + " | "
+      end
+    end
+  end
+end