y_petri 2.0.7 → 2.0.14.p1

data/lib/y_petri/net.rb

@@ -1,31 +1,26 @@
 #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.
+require_relative 'dependency_injection'
+require_relative 'net/visualization'
+require_relative 'net/selections'
+
+# Represents a _Petri net_: A collection of places and transitions. The
+# connector arrows – called _arcs_ in classical Petri net terminology – can be
+# considered a property of transitions. Therefore in +YPetri+, term 'arcs' is
+# mostly used as a synonym  denoting neighboring places / transitions.
 # 
 class YPetri::Net
   include NameMagic
+  include YPetri::DependencyInjection
   
-  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
+  def initialize( places: [], transitions: [] )
+    @places, @transitions = places, transitions
+  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.
+  # Includes a place in the net. Returns _true_ if successful, _false_ if the
+  # place is already included in the net.
   # 
   def include_place! place
     pl = place( place )
@@ -34,10 +29,9 @@ class YPetri::Net
     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.
+  # Includes a transition in the net. Returns _true_ if successful, _false_ 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;
     tr = transition( transition )
@@ -49,10 +43,9 @@ class YPetri::Net
     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.
+  # Excludes a place from the net. Returns _true_ if successful, _false_ 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
     pl = place( place )
@@ -62,8 +55,8 @@ class YPetri::Net
     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.
+  # Excludes a transition from the net. Returns _true_ if successful, _false_ if
+  # the transition was not found in the net.
   # 
   def exclude_transition! transition
     tr = transition( transition )
@@ -71,9 +64,8 @@ class YPetri::Net
     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.
+  # Includes an object (either place or transition) in the net. Acts by calling
+  # +#include_place!+ or +#include_transition!+, as needed, swallowing errors.
   # 
   def << place_or_transition
     begin
@@ -82,8 +74,8 @@ class YPetri::Net
       begin
         include_transition! place_or_transition
       rescue NameError
-        raise NameError,
-        "Unrecognized place or transition: #{place_or_transition}"
+        raise NameError, "Unrecognized place/transition: #{place_or_transition}"
+        # TODO: Exceptional Ruby
       end
     end
     return self
@@ -107,213 +99,17 @@ class YPetri::Net
     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? && 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>tsa</em> transitions in the net.
-  # 
-  def timeless_nonstoichiometric_nonassignment_transitions
-    transitions.select { |t|
-      t.timeless? && t.nonstoichiometric? && ! t.assignment_action?
-    }
-  end
-  alias tsa_transitions timeless_nonstoichiometric_nonassignment_transitions
-
-  # Names of <em>tsa</em> transitions in the net.
-  # 
-  def timeless_nonstoichiometric_nonassignment_tt
-    timeless_nonstoichiometric_nonassignment_transitions.map &:name
-  end
-  alias tsa_tt timeless_nonstoichiometric_nonassignment_tt
-
-  # Array of <em>tS</em> transitions in the net.
-  # 
-  def timeless_stoichiometric_transitions
-    transitions.select { |t| t.timeless? && 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? && t.nonstoichiometric? && 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? && t.stoichiometric? && 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? && 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.
+  # Is the net _functional_?
   # 
-  def assignment_transitions
-    transitions.select { |t| t.assignment_action? }
+  def functional?
+    transitions.all? { |t| t.functional? }
   end
-  alias A_transitions assignment_transitions
-
-  # Names of transitions with <em>explicit assignment action</em>
-  # (<em>A</em> transitions) in the net.
-  # 
-  def assignment_tt
-    assignment_transitions.map &:name
-  end
-  alias A_tt assignment_tt
-
-  # 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
+  def timed?
+    transitions.all? { |t| t.timed? }
+  end
 
   # Creates a new simulation from the net.
   # 
@@ -327,8 +123,6 @@ class YPetri::Net
     YPetri::TimedSimulation.new **named_args.merge( net: self )
   end
 
-  # ==== Sundry methods
-
   # Networks are equal when their places and transitions are equal.
   # 
   def == other
@@ -340,82 +134,10 @@ class YPetri::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
-    # Add places and transitions.
-    place_nodes = places.map.with_object Hash.new do |pl, ꜧ|
-      ꜧ[pl] = γ.add_nodes pl.name.to_s,
-                          fillcolor: 'lightgrey',
-                          color: 'grey',
-                          style: 'filled'
-    end
-    transition_nodes = transitions.map.with_object Hash.new do |tr, ꜧ|
-      ꜧ[tr] = γ.add_nodes tr.name.to_s,
-                          shape: 'box',
-                          fillcolor: if tr.assignment? then 'yellow'
-                                     elsif tr.basic_type == :SR then 'lightcyan'
-                                     else 'ghostwhite' end,
-                          color: if tr.assignment? then 'goldenrod'
-                                 elsif tr.basic_type == :SR then 'cyan'
-                                 else 'grey' end,
-                          style: 'filled'
-    end
-    # Add Petri net arcs.
-    transition_nodes.each { |tr, tr_node|
-      if tr.assignment? then
-        tr.codomain.each { |pl|
-          γ.add_edges tr_node, place_nodes[pl], color: 'goldenrod'
-        }
-        ( tr.domain - tr.codomain ).each { |pl|
-          γ.add_edges tr_node, place_nodes[pl], color: 'grey', arrowhead: 'none'
-        }
-      elsif tr.basic_type == :SR then
-        tr.codomain.each { |pl|
-          if tr.stoichio[pl] > 0 then # producing arc
-            γ.add_edges tr_node, place_nodes[pl], color: 'cyan'
-          elsif tr.stoichio[pl] < 0 then # consuming arc
-            γ.add_edges place_nodes[pl], tr_node, color: 'cyan'
-          else
-            γ.add_edges place_nodes[pl], tr_node, color: 'grey', arrowhead: 'none'
-          end
-        }
-        ( tr.domain - tr.codomain ).each { |pl|
-          γ.add_edges tr_node, place_nodes[pl], color: 'grey', arrowhead: 'none'
-        }
-      end
-    }
-    # Generate output image.
-    γ.output png: File.expand_path( "~/y_petri_graph.png" )
-    # require 'y_support/kde'
-    YSupport::KDE.show_file_with_kioclient File.expand_path( "~/y_petri_graph.png" )
+      "#{places.size} places, #{transitions.size} transitions" + ">"
   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/guard.rb

@@ -6,7 +6,9 @@ class YPetri::Place
   # Marking guard.
   # 
   class Guard
-    ERRMSG = -> m, assert { "Marking #{m}:#{m.class} #{assert}!" }
+    ERRMSG = -> m, pl, assert do
+      "Marking #{m}:#{m.class}#{pl ? " of place #{pl}" : ''} #{assert}!"
+    end
 
     attr_reader :assertion, :block
 
@@ -32,9 +34,9 @@ class YPetri::Place
     # Validates a supplied marking value against the guard block. Raises
     # +YPetri::GuardError+ if the guard fails, otherwise returns _true_.
     # 
-    def validate( marking_value )
-      λ = __fail__( marking_value, assertion )
-      λ.call if @Lab.new( λ ).instance_exec( marking_value, &block ) == false
+    def validate( marking, place=nil )
+      λ = __fail__( marking, place, assertion )
+      λ.call if @Lab.new( λ ).instance_exec( marking, &block ) == false
       return true
     end
 
@@ -42,8 +44,8 @@ class YPetri::Place
 
     # Constructs the fail closure.
     # 
-    def __fail__ marking_value, assertion
-      -> { fail YPetri::GuardError, ERRMSG.( marking_value, assertion ) }
+    def __fail__ marking, place, assertion
+      -> { fail YPetri::GuardError, ERRMSG.( marking, place, assertion ) }
     end
   end
 
@@ -92,7 +94,7 @@ class YPetri::Place
   # 
   def federated_guard_closure
     lineup = guards.dup
-    -> marking_value { lineup.each { |g| g.validate marking_value }; true }
+    -> m { lineup.each { |g| g.validate( m, self ) }; return m }
   end
 
   # Applies guards on the marking currently owned by the place.
@@ -109,14 +111,19 @@ class YPetri::Place
   # interchangeable, except complex numbers.
   # 
   def add_default_guards!( reference_marking )
-    ref_class = reference_marking.class
-    if ref_class < Numeric and not ref_class < Complex then
-      # Note that #marking method is overloaded to act as #guard method when
-      # a block is supplied to it:
-      marking "should be a number" do |m| m.is_a? Numeric end
+    case reference_marking
+    when Complex then marking "should be Numeric" do |m| m.is_a? Numeric end
+    when Numeric then
+      marking "should be Numeric" do |m| m.is_a? Numeric end
       marking "should not be complex" do |m| fail if m.is_a? Complex end
+      marking "should not be negative" do |m| m >= 0 end
+    when nil then # no guards
+    when true, false then marking "should be Boolean" do |m| m == !!m end
     else
-      marking "should be a #{ref_class}" do |m| m.is_a? ref_class end
+      reference_marking.class.tap do |klass|
+        marking "should be a #{klass}" do |m| m.is_a? klass end
+      end
     end
+    return nil
   end
 end # class YPetri::Place

data/lib/y_petri/place.rb

@@ -13,7 +13,6 @@ class YPetri::Place
   attr_reader :quantum
   attr_reader :guards
   attr_accessor :default_marking
-  attr_writer :marking
 
   # Named parameters supplied upon place initialization may include:
   # 
@@ -55,7 +54,7 @@ class YPetri::Place
                  &block
     @upstream_arcs, @downstream_arcs, @guards = [], [], [] # init to empty
     @quantum, @default_marking = quantum, default_marking
-    @marking = marking || default_marking
+    self.marking = marking || default_marking
 
     # Check in :guard named argument and &block.
     if guard.ℓ? then # guard NL assertion not given, use block or default guards
@@ -91,6 +90,12 @@ class YPetri::Place
     guard args[0], &block
   end
 
+  # Marking setter.
+  # 
+  def marking=( new_marking )
+    @marking = guard.( new_marking )
+  end
+
   # Alias for #marking=
   # 
   def value=( marking ); self.marking = marking end
@@ -101,20 +106,20 @@ class YPetri::Place
 
   # Adds tokens to the place.
   # 
-  def add( amount_of_tokens )
-    @marking += amount_of_tokens
+  def add( amount )
+    @marking = guard.( @marking + amount )
   end
 
   # Subtracts tokens from the place.
   # 
-  def subtract( amount_of_tokens )
-    @marking -= amount_of_tokens
+  def subtract( amount )
+    @marking = guard.( @marking - amount )
   end
 
   # Resets place marking back to its default marking.
   # 
   def reset_marking
-    @marking = @default_marking
+    @marking = guard.( @default_marking )
   end
 
   # Produces the inspect string of the place.

data/lib/y_petri/simulation.rb

@@ -1,14 +1,13 @@
 #encoding: utf-8
 
-# Emphasizing separation of concerns, the model is defined as agnostic of
-# simulation settings. Only for the purpose of simulation, model is combined
-# together with specific simulation settings. Simulation settings consist of
-# global settings (eg. time step, sampling rate...) and object specific
-# settings (eg. clamps, constraints...). Again, clamps and constraints *do
-# not* belong to the model. Simulation methods are also concern of this
-# class, not the model class. Thus, simulation is not done by calling
-# instance methods of the model. Instead, this class makes a 'mental image'
-# of the model and only that is used for actual simulation.
+# The Petri net model is agnostic of simulation settings. Only for the purpose
+# of simulation, model is combined together with specific simulation settings.
+# Simulation settings consist of global settings (time step, sampling rate...)
+# and object specific settings (clamps, constraints...). Again, clamps and
+# constraints *do not belong* to the model. The Petri net model is also agnostic
+# of the simulation methods. Simulation is not achieved by calling instance
+# methods of the model. Instead, Simulation class makes a 'mental image' of the
+# model, and uses that one in the actual simulation.
 #
 class YPetri::Simulation
   SAMPLING_DECIMAL_PLACES = 5

data/lib/y_petri/transition/assignment.rb

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+
+# Mixin for the transitions with assignment action.
+# 
+module YPetri::Transition::Assignment
+  # Transition's action (before validation).
+  # 
+  def action
+    action_closure.( *domain_marking )
+  end
+
+  # Applies action to the codomain, honoring cocking. Returns true if the transition
+  # fired, false if it wasn't cocked.
+  # 
+  def fire
+    cocked?.tap { |x| ( uncock; fire! ) if x }
+  end
+
+  # Assigns the action closure result to the codomain, regardless of cocking.
+  # 
+  def fire!
+    try "to call #fire! method" do
+      act = note "action", is: Array( action )
+      codomain.each_with_index do |codomain_place, i|
+        note "assigning action element no. #{i} to place #{codomain_place}"
+        codomain_place.marking = note "marking to assign", is: act.fetch( i )
+      end
+    end
+    return nil
+  end
+
+  # A transitions are always _enabled_.
+  # 
+  def enabled?
+    true
+  end
+end # class YPetri::Transition::Assignment

data/lib/y_petri/transition/{constructor_syntax.rb → construction.rb}

@@ -60,6 +60,7 @@ class YPetri::Transition
   #       
   def initialize *args
     check_in_arguments *args       # the big work of checking in args
+    extend timed? ? Timed : assignment? ? Assignment : OrdinaryTimeless
     inform_upstream_places         # that they have been connected
     inform_downstream_places       # that they have been connected
     uncock                         # transitions initialize uncocked

data/lib/y_petri/transition/ordinary_timeless.rb

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+
+# Mixin for timed non-assignment timeless Petri net transitions.
+# 
+module YPetri::Transition::OrdinaryTimeless
+  # Result of the transition's "function", regardless of the #enabled? status.
+  # 
+  def action
+    if stoichiometric? then
+      rslt = action_closure.( *domain_marking )
+      stoichiometry.map { |coeff| rslt * coeff }
+    else
+      action_closure.( *domain_marking )
+    end
+  end # action
+
+  # Fires the transition, honoring cocking. Returns true if the transition
+  # fired, false if it wasn't cocked.
+  # 
+  def fire
+    cocked?.tap { |x| ( uncock; fire! ) if x }
+  end
+
+  # Fires the transition regardless of cocking.
+  # 
+  def fire!
+    try "to call #fire method" do
+      act = note "action", is: Array( action )
+      codomain.each_with_index do |codomain_place, i|
+        note "adding action element no. #{i} to place #{codomain_place}"
+        codomain_place.add( note "marking change", is: act.fetch( i ) )
+      end
+    end
+    return nil
+  end
+
+  # Timeless transition is _enabled_ if its action would result in a legal
+  # codomain marking.
+  # 
+  def enabled?
+    codomain.zip( action ).all? do |place, change|
+      begin; place.guard.( place.marking + change )
+      rescue YPetri::GuardError; false end
+    end
+  end
+end # class YPetri::Transition::OrdinaryTimeless