y_petri 2.2.4 → 2.3.2

data/lib/y_petri/net/state.rb

@@ -1,129 +1,95 @@
 # encoding: utf-8
 
-# An array whose elements correspond to the full marking of the net's places.
-#
+# An array whose elements represent marking of places of a +YPetri::Net+.
+# 
 class YPetri::Net::State < Array
   require_relative 'state/feature'
   require_relative 'state/features'
 
   class << self
-    # Customization of the parametrize method for the State class: Its
-    # dependents Feature and Features (feature set class) are also parametrized.
+    # Customization of the parametrize method for the State class: Its dependents
+    # Feature and Features (feature set class) are also parametrized.
     # 
     def parametrize net: ( fail ArgumentError, "No owning net!" )
       Class.new( self ).tap do |ç|
         ç.define_singleton_method :net do net end
-        ç.param_class( { Feature: Feature,
-                         Features: Features },
-                       with: { State: ç } )
+        ç.param_class!( { Feature: Feature,
+                          Features: Features },
+                        with: { State: ç } )
       end
     end
 
-    delegate :Marking,
-             :Firing,
-             :Gradient,
-             :Flux,
-             :Delta,
-             to: "Feature()"
-
     # Returns the feature identified by the argument.
-    # 
-    def feature *id
-      fail ArgumentError, "No feature identifier!" if id.empty?
-      case id.first
-      when Feature() then id.first
-      when Feature then id.first.class.new( id.first )
-      else
-        msg = "Malformed feature identifier!"
-        fail ArgumentError, msg unless id.size == 1 and id.first.is_a? Hash
-        ꜧ = id.first
-        fail ArgumentError, msg unless ꜧ.size == 1
-        key, val = ꜧ.keys.first, ꜧ.values.first
-        recognized = :marking, :firing, :gradient, :flux, :delta
-        msg = "Unrecognized feature: #{key}"
-        fail ArgumentError, msg unless recognized.include? key
-        # And now, with everything clean...
+    #
+    def Feature arg=nil, **named_args
+      case arg
+      when Feature() then arg
+      when Feature then arg.class.new( arg )
+      when nil then
+        key, val = named_args.first
         case key
-        when :marking then Marking( val )
-        when :firing then Firing( val )
-        when :flux then Flux( val )
-        when :gradient then Gradient( *val )
-        when :delta then Delta( *val )
+        when :marking then Feature().Marking( val )
+        when :firing then Feature().Firing( val )
+        when :flux then Feature().Flux( val )
+        when :gradient then Feature().Gradient( *val )
+        when :delta then Feature().Delta( *val )
+        when :assignment then Feature().Assignment( val )
+        else fail ArgumentError, "Unrecognized feature: #{key}!"
         end
+      else
+        Feature().infer_from_node( arg )
       end
     end
 
-    # If the argument is an array of features, or another Features instance,
-    # a feature set based on this array is returned. But the real purpose of
-    # this method is to allow hash-type argument, with keys +:marking+,
-    # +:firing+, +:gradient+, +:flux+ and +:delta+, specifying the respective
-    # features. For +:marking+, an array of places (or Marking features) is
-    # expected. For +:firing+ and +:flux+, an array of transitions (or Firing
-    # / Flux features) is expected. For +:gradient+ and +:delta+, a hash value
-    # is expected, containing keys +:places+ and +:transitions+, specifying
-    # for which place set / transition set should gradient / delta features
-    # be constructed. More in detail, values supplied under keys +:marking+,
-    # +:firing+, +:gradient+, +:flux+ and +:delta+ are delegated to
-    # +Features.marking+, +Features.firing+, +Features.gradient+ and
-    # +Features.flux+ methods, and their results are joined into a single
-    # feature set.
+    # A constructor of a +Features+ instance. Note that the message +:Features+
+    # called without arguments is intercepted by a singleton method and returns
+    # the parametrized subclass of +State::Features+ owned by this class.
     # 
-    def features arg
-      case arg
-      when Features(), Array then Features().new( arg )
-      else # the real job of the method
-        marking = arg[:marking] || []
-        firing = arg[:firing] || [] # array of tS transitions
-        gradient = arg[:gradient] || [ [], transitions: [] ]
-        flux = arg[:flux] || [] # array of TS transitions
-        delta = arg[:delta] || [ [], transitions: [] ]
-        [ Features().marking( marking ),
-          Features().firing( firing ),
-          Features().gradient( *gradient ),
-          Features().flux( flux ),
-          Features().delta( *delta ) ].reduce :+
-      end
+    # This method may accept a single array-type argument, constructing a feature
+    # set out of it. Alternatively, the method may accept named arguments:
+    # +:marking+, +:firing+, +:gradient+, +:flux+, +:delta+, and +:assignment+,
+    # specifying the a single (possibly mixed) feature set.
+    # 
+    def Features array=nil, **named_args
+      Features()[ *array, **named_args ]
     end
+  end # class << self
 
-    delegate :marking, :firing, :gradient, :flux, :delta, to: "Features()"
-  end
-
-  # For non-parametrized vesion of the class, the class instance variables
-  # hold the non-parametrized dependent classes.
+  # For non-parametrized vesion of the class, should it ever be used in such way,
+  # the class instance variables hold the non-parametrized dependent classes.
   # 
   @Feature, @Features = Feature, Features
 
   delegate :net,
-           :Feature,
-           :Features,
-           :features,
-           :marking, :firing, :gradient, :flux, :delta,
+           :Feature,             # Note that as syntactic salt, specific methods
+           :Features,            # #marking, #firing, #gradient, #flux etc. are
+           :features,            # not delegated to self.class.
            to: "self.class"
 
-  # Given a set of clamped places,  this method outputs a Record instance
+  # Given a set of clamped places, this method outputs a +Record+ instance
   # containing the marking of the free places (complementary to the supplied
   # set of clamped places). I no set of clamped places is supplied, it is
   # considered empty.
   # 
-  def to_record clamped_places=[]
+  def to_record clamped_places
     free_places = case clamped_places
                   when Hash then to_record( clamped_places.keys )
                   else
-                    free_places = places - places( clamped_places )
+                    places - places( clamped_places )
                   end
     features( marking: free_places ).Record.load markings( free_places ) 
   end
 
   # Marking of a single given place in this state.
   # 
-  def marking place_id
-    self[ places.index place( place_id ) ]
+  def marking place
+    self[ net.places.index net.place( place ) ]
   end
 
-  # Returns an array of markings of particular places in this state..
+  # Expects an arbitrary number of places or place ids, and returns an array
+  # of their markings as per the receiver +State+ instance.
   # 
-  def markings place_ids=nil
-    return markings( places ) if place_ids.nil?
-    place_ids.map &:marking
+  def markings *places
+    places.map &method( :marking )
   end
 end # YPetri::Net::State

data/lib/y_petri/net/visualization.rb

@@ -1,4 +1,4 @@
-#encoding: utf-8
+# encoding: utf-8
 
 # Own visualization capabilities of a Petri net.
 # 

data/lib/y_petri/net.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-require_relative 'net/element_access'
+require_relative 'net/node_access'
 require_relative 'net/visualization'
 require_relative 'net/own_state'
 require_relative 'net/data_set'
@@ -10,21 +10,33 @@ require_relative 'net/state'
 # connector arrows – called _arcs_ in classical Petri net terminology – can be
 # considered a property of transitions. Therefore in +YPetri::Net+, you won't
 # find arcs as first-class citizens, but only as a synonym denoting nearest
-# neighbors of elements (places or transitions).
+# neighbors of nodes (places or transitions).
 # 
 class YPetri::Net
+  # ===========================================================================
+  # !!! TODO !!!
+  #
+  # Refactoring plans for Net class
+  #
+  # Make it a subclass of Module class, so places and transitions can simply
+  # be defined as its constants.
+  #
+  # ===========================================================================
+
   ★ NameMagic                        # ★ means include
-  ★ ElementAccess                    # to be below ElementAccess
+  ★ NodeAccess
   ★ Visualization
   ★ OwnState
 
   class << self
     ★ YPetri::World::Dependency
 
-    # Constructs a net containing a particular set of elements.
+    private :new
+
+    # Constructs a net containing a particular set of nodes.
     # 
-    def of elements
-      new.tap { |inst| elements.each { |e| inst << e } }
+    def of nodes
+      new.tap { |inst| nodes.each { |node| inst << node } }
     end
   end
 
@@ -34,93 +46,95 @@ class YPetri::Net
   # Takes 2 arguments (+:places+ and +:transitions+) and builds a net from them.
   # 
   def initialize( places: [], transitions: [] )
-    param_class( { State: State }, with: { net: self } )
+    param_class!( { State: State,
+                    Simulation: YPetri::Simulation },
+                  with: { net: self } )
     @places, @transitions = [], []
     places.each &method( :include_place )
     transitions.each &method( :include_transition )
-    param_class( { Simulation: YPetri::Simulation },
-                 with: { net: self } )
   end
 
   # Includes a place in the receiver. Returns _true_ if successful, _false_ if
   # the place is already included in the receiver net. 
   # 
-  def include_place id
-    pl = Place().instance( id )
-    return false if includes_place? pl
-    true.tap { @places << pl }
+  def include_place place
+    place = Place().instance( place )
+    return false if include_place? place
+    true.tap { @places << place }
   end
 
   # Includes a transition in the receiver. 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 receiver net.
   # 
-  def include_transition id
-    tr = Transition().instance( id )
-    return false if includes_transition? tr
-    msg = "Transition #{tr} has arcs to places outside #{self}!"
-    fail msg unless tr.arcs.all? { |p| includes_place? p }
-    true.tap { @transitions << tr }
+  def include_transition transition
+    transition = Transition().instance( transition )
+    return false if include_transition? transition
+    fail "Transition #{transition} has arcs to places outside #{self}!" unless
+      transition.arcs.all? { |place| include_place? place }
+    true.tap { @transitions << transition }
   end
 
   # Excludes a place from the receiver. Returns _true_ if successful, _false_
   # if the place was not found in the receiver net. A place may not be excluded
   # from the receiver so long as any transitions therein connect to it.
   # 
-  def exclude_place id
-    pl = Place().instance( id )
-    msg = "Unable to exclude #{pl} from #{self}: Transition(s) depend on it!"
-    fail msg if transitions.any? { |tr| tr.arcs.include? pl }
-    false.tap { return true if @places.delete( pl ) }
+  def exclude_place place
+    place = Place().instance( place )
+    fail "Unable to exclude #{place} from #{self}: Transitions depend on it!" if
+      transitions.any? { |transition| transition.arcs.include? place }
+    false.tap { return true if @places.delete( place ) }
   end
 
   # Excludes a transition from the receiver. Returns _true_ if successful,
   # _false_ if the transition was not found in the receiver net.
   # 
-  def exclude_transition id
-    tr = Transition().instance( id )
-    false.tap { return true if @transitions.delete( tr ) }
+  def exclude_transition transition
+    transition = Transition().instance( transition )
+    false.tap { return true if @transitions.delete( transition ) }
   end
 
   # Includes another net in the receiver net. Returns _true_ if successful
   # (ie. if there was any change to the receiver net), _false_ if the receiver
   # net already includes the argument net.
   # 
-  def include_net id
-    net = Net().instance( id )
-    p_rslt = net.pp.map { |p| include_place p }.reduce :|
-    t_rslt = net.tt.map { |t| include_transition t }.reduce :|
-    p_rslt || t_rslt
+  def include_net net
+    net = Net().instance( net ) rescue YPetri::Net.instance( net )
+    p_results = net.pp.map &method( :include_place )
+    t_results = net.tt.map &method( :include_transition )
+    ( p_results + t_results ).reduce :|
   end
   alias merge! include_net
 
   # Excludes another net from the receiver net. Returns _true_ if successful
   # (ie. if there was any change to the receiver net), _false_ if the receiver
-  # net contained no element of the argument net.
+  # net contained no node of the argument net.
   # 
   def exclude_net id
-    net = Net().instance( id )
+    net = Net().instance( id ) rescue YPetri::Net.instance( net )
     t_rslt = net.tt.map { |t| exclude_transition t }.reduce :|
     p_rslt = net.pp.map { |p| exclude_place p }.reduce :|
     p_rslt || t_rslt
   end
 
-  # Includes an element (place or transition) in the net.
+  # Includes a node (place or transition) in the receiver net.
   # 
-  def << element_id
+  def << node
     begin
-      type, element = :place, self.class.place( element_id )
+      type = :place
+      place = self.class.place node
     rescue NameError, TypeError
       begin
-        type, element = :transition, self.class.transition( element_id )
+        type = :transition
+        transition = self.class.transition node
       rescue NameError, TypeError => err
-        raise TypeError, "Current world contains no place or transition " +
-          "identified by #{element_id}! (#{err})"
+        raise TypeError, "Current world contains no place or " +
+          "transition #{node}! (#{err})"
       end
     end
     case type # Factored out to minimize the code inside the rescue clause.
-    when :place then include_place( element )
-    when :transition then include_transition( element )
+    when :place then include_place( place )
+    when :transition then include_transition( transition )
     else fail "Implementation error!" end
     return self # important to enable chaining, eg. foo_net << p1 << p2 << t1
   end
@@ -135,12 +149,12 @@ class YPetri::Net
     end
   end
 
-  # Creates a new net that contains the places and transition of the receiver
-  # after excluding the second operand.
+  # Returns a new net that is the result of subtraction of the net given as
+  # argument from this net.
   # 
   def - other
     self.class.send( :new ).tap do |net|
-      net.merge! self
+      net.include_net self
       net.exclude_net other
     end
   end
@@ -148,13 +162,13 @@ class YPetri::Net
   # Is the net _functional_?
   # 
   def functional?
-    transitions.any? { |t| t.functional? }
+    transitions.any? &:functional?
   end
 
   # Is the net _timed_?
   # 
   def timed?
-    transitions.any? { |t| t.timed? }
+    transitions.any? &:timed?
   end
 
   # Creates a new simulation from the net.
@@ -162,6 +176,7 @@ class YPetri::Net
   def simulation( **settings )
     Simulation().__new__ **settings
   end
+  alias new_simulation simulation
 
   # Networks are equal when their places and transitions are equal.
   # 

data/lib/y_petri/place/arcs.rb

@@ -23,6 +23,24 @@ module YPetri::Place::Arcs
     upstream_arcs | downstream_arcs
   end
 
+  # Names of the transitions connected to the place. The optional argument
+  # controls what is returned for unnamed instances, and works just like in
+  # <tt>Array#names</tt> method from <tt>y_support/name_magic</tt>:
+  # The default value (_nil_) returns _nil_, _true_ returns the instance itself,
+  # and _false_ drops the unnamed instances from the list altogether.
+  # 
+  def aa arg=nil
+    arcs.names arg
+  end
+
+  # Arc (a transition connected to this place) identifier.
+  # 
+  def arc id
+    transition = transition( id )
+    arcs.find { |t| t == transition } or
+      fail TypeError, "No transition #{id} connected to #{self}!"
+  end
+
   # Union of the domains of the upstream transitions.
   # 
   def precedents
@@ -37,6 +55,32 @@ module YPetri::Place::Arcs
   end
   alias :downstream_places :dependents
 
+  # A net containing all the upstream transitions and their connected places.
+  # 
+  def upstream_net
+    net_klass = world.Net rescue YPetri::Net # for when not used as PS
+    upstream_transitions.each_with_object net_klass.send( :new ) do |t, net|
+      t.arcs.each { |place| net << place }
+      net << t
+    end
+  end
+
+  # A net containing all the upstream transitions and their connected places.
+  # 
+  def downstream_net
+    net_klass = world.Net rescue YPetri::Net # for when not used as PS
+    downstream_transitions.each_with_object net_klass.send( :new ) do |t, net|
+      t.arcs.each { |place| net << place }
+      net << t
+    end
+  end
+
+  # A union of upstream local net and downstream local net.
+  # 
+  def local_net
+    downstream_net + upstream_net
+  end
+
   # Fires the upstream transitions.
   # 
   def fire_upstream

data/lib/y_petri/place/features.rb

@@ -0,0 +1,115 @@
+# encoding: utf-8
+
+# Place instance methods concerned with state and/or simulation features.
+# 
+module YPetri::Place::Features
+  # Expects an array of transitions, and +:net+ named argument. Returns a single
+  # gradient feature belonging to the net for this place, and those upstream T
+  # transitions, that are also in the included in the array. If no ordered
+  # arguments are given, complete set of upstream T transitions is assumed. If
+  # no +:net+ is given, +Top+ is assumed.
+  # 
+  def Gradient array, net: world.net( :Top )
+    fail TypeError, "#{self} must be included in the net!" unless
+      net.include? self
+    transitions = upstream_arcs.select { |t| array.include? t }.select( &:T? )
+    net.State.Feature.Gradient( self, transitions: transitions )
+  end
+
+  # Expects an arbitrary number of transitions, and +:net+ named argument.
+  # Returns a single gradient feature belonging to the net for this place,
+  # and those upstream T transitions, that are also in the included among
+  # the arguments. If no ordered arguments are given, complete set of upstream
+  # T transitions is assumed. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def gradient *transitions, net: world.net( :Top )
+    return Gradient upstream_arcs, net: net if transitions.empty?
+    Gradient transitions, net: net
+  end
+
+  # Expects an array of transitions, and +:net+ named argument. Returns a
+  # feature set belonging to the net, consisting of the features for this
+  # place, and those upstream T transitions, that are also included in the
+  # array. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def Gradients array, net: world.net( :Top )
+    fail TypeError, "#{self} must be included in the net!" unless
+      net.include? self
+    transitions = upstream_arcs.select { |t| array.include? t }.select( &:T? )
+    net.State.Features( transitions.map { |t| gradient t, net: net } )
+  end
+
+  # Expects an arbitrary number of transitions, and +:net+ named argument.
+  # Returns a feature set belonging to the net, constisting of the features
+  # for this place, and those upstream T transitions, that are also included
+  # in the array. If no ordered arguments are given, complete set of upstream
+  # T transitions is assumed. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def gradients *transitions, net: world.net( :Top )
+    return Gradients upstream_arcs, net: net if transitions.empty?
+    Gradients transitions, net: net
+  end
+
+  # Expects an array of transitions, and +:net+ named argument. Returns a single
+  # delta feature belonging to the net for this place, and those upstream T
+  # transitions, that are also in the included in the array. If no ordered
+  # arguments are given, complete set of upstream T transitions is assumed. If
+  # no +:net+ is given, +Top+ is assumed.
+  # 
+  def Delta array, net: world.net( :Top )
+    fail TypeError, "#{self} must be included in the net!" unless
+      net.include? self
+    transitions = upstream_arcs.select { |t| array.include? t }.select( &:T? )
+    net.State.Feature.Delta( self, transitions: transitions )
+  end
+
+  # Expects an arbitrary number of transitions, and +:net+ named argument.
+  # Returns a single delta feature belonging to the net for this place,
+  # and those upstream T transitions, that are also in the included among
+  # the arguments. If no ordered arguments are given, complete set of upstream
+  # T transitions is assumed. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def delta *transitions, net: world.net( :Top )
+    return Delta upstream_arcs, net: net if transitions.empty?
+    Delta transitions, net: net
+  end
+
+  # Expects an array of transitions, and +:net+ named argument. Returns a
+  # feature set belonging to the net, consisting of the features for this
+  # place, and those upstream T transitions, that are also included in the
+  # array. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def Deltas array, net: world.net( :Top )
+    fail TypeError, "#{self} must be included in the net!" unless
+      net.include? self
+    transitions = upstream_arcs.select { |t| array.include? t }.select( &:T? )
+    net.State.Features( transitions.map { |t| delta t, net: net } )
+  end
+
+  # Expects an arbitrary number of transitions, and +:net+ named argument.
+  # Returns a feature set belonging to the net, constisting of the features
+  # for this place, and those upstream T transitions, that are also included
+  # in the array. If no ordered arguments are given, complete set of upstream
+  # T transitions is assumed. If no +:net+ is given, +Top+ is assumed.
+  # 
+  def deltas *transitions, net: world.net( :Top )
+    return Deltas upstream_arcs, net: net if transitions.empty?
+    Deltas transitions, net: net
+  end
+
+  # Convenience method. Prints gradients under curent simulation.
+  # 
+  def pg simulation=world.simulation, precision: 8, **nn
+    ( gradients >> gradients % simulation )
+      .pretty_print_numeric_values precision: precision, **nn
+  end
+
+  # Convenience method. Prints deltas under current simulation.
+  # 
+  def pd simulation=world.simulation, precision: 8, **nn
+    nn.may_have :delta_time, syn!: :Δt
+    delta_time = nn.delete( :delta_time ) || world.simulation.step
+    ( deltas >> deltas % [ simulation, delta_time: delta_time ] )
+      .pretty_print_numeric_values precision: precision, **nn
+  end
+end # class YPetri::Place::Features