y_petri 1.0.0

data/lib/y_petri/net.rb

@@ -0,0 +1,458 @@
+#encoding: utf-8
+
+# Represents a <em>Petri net</em>: A collection of places and
+# transitions. The connector arrows – called <em>arcs</em> in
+# classical Petri net terminology – are considered a property
+# of transitions. In <tt>YPetri</tt>, 'arcs' is a synonym for
+# places / transitions connected to a given transition / place.
+# 
+class YPetri::Net
+  include NameMagic
+  
+  def initialize *args; oo = args.extract_options!
+    @places, @transitions = [], [] # empty arrays
+    # LATER: let the places/transitions be specified upon init
+  end
+
+  attr_reader :places, :transitions
+
+  # Names of places in the net.
+  # 
+  def pp; places.map &:name end
+
+  # Names of transitions in the net.
+  # 
+  def tt; transitions.map &:name end
+    
+  # Includes a place in the net. Returns <em>true</em> if successful,
+  # <em>false</em> if the place is already included in the net.
+  # 
+  def include_place! place
+    p = place( place )
+    return false if @places.include? p
+    @places << p
+    return true
+  end
+
+  # Includes a transition in the net. Returns <em>true</em> if successful,
+  # <em>false</em> if the transition is already included in the net. The
+  # arcs of the transition being included may only connect to the places
+  # already in the net.
+  # 
+  def include_transition! transition;
+    t = transition( transition )
+    return false if @transitions.include? t
+    raise TypeError, "Unable to include the transition #{t} in #{self}: " +
+      "It connects to one or more places outside the net." unless
+      t.arcs.all? { |p| include? p }
+    @transitions << t
+    return true
+  end
+
+  # Excludes a place from the net. Returns <em>true<em> if successful,
+  # <em>false</em> if the place was not found in the net. A place may
+  # not be excluded from the net so long as any transitions in the
+  # net connect to it.
+  # 
+  def exclude_place! place
+    p = place( place )
+    raise "Unable to exclude #{p} from #{self}: One or more transitions" +
+      "depend on it" if transitions.any? { |t| t.arcs.include? p }
+    return true if @places.delete p
+    return false
+  end
+
+  # Excludes a transition from the net. Returns <em>true</em> if successful,
+  # <em>false</em> if the transition was not found in the net.
+  # 
+  def exclude_transition! transition
+    t = transition( transition )
+    return true if @transitions.delete t
+    return false
+  end
+
+  # Includes an object (either place or transition) in the net. Acts by
+  # calling #include_place! or #include_transition!, as needed, the
+  # difference being, that errors from bad arguments are swallowed.
+  # 
+  def << place_or_transition
+    begin
+      include_place! place_or_transition
+    rescue NameError
+      begin
+        include_transition! place_or_transition
+      rescue NameError
+        raise NameError,
+        "Unrecognized place or transition: #{place_or_transition}"
+      end
+    end
+    return self
+  end
+
+  # Inquirer whether the net includes a place / transition.
+  # 
+  def include? place_or_transition
+    p = begin
+          place( place_or_transition )
+        rescue NameError
+          nil
+        end
+    return places.include? p if p
+    t = begin
+          transition( place_or_transition )
+        rescue NameError
+          nil
+        end
+    return transitions.include? t if t
+    return false
+  end
+
+  # ----------------------------------------------------------------------
+  # Methods exposing transition collections acc. to their properties:
+
+  # Array of <em>ts</em> transitions in the net.
+  # 
+  def timeless_nonstoichiometric_transitions
+    transitions.select{ |t| t.timeless? and t.nonstoichiometric? }
+  end
+  alias ts_transitions timeless_nonstoichiometric_transitions
+
+  # Names of <em>ts</em> transitions in the net.
+  # 
+  def timeless_nonstoichiometric_tt
+    timeless_nonstoichiometric_transitions.map &:name
+  end
+  alias ts_tt timeless_nonstoichiometric_tt
+
+  # Array of <em>tS</em> transitions in the net.
+  # 
+  def timeless_stoichiometric_transitions
+    transitions.select{ |t| t.timeless? and t.stoichiometric? }
+  end
+  alias tS_transitions timeless_stoichiometric_transitions
+
+  # Names of <em>tS</em> transitions in the net.
+  # 
+  def timeless_stoichiometric_tt
+    timeless_stoichiometric_transitions.map &:name
+  end
+  alias tS_tt timeless_stoichiometric_tt
+
+  # Array of <em>Tsr</em> transitions in the net.
+  # 
+  def timed_nonstoichiometric_transitions_without_rate
+    transitions.select{ |t| t.timed? and t.nonstoichiometric? and t.rateless? }
+  end
+  alias timed_rateless_nonstoichiometric_transitions \
+        timed_nonstoichiometric_transitions_without_rate
+  alias Tsr_transitions timed_nonstoichiometric_transitions_without_rate
+
+  # Names of <em>Tsr</em> transitions in the net.
+  # 
+  def timed_nonstoichiometric_tt_without_rate
+    timed_nonstoichiometric_transitions_without_rate.map &:name
+  end
+  alias timed_rateless_nonstoichiometric_tt \
+        timed_nonstoichiometric_tt_without_rate
+  alias Tsr_tt timed_nonstoichiometric_tt_without_rate
+
+  # Array of <em>TSr</em> transitions in the net.
+  # 
+  def timed_stoichiometric_transitions_without_rate
+    transitions.select { |t| t.timed? and t.stoichiometric? and t.rateless? }
+  end
+  alias timed_rateless_stoichiometric_transitions \
+        timed_stoichiometric_transitions_without_rate
+  alias TSr_transitions timed_stoichiometric_transitions_without_rate
+
+  # Names of <em>TSr</em> transitions in the net.
+  # 
+  def timed_stoichiometric_tt_without_rate
+    timed_stoichiometric_transitions_without_rate.map &:name
+  end
+  alias timed_rateless_stoichiometric_tt timed_stoichiometric_tt_without_rate
+  alias Tsr_tt timed_stoichiometric_tt_without_rate
+
+  # Array of <em>sR</em> transitions in the net.
+  # 
+  def nonstoichiometric_transitions_with_rate
+    transitions.select { |t| t.has_rate? and t.nonstoichiometric? }
+  end
+  alias sR_transitions nonstoichiometric_transitions_with_rate
+
+  # Names of <em>sR</em> transitions in the net.
+  # 
+  def nonstoichiometric_tt_with_rate
+    nonstoichiometric_transitions_with_rate.map &:name
+  end
+  alias sR_tt nonstoichiometric_tt_with_rate
+
+  # Array of <em>SR</em> transitions in the net.
+  # 
+  def stoichiometric_transitions_with_rate
+    transitions.select { |t| t.has_rate? and t.stoichiometric? }
+  end
+  alias SR_transitions stoichiometric_transitions_with_rate
+
+  # Names of <em>SR</em> transitions in the net.
+  # 
+  def stoichiometric_tt_with_rate
+    stoichiometric_transitions_with_rate.map &:name
+  end
+  alias SR_tt stoichiometric_tt_with_rate
+
+  # Array of transitions with <em>explicit assignment action</em>
+  # (<em>A</em> transitions) in the net.
+  # 
+  def transitions_with_explicit_assignment_action
+    transitions.select { |t| t.assignment_action? }
+  end
+  alias transitions_with_assignment_action \
+        transitions_with_explicit_assignment_action
+  alias assignment_transitions transitions_with_explicit_assignment_action
+  alias A_transitions transitions_with_explicit_assignment_action
+
+  # Names of transitions with <em>explicit assignment action</em>
+  # (<em>A</em> transitions) in the net.
+  # 
+  def tt_with_explicit_assignment_action
+    transitions_with_explicit_assignment_action.map &:name
+  end
+  alias tt_with_assignment_action tt_with_explicit_assignment_action
+  alias assignment_tt tt_with_assignment_action
+  alias A_tt tt_with_assignment_action
+
+  # Array of <em>stoichiometric</em> transitions in the net.
+  # 
+  def stoichiometric_transitions
+    transitions.select &:stoichiometric?
+  end
+  alias S_transitions stoichiometric_transitions
+
+  # Names of <em>stoichiometric</em> transitions in the net.
+  # 
+  def stoichiometric_tt
+    stoichiometric_transitions.map &:name
+  end
+  alias S_tt stoichiometric_tt
+
+  # Array of <em>nonstoichiometric</em> transitions in the net.
+  # 
+  def nonstoichiometric_transitions
+    transitions.select &:nonstoichiometric?
+  end
+  alias s_transitions nonstoichiometric_transitions
+
+  # Names of <em>nonstoichimetric</em> transitions in the net.
+  # 
+  def nonstoichiometric_tt
+    nonstoichiometric_transitions.map &:name
+  end
+  alias s_tt nonstoichiometric_tt
+
+  # Array of <em>timed</em> transitions in the net.
+  #
+  def timed_transitions; transitions.select &:timed? end
+  alias T_transitions timed_transitions
+
+  # Names of <em>timed</em> transitions in the net.
+  # 
+  def timed_tt; timed_transitions.map &:name end
+  alias T_tt timed_tt
+
+  # Array of <em>timeless</em> transitions in the net.
+  # 
+  def timeless_transitions; transitions.select &:timeless? end
+  alias t_transitions timeless_transitions
+
+  # Names of <em>timeless</em> transitions in the net.
+  # 
+  def timeless_tt; timeless_transitions.map &:name end
+  alias t_tt timeless_tt
+
+  # Array of <em>transitions with rate</em> in the net.
+  # 
+  def transitions_with_rate; transitions.select &:has_rate? end
+  alias R_transitions transitions_with_rate
+
+  # Names of <em>transitions with rate</em> in the net.
+  # 
+  def tt_with_rate; transitions_with_rate.map &:name end
+  alias R_tt tt_with_rate
+
+  # Array of <em>rateless</em> transitions in the net.
+  # 
+  def rateless_transitions; transitions.select &:rateless? end
+  alias transitions_without_rate rateless_transitions
+  alias r_transitions rateless_transitions
+
+  # Names of <em>rateless</em> transitions in the net.
+  # 
+  def rateless_tt; rateless_transitions.map &:name end
+  alias tt_without_rate rateless_tt
+  alias r_tt rateless_tt
+
+  # ==== Inquirer methods about net qualities
+
+  # Is the net <em>functional</em>?
+  # 
+  def functional?; transitions.all? { |t| t.functional? } end
+    
+  # Is the net <em>timed</em>?
+  # 
+  def timed?; transitions.all? { |t| t.timed? } end
+
+  # ==== Simulation constructors
+
+  # Creates a new simulation from the net.
+  # 
+  def new_simulation *args
+    oo = args.extract_options!
+    YPetri::Simulation.new *args, oo.merge( net: self )
+  end
+
+  # Creates a new timed simulation from the net.
+  # 
+  def new_timed_simulation *args
+    oo = args.extract_options!
+    YPetri::TimedSimulation.new oo.merge( net: self )
+  end
+
+  # ==== Sundry methods
+
+  # Networks are equal when their places and transitions are equal.
+  # 
+  def == other
+    return false unless other.class_complies?( ç )
+    places == other.places && transitions == other.transitions
+  end
+
+  # Returns a string briefly describing the net.
+  # 
+  def to_s
+    "#<Net: " + ( name.nil? ? "%s" : "name: #{name}, %s" ) %
+      "#{places.size} places, #{transitions.size} transitions" + " >"
+  end
+
+  def visualize
+    require 'graphviz'
+    γ = GraphViz.new :G     # creating a new graph
+      
+    # main        = γ.add_nodes( "main", shape: "box" )
+    # parse       = γ.add_nodes( "parse", fillcolor: "yellow", style: "rounded,filled", shape: "diamond" )
+    # execute     = γ.add_nodes( "execute", shape: "record", label: "{ a | b | c }", style: "rounded" )
+    # init        = γ.add_nodes( "init", fillcolor: "yellow", style: "filled" )
+
+    # # set global node options
+    # g.node[:color] = "#ddaa66"
+    # g.node[:style] = "filled"
+    # g.node[:shape] = "box"
+    # g.node[:penwidth] = "1"
+    # g.node[:fontname] = "Trebuchet MS"
+    # g.node[:fontsize] = "8"
+    # g.node[:fillcolor] = "#ffeecc"
+    # g.node[:fontcolor] = "#775500"
+    # g.node[:margin] = "0.0"
+
+    # # set global edge options
+    # g.edge[:color] = "#999999"
+    # g.edge[:weight] = "1"
+    # g.edge[:fontsize] = "6"
+    # g.edge[:fontcolor] = "#444444"
+    # g.edge[:fontname] = "Verdana"
+    # g.edge[:dir] = "forward"
+    # g.edge[:arrowsize] = "0.5"
+
+    # add place nodes
+    place_nodes =
+      Hash[ places.zip places.map { |p|
+              γ.add_nodes p.name.to_s, fillcolor: 'lightgrey', color: 'grey', style: 'filled'
+            } ]
+
+    # add transition nodes
+    transition_nodes =
+      Hash[ transitions.zip transitions.map { |t|
+              γ.add_nodes( t.name.to_s,
+                           shape: 'box',
+                           fillcolor: if t.assignment? then 'yellow'
+                                      elsif t.basic_type == :SR then 'lightcyan'
+                                      else 'ghostwhite' end,
+                           color: if t.assignment? then 'goldenrod'
+                                  elsif t.basic_type == :SR then 'cyan'
+                                  else 'grey' end,
+                           style: 'filled'
+                           )
+              
+            } ]
+
+    # add edges
+    transition_nodes.each { |t, t_node|
+      if t.assignment? then
+        t.codomain.each { |p|
+          γ.add_edges t_node, place_nodes[p], color: 'goldenrod'
+        }
+        ( t.domain - t.codomain ).each { |p|
+          γ.add_edges t_node, place_nodes[p], color: 'grey', arrowhead: 'none'
+        }
+      elsif t.basic_type == :SR then
+        t.codomain.each { |p|
+          if t.stoichio[p] > 0 then # producing arc
+            γ.add_edges t_node, place_nodes[p], color: 'cyan'
+          elsif t.stoichio[p] < 0 then # consuming arc
+            γ.add_edges place_nodes[p], t_node, color: 'cyan'
+          else
+            γ.add_edges place_nodes[p], t_node, color: 'grey', arrowhead: 'none'
+          end
+        }
+        ( t.domain - t.codomain ).each { |p|
+          γ.add_edges t_node, place_nodes[p], color: 'grey', arrowhead: 'none'
+        }
+      end
+    }
+
+    # place_collection.each { |place_name, place_label|
+    #   place_instance = place( place_name )
+    #   place_instance.upstream_places.each { |upstream_place|
+    #     node = nodes[ place_name ]
+    #     next unless set_of_places.map { |ɴ, _| ɴ }.include?( upstream_place.name )
+    #     next if upstream_place == place_instance
+    #     upstream_node = nodes[ upstream_place.name ]
+    #     node << upstream_node
+    #   }
+    # }
+
+    # Generate output image
+    γ.output png: "y_petri_graph.png"
+    show_file_with_kioclient "y_petri_graph.png"
+  end
+
+  # display it with kioclient
+  def show_file_with_kioclient( fɴ )
+    system "sleep 0.2; kioclient exec 'file:%s'" % File.expand_path( '.', fɴ )
+  end
+
+  # Inspect string of the instance.
+  # 
+  def inspect; to_s end
+
+  private
+
+  # Display a file with kioclient (KDE).
+  # 
+  def show_file_with_kioclient( file_name )
+    system "sleep 0.2; kioclient exec 'file:%s'" %
+      File.expand_path( '.', file_name )
+  end
+
+  # Place, Transition, Net classes.
+  # 
+  def Place; ::YPetri::Place end
+  def Transition; ::YPetri::Transition end
+  def Net; ::YPetri::Net end
+
+  # Instance identification methods.
+  # 
+  def place( which ); Place().instance( which ) end
+  def transition( which ); Transition().instance( which ) end
+  def net( which ); Net().instance( which ) end
+end # class YPetri::Net

data/lib/y_petri/place.rb

@@ -0,0 +1,189 @@
+#encoding: utf-8
+
+# This class represents Petri net places.
+# 
+class YPetri::Place
+  USE_QUANTUM = false
+  include NameMagic
+
+  attr_reader :quantum
+  attr_accessor :default_marking
+  attr_accessor :marking           # instance-attached marking
+  alias :value :marking
+  alias :m :marking
+
+  # Alias for #marking=
+  # 
+  def value=( marking ); self.marking = marking end
+
+  # Alias for #marking=
+  # 
+  def m=( marking ); self.marking = marking end
+    
+  # Transitions that can directly add/remove tokens from this place.
+  # It is aliased as #upstream_transitions and #ϝ. (ϝ (Greek digamma) looks
+  # like "function", which we know from spreadsheet software: A collection
+  # of transitions directly affecting marking of this place.)
+  # 
+  attr_reader :upstream_arcs
+  alias :upstream_transitions :upstream_arcs
+  alias :ϝ :upstream_arcs
+
+  # Transitions whose action directly depends on this place. Aliased
+  # as #downstream_transitions.
+  # 
+  attr_reader :downstream_arcs
+  alias :downstream_transitions :downstream_arcs
+
+  # Named parameters supplied upon place initialization may include:
+  # 
+  # * :marking (alias :m)
+  # * :default_marking (alias :dflt_m or :m!)
+  # * :quantum (alias :q)
+  # 
+  # While 'marking' is a standard Petri net concept, and default marking
+  # is self-explanatory, place quantum is the concept by which YPetri
+  # reconciles with letter H in the abbreviation HFPN. YPetri places are
+  # always considered discrete, and it is true insomuch, as their marking
+  # is represented by a finite-digit number. The place quantum feature is
+  # not supported yet, but in future, it should enable smooth transition
+  # between continuous and stochastic modes of simulation.
+  # 
+  def initialize *aa; oo = aa.extract_options!
+    # set domain and codomain of the place empty
+    @upstream_arcs = []
+    @downstream_arcs = []
+    @quantum = oo.may_have( :quantum, syn!: :q ) || 1
+    @default_marking = oo.may_have( :default_marking, syn!: [ :dflt_m, :m! ] )
+    @marking = oo.may_have( :marking, syn!: :m ) || @default_marking
+  end
+
+  # Returns an array of all the transitions connected to the place.
+  # 
+  def arcs
+    upstream_arcs | downstream_arcs
+  end
+  alias :connectivity :arcs
+
+  # Returns the union of domains of the transitions associated
+  # with the upstream arcs of this place.
+  # 
+  def precedents
+    upstream_transitions
+      .map( &:upstream_places )
+      .reduce( [], :| )
+  end
+  alias :upstream_places :precedents
+
+  # Returns the union of codomains of the transitions associated
+  # with the downstream arcs originating from this place.
+  # 
+  def dependents
+    downstream_transitions
+      .map( &:downstream_places )
+      .reduce( [], :| )
+  end
+  alias :downstream_places :dependents
+
+  # Adds tokens to the place.
+  # 
+  def add( amount_of_tokens )
+    @marking += amount_of_tokens
+  end
+
+  # Subtracts tokens from the place.
+  # 
+  def subtract( amount_of_tokens)
+    @marking -= amount_of_tokens
+  end
+
+  # Resets place marking back to its default marking.
+  # 
+  def reset_marking
+    @marking = @default_marking
+  end
+
+  # Firing of upstream transitions regardless of cocking. (To #fire
+  # transitions, they have to be cocked with #cock method; the firing
+  # methods with exclamation marks disregard cocking.)
+  # 
+  def fire_upstream!
+    @upstream_arcs.each &:fire!
+  end
+  alias :fire! :fire_upstream!
+
+  # Fires whole upstream portion of the net.
+  # 
+  def fire_upstream_recursively
+    # LATER: so far, implemented without concerns about infinite loops
+    # LATER: This as a global hash { place => fire_list }
+    @upstream_arcs.each &:fire_upstream_recursively
+  end
+  alias :fire_upstream! :fire_upstream_recursively
+
+  # Firing of downstream transitions regardless of cocking. (To #fire
+  # transitions, they have to be cocked with #cock method; the firing
+  # methods with exclamation marks disregard cocking.)
+  # 
+  def fire_downstream!
+    @downstream_arcs.each &:fire!
+  end
+
+  # Fires whole downstream portion of the net.
+  # 
+  def fire_downstream_recursively
+    # LATER: so far, implemented withoud concerns about infinite loops
+    # LATER: This as a global hash { place => fire_list }
+    @downstream_arcs.each &:fire_downstream_recursively
+  end
+  alias :fire_downstream! :fire_downstream_recursively
+
+  # Produces the inspect string of the place.
+  # 
+  def inspect
+    n, m, d, q = instance_description_strings
+    "#<Place: #{ ( USE_QUANTUM ? [n, m, d, q] : [n, m, d] ).join ', ' } >"
+  end
+
+  # Returns a string briefly describing the place.
+  # 
+  def to_s
+    n, m = name, marking
+    "#{n.nil? ? 'Place' : n}[ #{m.nil? ? 'nil' : m} ]"
+  end
+
+  private
+
+  # Makes the place notice an upstream transition;
+  # to be called from the connecting transitions.
+  def register_upstream_transition( transition )
+    @upstream_arcs << transition
+  end
+
+  # Makes the place notice a downstream transition;
+  # to be called from the connecting transitions.
+  def register_downstream_transition( transition )
+    @downstream_arcs << transition
+  end
+
+  def instance_description_strings
+    m, n, d, q = marking, name, default_marking, quantum
+    nς = "name: #{n.nil? ? '∅' : n}"
+    mς = "marking: #{m.nil? ? 'nil' : m}"
+    dς = "default_marking: #{d.nil? ? '∅' : d}"
+    qς = "quantum: #{q.nil? ? '∅' : q}"
+    return nς, mς, dς, qς
+  end
+
+  # Place, Transition, Net class
+  # 
+  def Place; ::YPetri::Place end
+  def Transition; ::YPetri::Transition end
+  def Net; ::YPetri::Net end
+
+  # Instance identification methods.
+  # 
+  def place( which ); Place().instance( which ) end
+  def transition( which ); Transition().instance( which ) end
+  def net( which ); Net().instance( which ) end
+end # class YPetri::Place