y_petri 2.2.2 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b2ecda77bfc45a49d215cf17020f630ee0f34be
-  data.tar.gz: a83ad616cf8cd540ed9823e6a42938b4617312ff
+  metadata.gz: 4d21a38d5b195eb6616e741ee032954f2e3c8a5f
+  data.tar.gz: fe9679678f401d6842e9eecec61742a44e480882
 SHA512:
-  metadata.gz: 7ba1c8559c1fb4b906e176403bd4d015bc257535afc719f308cd658574fd5c7858a127d3ea138eac27f343dbffd66ebbb8c24f32a3a6a971e1bf121c16d32ed1
-  data.tar.gz: ab033d8eaabe98073c1d783450145232aaa09041947c66fa85b1069fe654a4c753f8372b948934f3b6523ceb0ba34fc7b3e2253ab103be3252be7df86230ea48
+  metadata.gz: 4329188c403e5c4491f0b716736ab70ff3094f49cc34c950713c9f881e233c52f853e5776bae401ddd5236e6cbcf03ab1b61d31616daf98a33d4233f3f1be2ee
+  data.tar.gz: b059ae5693243f584706b30457b0a9a2d593faa700f5f63ac30f5a5a68164e9041a8a82289338f1b54a3637586a3e8507def9f1d524863b4d5c9b7dab7890800

data/lib/y_petri/agent/simulation_related.rb

@@ -271,14 +271,14 @@ module YPetri::Agent::SimulationRelated
 
   # Plot system state history.
   # 
-  def plot_state( place_ids=nil, except: [],
+  def plot_marking( place_ids=nil, except: [],
                   title: "State plot", ylabel: "Marking [µM]",
                   **options )
     rec = simulation.recording
     pp = simulation.pp( place_ids ) - simulation.pp( except )
     rec.marking( pp ).plot( title: title, ylabel: ylabel, **options )
   end
-  alias plot_marking plot_state
+  alias plot_state plot_marking
 
   # Plot flux history of TS transitions.
   # 
@@ -327,10 +327,44 @@ module YPetri::Agent::SimulationRelated
     options.may_have :delta_time, syn!: :Δt
     rec = simulation.recording
     pp = simulation.pp( place_ids ) - simulation.ee( except )
-    tt = transitions.nil? ? simulation.tt : tranisitions
+    tt = transitions.nil? ? simulation.tt : transitions
     tt = simulation.tt( tt )
     tt -= simulation.ee( except )
     rec.delta( pp, transitions: tt, Δt: options[:delta_time] )
       .plot( title: title, ylabel: ylabel, **options )
   end
+
+  # # Pretty print marking of the current simulation.
+  # # 
+  # def marking
+    
+  # end
+  # alias state marking
+
+  # # Pretty print the flux for the current simulation state.
+  # # 
+  # def flux
+    
+  # end
+
+  # # Pretty print the firing for the current simulation state.
+  # # 
+  # def firing
+    
+  # end
+
+  # # Pretty print the gradient for the current simulation state.
+  # # 
+  # def gradient
+    
+  # end
+
+  # # Pretty print deltas for the current simulation state.
+  # # 
+  # def delta( place_ids=nil, except: [], transitions: nil, **options )
+  #   Δt = options.must_have :delta_time, syn!: :Δt
+  #   pp = simulation.pp( place_ids )
+  #   tt = transitions.nil? ? simulation.tt : transitions
+  #   simulation.delta( place_id, except: except, transitions: transitions )
+  # end
 end # module YPetri::Agent::SimulationRelated

data/lib/y_petri/dsl.rb

@@ -58,10 +58,17 @@ module YPetri
            :print_recording,
            :plot,
            :plot_selected,
+           :plot_marking,
            :plot_state,
            :plot_flux,
            :plot_firing,
            :plot_gradient,
            :plot_delta,
+           :_marking,
+           :_state,
+           :_flux,
+           :_firing,
+           :_gradient,
+           :_delta,
            to: :y_petri_agent
 end

data/lib/y_petri/net/state/features.rb

@@ -156,44 +156,45 @@ class YPetri::Net::State::Features < Array
 
   alias new_record load
 
-  # Extracts the features from a given target
+  # Extracts the features from a given target, returning a +Record+ instance.
   # 
   def extract_from target, **nn
     values = map { |feat| feat.extract_from( target, **nn ) }
     new_record( values )
   end
 
-  # Constructs a new record from these features.
+  # Constructs a new +Record+ instance from the supplied values array. The
+  # values in the array must correspond to the receiver feature set.
   # 
   def new_record values
     Record().load values
   end
 
-  # Constructs a new dataset from these features.
+  # Constructs a new dataset based on the receiver feature set.
   # 
   def new_dataset *args, &blk
     DataSet().new *args, &blk
   end
 
-  # Feature summation -- of feature class.
+  # Summation of feature sets.
   # 
   def + other
     self.class.new( super )
   end
 
-  # Feature summation -- of feature class.
+  # Subtraction of feature sets.
   # 
   def - other
     self.class.new( super )
   end
 
-  # Feature summation -- of feature class.
+  # Multiplication (like in arrays).
   # 
   def * other
     self.class.new( super )
   end
 
-  # Feature labels.
+  # Labels of the features of the receiver feature set.
   # 
   def labels
     map &:label

data/lib/y_petri/net/state.rb

@@ -8,7 +8,7 @@ class YPetri::Net::State < Array
 
   class << self
     # Customization of the parametrize method for the State class: Its
-    # dependents Feature and Features (ie. feature set) are also parametrized.
+    # dependents Feature and Features (feature set class) are also parametrized.
     # 
     def parametrize net: ( fail ArgumentError, "No owning net!" )
       Class.new( self ).tap do |ç|

data/lib/y_petri/place/guard.rb

@@ -3,6 +3,8 @@
 # Marking guard of a place.
 # 
 class YPetri::Place::Guard
+  # Error message template.
+  # 
   ERRMSG = -> m, of, assert do
     "Marking #{m.insp}" +
       if of then " of #{of.name || of}" else '' end +
@@ -11,16 +13,24 @@ class YPetri::Place::Guard
 
   attr_reader :place, :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].
+  # Expects a guard assetion in natural language, and a guard block. Guard block
+  # is a unary block that validates marking. A validation fails when:
+  #
+  # 1. The block returns _false_.
+  # 2. The block raises +YPetri::GuardError+.
+  #
+  # In all other cases, including when the block returns _nil_ (beware!),
+  # the marking is considered valid. Inside the block, +#fail+ keyword is
+  # redefined, so that it can (and must) be called without arguments, and it
+  # raises an appropriately worded +GuardError+. (Other exceptions can still be
+  # raised using +#raise+ keyword.) Practical example:
+  # 
+  #   YPetri::Place::Guard.new "should be a number" do |m|
+  #     fail unless m.is_a? Numeric
+  #   end
+  #
+  # Then <code>guard! :foobar</code> raises +GuardError+ with a message "Marking
+  # foobar:Symbol should be a number!"
   # 
   def initialize( assertion_NL_string, place: nil, &block )
     @place, @assertion, @block = place, assertion_NL_string, block
@@ -30,8 +40,7 @@ class YPetri::Place::Guard
     end
   end
 
-  # Validates a supplied marking value against the guard block. Raises
-  # +YPetri::GuardError+ if the guard fails, otherwise returns _true_.
+  # Validates a marking value. Raises +YPetri::GuardError+ upon failure.
   # 
   def validate( marking )
     λ = __fail__( marking, assertion )
@@ -43,7 +52,7 @@ class YPetri::Place::Guard
 
   # Constructs the fail closure.
   # 
-  def __fail__ marking, assertion
+  def __fail__ marking, assertionq
     pl = place
     -> { fail YPetri::GuardError, ERRMSG.( marking, pl, assertion ) }
   end

data/lib/y_petri/place/guarded.rb

@@ -1,60 +1,49 @@
 # encoding: utf-8
 
-# A mixin to make a place support guards.
+# Support of places' marking guards.
 # 
 module YPetri::Place::Guarded
   # 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:
+  # block is a unary block that validates marking. A validation fails when:
   #
   # 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:
+  # In all other cases, including when the block returns _nil_ (beware!),
+  # the marking is considered valid! Inside the block, +#fail+ keyword is
+  # redefined so that it can (and must) be called without arguments, and it
+  # raises an appropriately worded +GuardError+. (Other exceptions can still
+  # be raised using +#raise+ keyword.) Practical example:
   #
   #   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.
+  # Then <code>guard! :foobar</code> raises +GuardError+ with a message "Marking
+  # foobar:Symbol should be a number!"
   #
   # 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).
+  # given to it, it acts as an alias of +#common_guard_closure+ method.
   # 
   def guard *args, &block
     if block then
       @guards << YPetri::Place::Guard.new( *args, place: self, &block )
     elsif args.size == 1 then
-      federated_guard_closure.( args[0] )
+      common_guard_closure.( args[0] )
     elsif args.empty? then
-      federated_guard_closure
+      common_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.
+  # Returns a closure combining all the guards defined for the place so far,
+  # which passes if, and only if, all the included guards pass. The common
+  # closure, if it passes, returns the tested marking value.
   # 
-  def federated_guard_closure
+  def common_guard_closure
     place_name, lineup = name.to_s, guards.dup
-    -> m { lineup.each { |g| g.validate( m ) }; return m }
+    -> marking { lineup.each { |g| g.validate marking }; marking }
   end
 
-  # Applies guards on the marking currently owned by the place.
+  # Applies the guards defined for the place on the current marking (contents
+  # of +@marking+ instance variable).
   # 
   def guard!
     guard.( marking )
@@ -62,21 +51,24 @@ module YPetri::Place::Guarded
 
   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.
+  # If no guards were specified by the user, this method can construct standard
+  # guards based on the data type of places' +marking+ and/or +default_marking+.
+  # (For most data types, default guards enfore type compliance. Numeric
+  # descendants, however, are considered interchangeable, except for Complex
+  # class.)
   # 
   def add_default_guards!( reference_marking )
     case reference_marking
-    when Complex then marking "should be Numeric" do |m| m.is_a? Numeric end
-    when Numeric then
+    when Complex then # 1 guard
+      marking "should be Numeric" do |m| m.is_a? Numeric end
+    when Numeric then # 3 guards
       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
+    when true, false then # 1 guard
+      marking "should be Boolean" do |m| m == !!m end
+    else # 1 guard
       reference_marking.class.tap do |klass|
         marking "should be a #{klass}" do |m| m.is_a? klass end
       end

data/lib/y_petri/place.rb

@@ -23,38 +23,30 @@ class YPetri::Place
   attr_reader :guards
   attr_accessor :default_marking
 
-  # Named parameters supplied upon place initialization may include:
-  # 
-  # * :marking
-  # * :default_marking
-  # * :quantum
-  # * :guard
-  # 
-  # Those familiar with Petri nets need no introduction into _marking_
-  # attribute of a Petri net place. However, _quantum_ is a relatively uncommon
-  # concept in the context of Petri nets. +YPetri+ introduces quantum as a
-  # replacement for the hybrid-ness of Hybrid Functional Petri Nets (HFPNs).
-  # Formally, +YPetri+ is a discrete functional Petri net (FPN). The quantum
-  # is a numeric representation of a token: The smallest number by which the
-  # numeric representation of the place's marking can change. This is intended
-  # to enable smooth transition between continuous and stochastic simulation
-  # depending on pre-defined statistical settings.
-  #
-  # The :guard named argument and optional block specification allows to specify
-  # one marking guard already upon place initialization. This is done by putting
-  # the NL assertion string of the guard  under the :guard named argument, and
-  # supplying the guard block to the constructor. More guards can be defined
-  # later for the place using its +#guard+ method.
+  # Arguments supplied upon place initialization may include:
+  # 
+  # * +:marking+
+  # * +:default_marking+
+  # * +:quantum+
+  # * +:guard+
+  # 
+  # +Marking+ is a standard attribute of a Petri net place, +default_marking+
+  # is marking upon calling the reset method. Default marking may also be used
+  # as the initial value in the simulations involving the place in question.
+  # +Quantum+ attribute is not in use presently. In the future, it will be used
+  # to decide when to switch between continuous and discrete stochastic modeling
+  # of a place value. +Guard+ means a restriction of the place marking. (For
+  # example, the place could only admit non-negative numbers, or numbers smaller
+  # than 1, or odd numbers etc.) Named argument :guard along with a block
+  # supplied to the constructor allow one to specify a single marking guard
+  # upon place initialization by putting an NL assertion (a string) under
+  # +:guard+ argument, along with a block expressing the same meaning in code.
+  # More guards, if necessary, can be specified later using +Place#guard+ method.
   # 
   # If no guard block is supplied, default guards are constructed based on the
-  # type of the marking or default marking supplied upon initialization. For
-  # numeric marking except complex numbers, the default type guard allows all
-  # +Numeric+ types except complex numbers, and the default value guard prohibits
-  # negative values. For all other classes, there is just one guard enforcing
-  # the class compliance of the marking.
-  #
-  # To construct a place with no guards whatsoever, set :guard named argument
-  # to _false_.
+  # data type of the +:marking+ or +:default_marking+ argument. If it is wished
+  # that the place has no guards whatsoever, +:guard+ argumend should be set to
+  # _false_.
   # 
   def initialize quantum: 1,
                  default_marking: nil,
@@ -64,32 +56,31 @@ class YPetri::Place
     @upstream_arcs, @downstream_arcs, @guards = [], [], [] # init to empty
     @quantum, @default_marking = quantum, default_marking
     self.marking = marking || default_marking
-
-    # Check in :guard named argument and &block.
+    # Check in :guard value and the corresponding &block.
     if guard.ℓ? then # guard NL assertion not given, use block or default guards
       block ? guard( &block ) : add_default_guards!( @marking )
     elsif guard then # guard NL assertion given
       fail ArgumentError, "No guard block given!" unless block
       guard( guard, &block )
     else
-      fail ArgumentError, "Block given, but :guard set to falsey!" if block
+      fail ArgumentError, "Block given, but :guard argument is falsey!" if block
     end
   end
 
-  # Getter of +@marking+ attribute.
+  # Getter of the place's +@marking+ attribute.
   # 
   def m
     @marking
   end
   alias value m
 
-  # This method, which acts as a simple getter of +@marking+ attribute if no
-  # block is supplied to it, is overloaded to act as +#guard+ method frontend
-  # if a guard block is supplied. The reason is because this
+  # Used without arguments, it is a getter of the place's +@marking+ attribute,
+  # just like the +Place#m+ method. However, if a string and a block is supplied
+  # to it, it acts as an alias of the +Place#guard+ method. This is because this:
   #
   #   marking "should be a number" do |m| fail unless m.is_a? Numeric end
   # 
-  # reads better than
+  # reads better than this:
   # 
   #   guard "should be a number" do |m| fail unless m.is_a? Numeric end
   #
@@ -119,32 +110,33 @@ class YPetri::Place
     self.marking = marking
   end
 
-  # Adds tokens to the place.
+  # Adds tokens to the place's +@marking+ instance variable.
   # 
   def add( amount )
     @marking = guard.( @marking + amount )
   end
 
-  # Subtracts tokens from the place.
+  # Subtracts tokens from the place's +@marking+ instance variable.
   # 
   def subtract( amount )
     @marking = guard.( @marking - amount )
   end
 
-  # Resets place marking back to its default marking.
+  # Resets the place's marking back to its default value (+@default_marking
+  # instance variable).
   # 
   def reset_marking
     @marking = guard.( @default_marking )
   end
 
-  # Produces the inspect string of the place.
+  # Builds an inspect string of the place.
   # 
   def inspect
     n, m, d, q = instance_description_strings
     "#<Place: #{ ( [n, m, d, q].compact ).join ', ' }>"
   end
 
-  # Returns a string briefly describing the place.
+  # Returns a string representing the place.
   # 
   def to_s
     n, m = name, marking

data/lib/y_petri/simulation/marking_vector.rb

@@ -163,5 +163,12 @@ class YPetri::Simulation
       indices_of_free_places = annotation.free.map { |p| annotation.index p }
       increment_at_indices_closure( indices: indices_of_free_places )
     end
+
+    # Pretty-prints the marking vector.
+    # 
+    def pretty_print
+      to_h.pretty_print_numeric_values
+    end
+    alias pp pretty_print
   end
 end

data/lib/y_petri/version.rb

@@ -1,4 +1,4 @@
 module YPetri
-  VERSION = "2.2.2"
+  VERSION = "2.2.3"
   DEBUG = false
 end

data/test/acceptance/basic_usage_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/acceptance/simulation_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/acceptance/simulation_with_physical_units_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/acceptance/token_game_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
-# -*- coding: utf-8 -*-
+# encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/acceptance/visualization_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/acceptance_tests.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-gem 'minitest', '=4.7.4'
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/agent_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/net_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/place_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'
@@ -61,7 +60,7 @@ describe YPetri::Place do
     -> { g2.validate Complex( 1, 1 ) }.must_raise YPetri::GuardError
     p.marking "must be in 0..10" do |m| fail unless ( 0..10 ) === m end
     p.guards.size.must_equal 4
-    g = p.federated_guard_closure
+    g = p.common_guard_closure
     -> { g.( 11.1 ) }.must_raise YPetri::GuardError
     begin; p.marking = -1.11; rescue YPetri::GuardError => err
       err.message.must_equal 'Marking -1.11:Float of P1 should not be negative!'

data/test/simulation_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/transition_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require 'y_support/typing'
 

data/test/world_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri'     # tested component itself
 # require 'y_petri'

data/test/y_petri_test.rb

@@ -1,7 +1,6 @@
 #! /usr/bin/ruby
 # encoding: utf-8
 
-# gem 'minitest', '=4.7.4' # try uncommenting this line if problems appear
 require 'minitest/autorun'
 require_relative '../lib/y_petri' # tested component itself
 # require 'y_petri'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y_petri
 version: !ruby/object:Gem::Version
-  version: 2.2.2
+  version: 2.2.3
 platform: ruby
 authors:
 - boris
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-18 00:00:00.000000000 Z
+date: 2013-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: y_support