y_petri 2.0.3 → 2.0.7

data/lib/y_petri/place.rb

@@ -1,87 +1,103 @@
 # -*- coding: utf-8 -*-
-# This class represents Petri net places.
+
+require_relative 'dependency_injection'
+require_relative 'place/guard'
+require_relative 'place/arcs'
+
+# Represents a Petri net place.
 # 
 class YPetri::Place
-  USE_QUANTUM = false
   include NameMagic
+  include YPetri::DependencyInjection
 
   attr_reader :quantum
+  attr_reader :guards
   attr_accessor :default_marking
-  attr_accessor :marking           # instance-attached marking
-  alias :value :marking
-  alias :m :marking
-
-  # Alias for #marking=
-  # 
-  def value=( marking ); self.marking = marking end
-
-  # Alias for #marking=
-  # 
-  def m=( marking ); self.marking = marking end
-    
-  # Transitions that can directly add/remove tokens from this place.
-  # It is aliased as #upstream_transitions and #ϝ. (ϝ (Greek digamma) looks
-  # like "function", which we know from spreadsheet software: A collection
-  # of transitions directly affecting marking of this place.)
-  # 
-  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
+  attr_writer :marking
 
   # Named parameters supplied upon place initialization may include:
   # 
-  # * :marking (alias :m)
-  # * :default_marking (alias :dflt_m or :m!)
-  # * :quantum (alias :q)
-  # 
-  # While 'marking' is a standard Petri net concept, and default marking
-  # is self-explanatory, place quantum is the concept by which YPetri
-  # reconciles with letter H in the abbreviation HFPN. YPetri places are
-  # always considered discrete, and it is true insomuch, as their marking
-  # is represented by a finite-digit number. The place quantum feature is
-  # not supported yet, but in future, it should enable smooth transition
-  # between continuous and stochastic modes of simulation.
-  # 
-  def initialize *aa; oo = aa.extract_options!
-    # set domain and codomain of the place empty
-    @upstream_arcs = []
-    @downstream_arcs = []
-    @quantum = oo.may_have( :quantum, syn!: :q ) || 1
-    @default_marking = oo.may_have( :default_marking, syn!: [ :dflt_m, :m! ] )
-    @marking = oo.may_have( :marking, syn!: :m ) || @default_marking
+  # * :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.
+  # 
+  # 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_.
+  # 
+  def initialize quantum: 1,
+                 default_marking: nil,
+                 marking: nil,
+                 guard: L!,
+                 &block
+    @upstream_arcs, @downstream_arcs, @guards = [], [], [] # init to empty
+    @quantum, @default_marking = quantum, default_marking
+    @marking = marking || default_marking
+
+    # Check in :guard named argument and &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
+    end
+  end
+
+  # Getter of +@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
+  #
+  #   marking "should be a number" do |m| fail unless m.is_a? Numeric end
+  # 
+  # reads better than
+  # 
+  #   guard "should be a number" do |m| fail unless m.is_a? Numeric end
+  #
+  # {See #guard method}[rdoc-ref:YPetri::guard] for more information.
+  # 
+  def marking *args, &block
+    return @marking if args.empty?
+    fail ArgumentError, "Too many arguments!" if args.size > 1
+    guard args[0], &block
   end
 
-  # Returns an array of all the transitions connected to the place.
-  # 
-  def arcs
-    upstream_arcs | downstream_arcs
-  end
-
-  # Returns the union of domains of the transitions associated
-  # with the upstream arcs of this place.
+  # Alias for #marking=
   # 
-  def precedents
-    upstream_transitions
-      .map( &:upstream_places )
-      .reduce( [], :| )
-  end
-  alias :upstream_places :precedents
+  def value=( marking ); self.marking = marking end
 
-  # Returns the union of codomains of the transitions associated
-  # with the downstream arcs originating from this place.
+  # Alias for #marking=
   # 
-  def dependents
-    downstream_transitions
-      .map( &:downstream_places )
-      .reduce( [], :| )
-  end
-  alias :downstream_places :dependents
+  def m=( marking ); self.marking = marking end
 
   # Adds tokens to the place.
   # 
@@ -91,7 +107,7 @@ class YPetri::Place
 
   # Subtracts tokens from the place.
   # 
-  def subtract( amount_of_tokens)
+  def subtract( amount_of_tokens )
     @marking -= amount_of_tokens
   end
 
@@ -101,87 +117,28 @@ class YPetri::Place
     @marking = @default_marking
   end
 
-  # Firing of upstream transitions regardless of cocking. (To #fire
-  # transitions, they have to be cocked with #cock method; the firing
-  # methods with exclamation marks disregard cocking.)
-  # 
-  def fire_upstream!
-    @upstream_arcs.each &:fire!
-  end
-  alias :fire! :fire_upstream!
-
-  # Fires whole upstream portion of the net.
-  # 
-  def fire_upstream_recursively
-    # LATER: so far, implemented without concerns about infinite loops
-    # LATER: This as a global hash { place => fire_list }
-    @upstream_arcs.each &:fire_upstream_recursively
-  end
-  alias :fire_upstream! :fire_upstream_recursively
-
-  # Firing of downstream transitions regardless of cocking. (To #fire
-  # transitions, they have to be cocked with #cock method; the firing
-  # methods with exclamation marks disregard cocking.)
-  # 
-  def fire_downstream!
-    @downstream_arcs.each &:fire!
-  end
-
-  # Fires whole downstream portion of the net.
-  # 
-  def fire_downstream_recursively
-    # LATER: so far, implemented withoud concerns about infinite loops
-    # LATER: This as a global hash { place => fire_list }
-    @downstream_arcs.each &:fire_downstream_recursively
-  end
-  alias :fire_downstream! :fire_downstream_recursively
-
   # Produces the inspect string of the place.
   # 
   def inspect
     n, m, d, q = instance_description_strings
-    "#<Place: #{ ( USE_QUANTUM ? [n, m, d, q] : [n, m, d] ).join ', ' } >"
+    "#<Place: #{ ( [n, m, d, q].compact ).join ', ' }>"
   end
 
   # Returns a string briefly describing the place.
   # 
   def to_s
     n, m = name, marking
-    "#{n.nil? ? 'Place' : n}[ #{m.nil? ? 'nil' : m} ]"
+    "#{n.nil? ? 'Place' : n}[#{m.nil? ? 'nil' : m}]"
   end
 
   private
 
-  # Makes the place notice an upstream transition;
-  # to be called from the connecting transitions.
-  def register_upstream_transition( transition )
-    @upstream_arcs << transition
-  end
-
-  # Makes the place notice a downstream transition;
-  # to be called from the connecting transitions.
-  def register_downstream_transition( transition )
-    @downstream_arcs << transition
-  end
-
   def instance_description_strings
     m, n, d, q = marking, name, default_marking, quantum
     nς = "name: #{n.nil? ? '∅' : n}"
     mς = "marking: #{m.nil? ? 'nil' : m}"
     dς = "default_marking: #{d.nil? ? '∅' : d}"
-    qς = "quantum: #{q.nil? ? '∅' : q}"
+    qς = q == 1 ? nil : "quantum: #{q.nil? ? '∅' : q}"
     return nς, mς, dς, qς
   end
-
-  # Place, Transition, Net class
-  # 
-  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::Place