y_petri 2.0.3 → 2.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7785c5d949ae026d98f538426713dbf8ba5c087b
-  data.tar.gz: ae69a454df83b31f1314dd2935282ab97e12653f
+  metadata.gz: f65095d233b7613fda917f4c1b7ef7f430d61f27
+  data.tar.gz: d65127c5a68f1e798ca08c418d4884dfdb1c511c
 SHA512:
-  metadata.gz: 3a6cb9bc4a188d7de73fd3dd01067772be90ecfbd6f9673fb1adcfee464d590b9d470faeb154d07b89a95e930525ce3c090682817440a23b79829027e5cdf6d8
-  data.tar.gz: fdaed6c9020950aa17a2345567d8fdece08b2987f237aa3448ace6dc75ef14d8f417951ce39690f7de3fab7b24722f0bfcbfe888d151863771ca5f1328f36127
+  metadata.gz: b10bfea43b1e4a9f531ce953cac4e943fd8570d5b441acbc9e84a1f16e2d20a6ab445ff9ffe4c76c4d8ae914f876d0814a8b28d57aa7abdd356e22e19b0755e9
+  data.tar.gz: e2eae4ee3ecb0259979634d3b8f21982d9d93e3b6cc2e82fe658f3561b591f36d5a31af521815a3b4b741d1553796b79332e1ec8c27b564cd88e9d9b1ad3e572

data/lib/y_petri/dependency_injection.rb

@@ -0,0 +1,45 @@
+#encoding: utf-8
+
+# Provides basic skeleton for dependency injection for the triples of the
+# parametrized subclasses of Place, Transition and Net in different workspaces.
+#
+module YPetri::DependencyInjection
+
+  private
+
+  # Place class -- to be overriden in subclasses for dependency injection.
+  # 
+  def Place
+    YPetri::Place
+  end
+
+  # Transition class -- to be overriden in subclasses for dependency injection.
+  # 
+  def Transition
+    YPetri::Transition
+  end
+
+  # Net class -- to be overriden in subclasses for dependency injection
+  # 
+  def Net
+    YPetri::Net
+  end
+
+  # Place instance identification.
+  # 
+  def place id
+    Place().instance( id )
+  end
+
+  # Transition instance identification.
+  # 
+  def transition id
+    Transition().instance( id )
+  end
+
+  # Net instance identification.
+  # 
+  def net id
+    Net().instance( id )
+  end
+end # module YPetri::DependencyInjection

data/lib/y_petri/manipulator/petri_net_related_methods.rb

@@ -26,30 +26,49 @@ module YPetri::Manipulator::PetriNetRelatedMethods
 
   # Place constructor: Creates a new place in the current workspace.
   # 
-  def Place *args, &b; workspace.Place.new *args, &b end
+  def Place( *ordered_args, **named_args, &block )
+    fail ArgumentError, "If block is given, :guard named argument " +
+      "must not be given!" if named_args.has? :guard if block
+    named_args.update( guard: block ) if block # use block as a guard
+    named_args.may_have :default_marking, syn!: :m!
+    named_args.may_have :marking, syn!: :m
+    workspace.Place.new *ordered_args, **named_args
+  end
 
   # Transiton constructor: Creates a new transition in the current workspace.
   # 
-  def Transition *args, &b; workspace.Transition.new *args, &b end
+  def Transition( *aa, **oo, &b )
+    workspace.Transition.new *aa, **oo, &b
+  end
 
   # Net constructor: Creates a new Net instance in the current workspace.
   # 
-  def Net *args, &b; workspace.Net.new *args, &b end
+  def Net *aa, **oo, &b
+    workspace.Net.new *aa, **oo, &b
+  end
 
   # Returns the net identified, or the net at point (if no argument given).
   # 
-  def net id=nil; id.nil? ? @net_point : workspace.net( id ) end
+  def net id=nil
+    id.nil? ? @net_point : workspace.net( id )
+  end
 
   # Returns the name of the identified net, or of the net at point (if no
   # argument given).
   # 
-  def ne id=nil; net( id ).name end
+  def ne id=nil
+    net( id ).name
+  end
 
   # Sets net point to workspace.Net::Top
   # 
-  def net_point_reset; net_point_set( workspace.Net::Top ) end
+  def net_point_reset
+    net_point_set( workspace.Net::Top )
+  end
 
   # Sets net point to the net identified by the argument (by name or instance).
   # 
-  def net_point_set id; @net_point = workspace.net( id ) end
+  def net_point_set id
+    @net_point = workspace.net( id )
+  end
 end # module YPetri::Manipulator::PetriNetRelatedMethods

data/lib/y_petri/manipulator/simulation_related_methods.rb

@@ -31,8 +31,8 @@ module YPetri::Manipulator::SimulationRelatedMethods
     # A simulation is identified either by its name (if named), or by its
     # parameters and settings (:net, :cc, :imc, :ssc).
     # 
-    def set *args
-      key = identify *args
+    def set **nn
+      key = identify **nn
       @key = if key.nil? then key
              elsif @hash.has_key? key then key
              else raise "No simulation identified by #{key}!" end
@@ -40,8 +40,8 @@ module YPetri::Manipulator::SimulationRelatedMethods
 
     # Helper method specifying how a simulation is identified by arguments.
     # 
-    def identify( simulation_name=nil, net: nil, cc: nil, imc: nil, ssc: nil )
-      simulation_name || { net: net, cc: cc, imc: imc, ssc: ssc }
+    def identify( name: nil, net: nil, cc: nil, imc: nil, ssc: nil, **nn )
+      name || { net: net, cc: cc, imc: imc, ssc: ssc }.merge( nn )
     end
   end
 

data/lib/y_petri/net.rb

@@ -113,7 +113,7 @@ class YPetri::Net
   # Array of <em>ts</em> transitions in the net.
   # 
   def timeless_nonstoichiometric_transitions
-    transitions.select{ |t| t.timeless? and t.nonstoichiometric? }
+    transitions.select { |t| t.timeless? && t.nonstoichiometric? }
   end
   alias ts_transitions timeless_nonstoichiometric_transitions
 
@@ -124,10 +124,26 @@ class YPetri::Net
   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? and t.stoichiometric? }
+    transitions.select { |t| t.timeless? && t.stoichiometric? }
   end
   alias tS_transitions timeless_stoichiometric_transitions
 
@@ -141,7 +157,7 @@ class YPetri::Net
   # 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? }
+    transitions.select { |t| t.timed? && t.nonstoichiometric? && t.rateless? }
   end
   alias timed_rateless_nonstoichiometric_transitions \
         timed_nonstoichiometric_transitions_without_rate
@@ -159,7 +175,7 @@ class YPetri::Net
   # 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? }
+    transitions.select { |t| t.timed? && t.stoichiometric? && t.rateless? }
   end
   alias timed_rateless_stoichiometric_transitions \
         timed_stoichiometric_transitions_without_rate
@@ -176,7 +192,7 @@ class YPetri::Net
   # Array of <em>sR</em> transitions in the net.
   # 
   def nonstoichiometric_transitions_with_rate
-    transitions.select { |t| t.has_rate? and t.nonstoichiometric? }
+    transitions.select { |t| t.has_rate? && t.nonstoichiometric? }
   end
   alias sR_transitions nonstoichiometric_transitions_with_rate
 
@@ -204,23 +220,18 @@ class YPetri::Net
   # Array of transitions with <em>explicit assignment action</em>
   # (<em>A</em> transitions) in the net.
   # 
-  def transitions_with_explicit_assignment_action
+  def assignment_transitions
     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
+  alias A_transitions assignment_transitions
 
   # 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
+  def assignment_tt
+    assignment_transitions.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
+  alias A_tt assignment_tt
 
   # Array of <em>stoichiometric</em> transitions in the net.
   # 
@@ -306,16 +317,14 @@ class YPetri::Net
 
   # Creates a new simulation from the net.
   # 
-  def new_simulation *args
-    oo = args.extract_options!
-    YPetri::Simulation.new *args, oo.merge( net: self )
+  def new_simulation( **named_args )
+    YPetri::Simulation.new **named_args.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 )
+  def new_timed_simulation( **named_args )
+    YPetri::TimedSimulation.new **named_args.merge( net: self )
   end
 
   # ==== Sundry methods

data/lib/y_petri/place/arcs.rb

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+
+# Connectivity aspect of a Petri net place.
+# 
+class YPetri::Place
+  # Transitions that can directly add/remove tokens from this place. Aliased as
+  # +#upstream_transitions+ and +#ϝ+. (Digamma resembles "f", meaning function,
+  # well known from existing spreadsheet software.)
+  # 
+  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
+
+  # All the transitions connected to the place.
+  # 
+  def arcs
+    upstream_arcs | downstream_arcs
+  end
+
+  # Union of the domains of the upstream transitions.
+  # 
+  def precedents
+    upstream_transitions.map( &:upstream_places ).reduce( [], :| )
+  end
+  alias :upstream_places :precedents
+
+  # Union of the codomains of the downstream transitions.
+  # 
+  def dependents
+    downstream_transitions.map( &:downstream_places ).reduce( [], :| )
+  end
+  alias :downstream_places :dependents
+
+  # Fires the upstream transitions.
+  # 
+  def fire_upstream
+    upstream_arcs.each &:fire
+  end
+
+  # Fires the upstream transitions regardless of cocking. (Normally, transitions
+  # should be cocked (+#cock+ method) before they are fired (+#fire+ method).)
+  # 
+  def fire_upstream!
+    upstream_arcs.each &:fire!
+  end
+
+  # Fires the whole upstream portion of the net. Cocking ensures that the
+  # recursive firing will eventually end.
+  # 
+  def fire_upstream_recursively
+    # LATER: This as a global hash { place => fire_list }
+    @upstream_arcs.each &:fire_upstream_recursively
+  end
+
+  # Fires the downstream transitions.
+  # 
+  def fire_downstream
+    downstream_arcs.each &:fire
+  end
+
+  # Fires the downstream transitions regardless of cocking. (Normally,
+  # transitions should be cocked (+#cock+ method) before they are fired (+#fire+
+  # method).)
+  # 
+  def fire_downstream!
+    @downstream_arcs.each &:fire!
+  end
+
+  # Fires the whole downstream portion of the net. Cocking ensures that the
+  # recursive firing will eventually end.
+  # 
+  def fire_downstream_recursively
+    # LATER: This as a global hash { place => fire_list }
+    @downstream_arcs.each &:fire_downstream_recursively
+  end
+
+  private
+
+  # Notes a new upstream transition.
+  # 
+  def register_upstream_transition( transition )
+    @upstream_arcs << transition
+  end
+
+  # Notes a new downstream transition.
+  # 
+  def register_downstream_transition( transition )
+    @downstream_arcs << transition
+  end
+end # class YPetri::Place

data/lib/y_petri/place/guard.rb

@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+
+# Guard mechanics aspect of a place.
+# 
+class YPetri::Place
+  # Marking guard.
+  # 
+  class Guard
+    ERRMSG = -> m, assert { "Marking #{m}:#{m.class} #{assert}!" }
+
+    attr_reader :assertion, :block
+
+    # Requires a NL guard assertion (used in GuardError messages), and a guard
+    # block expressing the same assertion formally, in code.  Attention: *Only
+    # _false_ result is considered a failure! If the block returns _nil_, the
+    # guard has passed!* When +YPetri::Guard+ is in action (typically via its
+    # +#validate+ method), it raises +YPetri::GuardError+ if the guard block
+    # returns _false_. However, the guard block is welcome to raise +GuardError+
+    # on its own, and for this purpose, it is evaluated inside a special "Lab"
+    # object, with +#fail+ method redefined so as to accept no arguments, and
+    # automatically raise appropriately worded +GuardError+. See also:
+    # {+YPetri#guard+ method}[rdoc-ref:YPetri::guard].
+    # 
+    def initialize assertion_NL_string, &block
+      @assertion, @block = assertion_NL_string, block
+      @Lab = Class.new BasicObject do
+        def initialize λ; @λ = λ end
+        def fail; @λ.call end
+      end
+    end
+
+    # 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
+      return true
+    end
+
+    private
+
+    # Constructs the fail closure.
+    # 
+    def __fail__ marking_value, assertion
+      -> { fail YPetri::GuardError, ERRMSG.( marking_value, assertion ) }
+    end
+  end
+
+  # Expects a guard assertion in natural language, and a guard block. Guard
+  # block is a unary block capable of validating a marking value. The validation
+  # is considered as having failed if:
+  #
+  # 1. The block returns _false_.
+  # 2. The block raises +YPetri::GuardError+.
+  #
+  # In all other cases, including the block returning _nil_, the validation is
+  # considered as having passed! The block is evaluated in the context of a
+  # special "Lab" object, which has +#fail+ method redefined so that it can
+  # (and must) be called without parameters, and produces an appropriately
+  # worded +GuardError+. (Other exceptions can be still raised using +#raise+
+  # method.)
+  # 
+  # As for the NL assertion, apart from self-documenting the code, it is used
+  # for constructing appropriately worded +GuardError+ messages:
+  #
+  #   guard "should be a number" do |m| fail unless m.is_a? Numeric end
+  #
+  # Then +guard! :foobar+ raises +GuardError+ with message "Marking foobar:Symbol
+  # should be a number!"
+  #
+  # The method returns the reference to the +YPetri::Guard+ object, that has
+  # been constructed and already included in the collection of this place's
+  # guards.
+  #
+  # Finally, this method is overloaded in such way, that if no block is
+  # given to it, it acts as a frontend for the +#federated_guard_closure+
+  # method: It either applies the federated closure to the marking value given
+  # in the argument, or returns the federated closure itself if no arguemnts
+  # were given (behaving as +#federated_guard_closure+ alias in this case).
+  # 
+  def guard *args, &block
+    if block then @guards << Guard.new( *args, &block )
+    elsif args.size == 1 then federated_guard_closure.( args[0] )
+    elsif args.empty? then federated_guard_closure
+    end
+  end
+
+  # Returns a joint guard closure, composed of all the guards defined for the
+  # place at the moment. Joint closure passes if and only if all the guard
+  # blocks pass for the given marking value.
+  # 
+  def federated_guard_closure
+    lineup = guards.dup
+    -> marking_value { lineup.each { |g| g.validate marking_value }; true }
+  end
+
+  # Applies guards on the marking currently owned by the place.
+  # 
+  def guard!
+    guard.( marking )
+  end
+
+  private
+
+  # If no guards were specified by the user, this method can make them up in a
+  # standard way, using user-supplied marking / default marking as a type
+  # reference. Numeric types are an exception – they are considered mutually
+  # 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
+      marking "should not be complex" do |m| fail if m.is_a? Complex end
+    else
+      marking "should be a #{ref_class}" do |m| m.is_a? ref_class end
+    end
+  end
+end # class YPetri::Place