y_petri 2.2.4 → 2.3.2

data/lib/y_petri/simulation.rb

@@ -2,9 +2,9 @@
 
 require_relative 'simulation/matrix'
 require_relative 'simulation/dependency'
-require_relative 'simulation/element_representation'
-require_relative 'simulation/elements'
-require_relative 'simulation/elements/access'
+require_relative 'simulation/node_representation'
+require_relative 'simulation/nodes'
+require_relative 'simulation/nodes/access'
 require_relative 'simulation/place_representation'
 require_relative 'simulation/places'
 require_relative 'simulation/places/access'
@@ -22,22 +22,22 @@ require_relative 'simulation/recorder'
 require_relative 'simulation/timeless'
 require_relative 'simulation/timed'
 
-# Represents a Petri net simulation, concerning are the simulation method and
-# settings, initial values, marking clamps, guards and similar. Its concerns are
-# are separated from those of the Petri net domain model (existence, naming,
-# connectivity, functions...). Clamps, guards, initial values etc. <b>do not
-# belong</b> to the model, although for convenience, places may carry default
-# initial marking, guards, and clamps for use in the token game. Simulation
-# instance can also use these if none other are specified.
+# Represents a Petri net simulation. Its concerns include the simulation method,
+# simulation settings, initial values, marking clamps used during the simulation,
+# guards etc. Its concerns do not include the Petri net domain model as such
+# (places, transitions, arcs, transition functions...)
 # 
-# A simulation distinguishes between free and clamped places. For free places,
-# initial marking has to be specified. For clamped places, marking clamps have
-# to be specified. Both come as hashes:
+# In a simulation, some places are designated as free (ie. their marking is free
+# to be changed by firing of the net's transitions), while others are clamped
+# (their marking is clamped by the simulation rather than changed by the
+# transitions). For free places, initial marking has to be specified. For
+# clamped places, marking clamps have to be specified. (For convenience, places
+# may carry their own initial marking.)
 # 
 class YPetri::Simulation
   ★ Places::Access                   # ★ means include
   ★ Transitions::Access
-  ★ Elements::Access
+  ★ Nodes::Access
   ★ InitialMarking::Access
   ★ MarkingClamps::Access
   ★ MarkingVector::Access
@@ -52,7 +52,7 @@ class YPetri::Simulation
     end
   end
 
-  # Parametrized subclasses:
+  # Parametrized subclasses.
   attr_reader :core,
               :recorder,
               :guarded,
@@ -64,7 +64,7 @@ class YPetri::Simulation
               :Ts_gradient_closure,
               :tS_firing_closure,
               :TS_rate_closure,
-              :A_assignment_closure,
+              :A_direct_assignment_closure,
               :increment_marking_vector_closure
 
   alias guarded? guarded
@@ -72,12 +72,12 @@ class YPetri::Simulation
   delegate :net, to: "self.class"
 
   delegate :simulation_method,
-           :guarded?,
            :step!,
            :firing_vector_tS,
            to: :core
 
   delegate :recording,
+           :back!,
            to: :recorder
 
   alias r recording
@@ -99,7 +99,7 @@ class YPetri::Simulation
 
   # Firing of the indicated tS transitions (as hash with transition names as
   # keys).
-  # 
+  #
   def t_firing ids=nil
     tS_transitions( ids ).names( true ) >> firing( ids )
   end
@@ -113,69 +113,63 @@ class YPetri::Simulation
     t_firing( ids ).pretty_print_numeric_values( gap: gap, precision: precision )
   end
 
-  # The basic simulation parameter is :net – +YPetri::Net+ instance which to
-  # simulate. Net implies the collection of places and transitions. Other
-  # required attributes are +:marking_clamps+ and +:initial_marking+
+  # The basic simulation parameter is +:net+ – a collection of places and
+  # transitions (a <tt>YPetri::Net</tt> instance) that is simulated. Other
+  # required arguments are +:marking_clamps+ and +:initial_marking+
   # (or +:marking -- if no +:initial_marking+ is supplied, +:marking+ will be
-  # used in its stead). There is a possibility to extract the initial marking
-  # from the net elements directly, controlled by the optional argument
-  # +:use_default_marking+, _true_ by default. It means that even if the caller
-  # does not supply required +:initial_marking+ values, the constructor will
-  # extract them from the places, so long as these have their initial markings
-  # set. Setting +:use_default_marking+ to _false_ will cause an error unless
-  # +:initial_marking+ and +:place_clamps+ are supplied explicitly. 
+  # used in its stead). Even when the caller did not provide all the
+  # +:initial_marking+, there is an option of extracting them from the place
+  # instances themselves. This option, controlled by the named argument
+  # +use_default_marking+, is normally set to _true_, to turn it off, change
+  # it to _false_.
   # 
-  # Simulation method is controlled by the :method argument, guarding is
-  # switched on and off by the :guarded argument (_true_ / _false_). Simulations
-  # of timed nets are timed. A timed simulation constructor may have +:time+
-  # (alias +:time_range+), +:step+, controlling the size of the simulation step,
-  # and +:sampling+, controlling the sampling period. At least one of these named
-  # arguments has to be set for timed simulations.
+  # Simulation method is set by +:method+ named argument, guarding is controlled
+  # by +:guarded+ named argument (_true_/_false_). Simulations of timed nets are
+  # also timed. For a timed simulation, the constructor permits named arguments
+  # +:time+ (alias +:time_range+), +:step+ (simulation step size), and
+  # +:sampling+ (sampling period), and requires that at least one of these named
+  # arguments be supplied.
   # 
-  def initialize **settings
-    @guarded = settings[:guarded] # guarding on / off
-    m_clamps = settings[:marking_clamps] || {}
-    m = settings[:marking]
-    init_m = settings[:initial_marking] || {}
-    use_default_marking = if settings.has? :use_default_marking then
-                            settings[ :use_default_marking ]
-                          else true end
-    # Time-independent simulation settings received, constructing param. classes
-    param_class!( { Place: PlaceRepresentation,
+  def initialize use_default_marking: true,
+                 guarded: false,
+                 marking_clamps: {},
+                 initial_marking: {},
+                 marking: nil,
+                 **settings
+    param_class!( { Place: PlaceRepresentation, # parametrized subclasses
                     Places: Places,
                     Transition: TransitionRepresentation,
                     Transitions: Transitions,
+                    Nodes: Nodes,
                     PlaceMapping: PlaceMapping,
                     InitialMarking: InitialMarking,
                     MarkingClamps: MarkingClamps,
                     MarkingVector: MarkingVector },
                   with: { simulation: self } )
-    # Place and transition representation classes are their own namespaces.
-    Place().namespace!
-    Transition().namespace!
-    # Set up the places collection.
+    [ Place(), Transition() ].each &:namespace! # each serves as its namespace
+    @guarded = guarded # TODO: Not operable as of now.
     @places = Places().load( net.places )
-    # Clamped places' mapping to the clamp values.
-    @marking_clamps = MarkingClamps().load( m_clamps )
-    # Free places' mapping to the initial marking values.
-    @initial_marking = InitialMarking()
-      .load( if m then # use :marking as :initial_marking when possible
-               init_m_from_init_m = PlaceMapping().load( init_m )
-               init_m_from_marking = PlaceMapping().load( m )
-               init_m_from_marking.merge init_m_from_init_m
-             else init_m end )
-    # Set up the place and transition collections.
-    @places.complete_initial_marking( use_default_marking: use_default_marking )
-    # Correspondence matrix free --> all
+    @marking_clamps = MarkingClamps().load( marking_clamps )
+    @initial_marking = if marking then
+                         m = PlaceMapping().load( marking )
+                         im = PlaceMapping().load( initial_marking )
+                         InitialMarking().load( m.merge im )
+                       else
+                         InitialMarking().load( initial_marking )
+                       end
+    # Fill in the missing initial marking from the places' default marking.
+    @places.send( :complete_initial_marking,
+                  use_default_marking: use_default_marking )
+    # Correspondence matrix free places --> all places
     @f2a = free_places.correspondence_matrix( places )
-    # Correspondence matrix clamped --> all
+    # Correspondence matrix clamped places --> all places
     @c2a = clamped_places.correspondence_matrix( places )
     # Conditionally extend self depending on net's timedness.
-    anything_time = settings[:time] || settings[:step] || settings[:sampling]
-    extend( anything_time ? Timed : Timeless )
+    time_mentioned = settings[:time] || settings[:step] || settings[:sampling]
+    if time_mentioned then extend Timed else extend Timeless end
     # Initialize the marking vector.
     @m_vector = MarkingVector().zero
-    # Set up the transitions collection.
+    # Set up the collection of transitions.
     @transitions = Transitions().load( net.transitions )
     # Set up stoichiometry matrices relative to free places.
     @tS_stoichiometry_matrix = transitions.tS.stoichiometry_matrix
@@ -183,46 +177,48 @@ class YPetri::Simulation
     # Set up stoichiometry matrices relative to all places.
     @tS_SM = transitions.tS.SM
     @TS_SM = transitions.TS.SM
-    # Call timedness-dependent initialization.
+    # Call timedness-dependent #init subroutine.
     init **settings
-    # Make timeless closures.
+    # Make time-independent closures.
     @ts_delta_closure = transitions.ts.delta_closure
     @tS_firing_closure = transitions.tS.firing_closure
-    @A_assignment_closure = transitions.A.assignment_closure
+    @A_direct_assignment_closure = transitions.A.direct_assignment_closure
     @increment_marking_vector_closure = m_vector.increment_closure
-    # Make timed closures.
+    # Make timed-only closures.
     if timed? then
       @Ts_gradient_closure = transitions.Ts.gradient_closure
       @TS_rate_closure = transitions.TS.rate_closure
     end
     # Reset.
-    if m then reset! marking: m else reset! end
+    if marking then reset! marking: marking else reset! end
   end
 
   # Simulation settings.
   # 
   def settings all=false
     return { method: simulation_method, guarded: guarded? } unless all == true
-    settings( false )
-      .update( net: net,
-               marking_clamps: marking_clamps.keys_to_source_places,
-               initial_marking: initial_marking.keys_to_source_places )
+    { net: net,
+      marking_clamps: marking_clamps.keys_to_source_places,
+      initial_marking: initial_markings.keys_to_source_places
+    }.update( settings )
   end
 
   # Returns a new simulation instance. Unless modified by arguments, the state
   # of the new instance is the same as the creator's. Arguments can partially or
   # wholly modify the attributes of the duplicate.
   # 
-  def dup( marking: marking, recording: recording, **nn )
-    self.class.new( nn.reverse_merge! settings( true ) ).tap do |dup|
-      dup.recording.reset! recording: recording
-      dup.m_vector.reset! case marking
-                          when Hash then
-                            m_vector.to_hash_with_source_places
-                              .update( PlaceMapping().load( marking ) )
-                              .to_marking_vector
-                          when Matrix, Array then marking
-                          else marking.each.to_a end
+  def dup( marking: marking, recording: recording, **named_args )
+    named_args.reverse_merge! settings( true )
+    self.class.new( named_args ).tap do |duplicate|
+      duplicate.recorder.reset! recording: recording
+      duplicate.m_vector.reset! case marking
+                                when Hash then
+                                  m_vector.to_hash_with_source_places
+                                    .update( PlaceMapping().load( marking )
+                                               .to_marking_vector
+                                               .to_hash_with_source_places )
+                                when Matrix, Array then marking
+                                else marking.each.to_a end
     end
   end
 
@@ -240,12 +236,10 @@ class YPetri::Simulation
 
   # Resets the simulation.
   # 
-  def reset! **nn
-    m = nn[:marking]
+  def reset! marking: nil, **named_args
     tap do
-      if m then m_vector.reset! m else m_vector.reset! end
-      recorder.reset!
-      recorder.alert
+      marking ? m_vector.reset!( marking ) : m_vector.reset!
+      recorder.reset!.alert!
     end
   end
 
@@ -258,7 +252,7 @@ class YPetri::Simulation
 
   # Extract a prescribed set of features.
   # 
-  def get_features arg
-    net.State.features( arg ).extract_from( self )
+  def get_features *args
+    net.State.Features( *args ).extract_from( self )
   end
 end # class YPetri::Simulation

data/lib/y_petri/transition/A.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: utf-8
 
 # Mixin for the transitions with assignment action.
 # 
@@ -24,7 +24,7 @@ module YPetri::Transition::Type_A
       msg = "Wrong output arity of the action closure of #{self}"
       fail TypeError, msg if act.size != codomain.size
       codomain.each_with_index { |p, i|
-        note "assigning action element no. #{i} to #{p}"
+        note "assigning action node no. #{i} to #{p}"
         p.marking = note "marking to assign", is: act.fetch( i )
       }
     end
@@ -36,4 +36,10 @@ module YPetri::Transition::Type_A
   def enabled?
     true
   end
+
+  # Transition's assignment action under current simulation.
+  # 
+  def a simulation=world.simulation
+    simulation.net.State.Feature.Assignment( self ) % simulation
+  end
 end # class YPetri::Transition::Type_A

data/lib/y_petri/transition/T.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: utf-8
 
 # Mixin for timed Petri net transitions.
 # 
@@ -30,7 +30,7 @@ module YPetri::Transition::Type_T
       msg = "Wrong output arity of the action closure of #{self}!"
       fail TypeError, msg if act.size != codomain.size
       codomain.each_with_index do |p, i|
-        note "adding action element no. #{i} to #{p}"
+        note "adding action node no. #{i} to #{p}"
         p.add note( "marking change", is: act.fetch( i ) )
       end
     end
@@ -47,4 +47,27 @@ module YPetri::Transition::Type_T
       rescue YPetri::GuardError; false end
     end
   end
+
+  # Transition's firing under current simulation.
+  # 
+  def fir simulation=world.simulation, **nn
+    nn.must_have :delta_time, syn!: :Δt
+    Δt = nn.delete( :delta_time ) || simulation.step
+    simulation.net.State.Feature.Firing( self ) % [ simulation, Δt: Δt ]
+  end
+
+  # Transition's flux under current simulation.
+  # 
+  def f simulation=world.simulation
+    simulation.net.State.Feature.Flux( self ) % simulation
+  end
+
+  # Prints the transition's action under current simulation.
+  #
+  def pa simulation=world.simulation, **nn
+    nn.must_have :delta_time, syn!: :Δt
+    Δt = nn.delete( :delta_time ) || simulation.step
+    ff = simulation.net.State.Features.Delta( codomain, transitions: self )
+    ( ff >> ff % simulation ).pretty_print_numeric_values( **nn )
+  end
 end # class YPetri::Transition::Type_T

data/lib/y_petri/transition/arcs.rb

@@ -15,11 +15,27 @@ module YPetri::Transition::Arcs
 
   # Union of action arcs and test arcs.
   # 
-  def arcs; domain | codomain end
+  def arcs
+    domain | codomain
+  end
 
-  # Returns names of the (places connected to) the transition's arcs.
+  # Names of the places connected to the transition. 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; arcs.map { |p| p.name || p.object_id } end
+  def aa arg=nil
+    arcs.names arg
+  end
+
+  # Arc (a place connected to this transition) identifier.
+  # 
+  def arc id
+    place = place( id )
+    arcs.find { |p| p == place } or
+      fail TypeError, "No place #{id} connected to #{self}!"
+  end
 
   # Marking of the domain places.
   # 

data/lib/y_petri/transition/construction_convenience.rb

@@ -1,9 +1,9 @@
 # encoding: utf-8
 
 # Given the four transition types (TS, Ts, tS, ts), transition construction
-# is not an easy task. Actually, having convenient constructor syntax is an
-# important part of the functionality of the Transition class. Construction
-# related functionality is thus gathered together in this mixin.
+# is not an easy task. Having convenient constructor syntax is an important
+# part of the functionality of the Transition class. Construction related
+# functionality is thus gathered together in this mixin.
 # 
 module YPetri::Transition::ConstructionConvenience
   private
@@ -116,8 +116,8 @@ module YPetri::Transition::ConstructionConvenience
       end
     else # not a Proc, must guess user's intent
       λ = if stoichiometric? then # standard mass action
-            msg = "With numeric rate, domain must not be given!"
-            fail TypeError, msg if nn.has? :domain
+            fail TypeError, "With numeric rate, domain must not be given!" if
+              nn.has? :domain
             __standard_mass_action__( λ )
           else # constant closure
             msg = "With numeric rate and no stoichio., codomain size must be 1!"
@@ -126,8 +126,8 @@ module YPetri::Transition::ConstructionConvenience
               if dom == :missing then
                 dom = [] # Missing domain is natural here
               else # but should it was supplied explicitly, it must be empty.
-                msg = "Rate is a number, but domain is non-empty!"
-                fail TypeError, msg unless domain.empty? if nn.has? :domain
+                fail TypeError, "Rate is a number, but domain non-empty!" unless
+                  domain.empty? if nn.has? :domain
               end
             end
           end
@@ -191,8 +191,9 @@ module YPetri::Transition::ConstructionConvenience
         # plain factors, assuming that if these places were not involved
         # in the transition at all, the user would not be mentioning them.
         case coeff
-        when 0, -1 then marking * acc
-        else marking ** -coeff end
+        when 0 then marking * acc # coefficient 0 indicates plain factor
+        when -1 then marking * acc # for speed, 1 gets special treatment
+        else marking ** -coeff * acc end
       end
     end
   end
@@ -214,7 +215,7 @@ module YPetri::Transition::ConstructionConvenience
       else
         # array of stoichiometry coefficients
         msg = "With array-type stoichiometry, :codomain must be given!"
-        fail ArgumentError unless oo.has? :codomain
+        fail ArgumentError, msg unless oo.has? :codomain
         [ oo[:codomain], Array( oo[:stoichiometry] ) ]
       end
     # enforce that stoichiometry is a collection of numbers

data/lib/y_petri/transition/t.rb

@@ -29,7 +29,7 @@ module YPetri::Transition::Type_t
       msg = "Wrong output arity of the action closure of #{self}!"
       fail TypeError, msg if act.size != codomain.size
       codomain.each_with_index do |p, i|
-        note "adding action element no. #{i} to #{p}"
+        note "adding action node no. #{i} to #{p}"
         p.add note( "marking change", is: act.fetch( i ) )
       end
     end
@@ -45,4 +45,17 @@ module YPetri::Transition::Type_t
       rescue YPetri::GuardError; false end
     end
   end
+
+  # Transition's firing under current simulation.
+  # 
+  def fir simulation=world.simulation
+    simulation.net.State.Feature.Firing( self ) % simulation
+  end
+
+  # Prints the transition's action under current simulation.
+  # 
+  def pa simulation=world.simulation, **nn
+    ff = simulation.net.State.Features.Delta( codomain, transitions: self )
+    ( ff >> ff % simulation ).pretty_print_numeric_values **nn
+  end
 end # class YPetri::Transition::Type_t

data/lib/y_petri/transition/types.rb

@@ -41,9 +41,13 @@ module YPetri::Transition::Types
   end
   alias s? nonstoichiometric?
 
-  # Does the transition's action depend on delta time?
+  # Does the transition's action depend on delta time? (Note that although A
+  # transitions are technically timeless, for pragmatic reasons, they are
+  # excluded from T/t classification, because they are generally handled
+  # differently in Petri net execution.)
   # 
   def timed?
+    return nil if A?
     @timed
   end
   alias T? timed?
@@ -51,6 +55,7 @@ module YPetri::Transition::Types
   # Is the transition timeless? (Opposite of #timed?)
   # 
   def timeless?
+    return nil if A?
     not timed?
   end
   alias t? timeless?

data/lib/y_petri/transition.rb

@@ -53,6 +53,7 @@ require_relative 'transition/usable_without_world'
 # 2. *Stoichiometricity*: _stoichiometric_ (*S*) / _nonstoichiometric_ (*s*)
 # 
 # ==== Timedness
+
 # 
 # * Timed transitions have _rate_ _closure_, whose result is to be multiplied
 #   by +Δtime+.
@@ -168,7 +169,7 @@ class YPetri::Transition
             else Type_t end )
     inform_upstream_places         # that they have been connected
     inform_downstream_places       # that they have been connected
-    uncock                         # initialize in the uncocked state
+    uncock                         # initialize in uncocked state
   end
 
   # Domain, or 'upstream arcs', is a collection of places, whose marking
@@ -267,18 +268,14 @@ class YPetri::Transition
   #   return self
   # end
 
-  # Inspect string for a transition.
-  # 
-  def inspect
-    to_s
-  end
+  # Let's just leave this to NameMagic
 
-  # Conversion to a string.
-  # 
-  def to_s
-    "#<Transition: %s>" %
-      "#{'%s ' % name if name}(#{type})#{' id:%s' % object_id unless name}"
-  end
+  # # Conversion to a string.
+  # # 
+  # def to_s
+  #   "#<Transition: %s>" %
+  #     "#{'%s ' % name if name}(#{type})#{' id:%s' % object_id unless name}"
+  # end
 
   def place id
     super rescue Place().instance( id )

data/lib/y_petri/version.rb

@@ -1,4 +1,4 @@
 module YPetri
-  VERSION = "2.2.4"
+  VERSION = "2.3.2"
   DEBUG = false
 end

data/lib/y_petri/world/dependency.rb

@@ -19,16 +19,16 @@ class YPetri::World
       world.transition( id )
     end
 
-    # Element instance identification.
+    # Node instance identification.
     # 
-    def element id
+    def node id
       begin
         place( id )
       rescue NameError, TypeError
         begin
           transition( id )
         rescue NameError, TypeError => err
-          raise TypeError, "Unrecognized place or transition: #{element} (#{err})"
+          raise TypeError, "Unrecognized node: #{id} (#{err})"
         end
       end
     end

data/lib/y_petri/world/{petri_net_related.rb → petri_net_aspect.rb}

@@ -1,9 +1,9 @@
 # encoding: utf-8
 
-# Workspace instance methods related to Petri net itsef (places, transitions,
-# net instances).
+# Workspace instance methods related to the Petri net aspect of YPetri
+# (places, transitions, net instances).
 # 
-module YPetri::World::PetriNetRelated
+module YPetri::World::PetriNetAspect
   # Instance initialization.
   # 
   def initialize
@@ -58,4 +58,4 @@ module YPetri::World::PetriNetRelated
     # Hook new transitions to add themselves magically to the :Top net.
     Transition().new_instance_hook { |new_inst| net( :Top ) << new_inst }
   end
-end # module YPetri::World::PetriNetRelated
+end # module YPetri::World::PetriNetAspect