y_petri 2.3.10 → 2.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3764e025431d0669a31797b1d5bbce55a444e3d6
-  data.tar.gz: 6bf64d8fa786b8366219e7e2949cd581493cd75a
+  metadata.gz: 213efc795950a5d200a6b5c10fe3150dddf4940b
+  data.tar.gz: 6c1a54e4526c7f19ea63dc7faad780526e2d3ee2
 SHA512:
-  metadata.gz: 9c7294bf61692d9514ffe266dea39c931c25587cfc5ee14a1737010d21f88653a3ef8f14b826478b255e90c8623e7b33f8e81e02eeaac2e9aa986108ec32eec3
-  data.tar.gz: 73072db1890baeec7ea5fd6f22f80c95a6a581c69179062c6550b76a7ccf382b9ef22e4b502d0e1d957af4473e9f33df8883069a58b7f6a8bb41c87ccee52bee
+  metadata.gz: 60800f142748c833d2298583393f3790532d56bf294779d02a6e6b6991409bdc12b584bf64ec286868012d3b4d25e0a18cc8a5ac170359ab4c00ca7c703fdf52
+  data.tar.gz: aacfcbc2bbba5c262c5e2cab747a4fe093d047b02a65781709eec758a30b5bc9222dcd0a6874afdf1041d1a8d3f9d9e143fe0bd80f26361df6f5cd4b64e9182e

data/lib/y_petri/agent/petri_net_aspect.rb

@@ -3,11 +3,11 @@
 # Petri net aspect of +YPetri::Agent+.
 # 
 module YPetri::Agent::PetriNetAspect
-  # Net selection class.
+  # A class representing a selection of nets.
   # 
   NetSelection = Class.new YPetri::Agent::Selection
 
-  # Net point
+  # Net point.
   # 
   attr_reader :net_point
 
@@ -15,6 +15,8 @@ module YPetri::Agent::PetriNetAspect
   # 
   attr_reader :net_selection
 
+  # Standard initialization method. Takes no arguments.
+  # 
   def initialize
     net_point_reset
     @net_selection = NetSelection.new
@@ -27,37 +29,37 @@ module YPetri::Agent::PetriNetAspect
            :nets, :places, :transitions,
            to: :world
 
-  # Place name.
+  # Returns the name of a place identified by the argument.
   # 
   def pl( place_id )
     place( place_id ).name
   end
 
-  # Transition name.
+  # Returns the name of a transition identified by the argument.
   # 
   def tr( transition_id )
     transition( transition_id ).name
   end
 
-  # Place names.
+  # Names of the places.
   # 
   def pn
     places.names
   end
 
-  # Transition names.
+  # Names of the transitions.
   # 
   def tn
     transitions.names
   end
 
-  # Net names.
+  # Names of the nets.
   # 
   def nn
     nets.names
   end
 
-  # Place constructor: Creates a new place in the current world.
+  # Constructor of a place: Creates a new place in the current world.
   # 
   def Place( *ordered_args, **named_args, &block )
     fail ArgumentError, "If block is given, :guard named argument " +
@@ -68,24 +70,12 @@ module YPetri::Agent::PetriNetAspect
     world.Place.send( :new, *ordered_args, **named_args, &block )
   end
 
-  # Transition constructor: Creates a new transition in the current world.
+  # Constructor of a transition: Creates a new transition in the current world.
   # 
   def Transition( *ordered, **named, &block )
     world.Transition.send( :new, *ordered, **named, &block )
   end
 
-  # Place constructor: Creates a new place in the current world.
-  # 
-  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
-    world.Place.send( :new, *ordered_args, **named_args, &block )
-  end
-
-
   # Assignment transition constructor: Creates a new assignment transition in
   # the current world. Ordered arguments are collected as codomain. Domain key
   # (+:domain) is optional. Assignment closure must be supplied in a block.

data/lib/y_petri/agent.rb

@@ -6,6 +6,19 @@ require_relative 'agent/petri_net_aspect'
 require_relative 'agent/simulation_aspect'
 
 # A dumb agent that represents and helps the user.
+#
+# An instance of this class (an agent) helps the user to interact
+# with the world (YPetri::World instance) and the objects in it
+# (Petri net places, transitions, nets etc.). In particular, this
+# (YPetri::Agent) class is a convenient place to store various
+# "shortcuts" meant to reduce the amount of typing the user has to
+# do in order to construct and manipulate the world and its objects
+# (such as "pl" instead of "place", "tr" instead of "transition" etc.)
+# It would not be a good practice to encumber the classes where these
+# methods are implemented with these semi-idiosyncratic shortcuts. This
+# way, the implementation of the methods stays the concern of the mother
+# classes, and Agent class is responsible for improving the ergonomy
+# of their invocation.
 # 
 class YPetri::Agent
   ★ PetriNetAspect                  # ★ means include

data/lib/y_petri/core/timed/runge_kutta.rb

@@ -5,10 +5,57 @@
 module YPetri::Core::Timed::RungeKutta
   def delta Δt
     fail NotImplementedError, "RungeKutta not implemented yet!"
-    # Of course, the following line is from Euler method.
-    # The formula of Runge-Kutta is more complicated.
-    # 
-    gradient * Δt
+
+    # f = simulation.method :gradient, parameter: :state
+    f = lambda { |mv| # mv is the marking vector of the free places
+          result = "make hash from free places of the simulation to zeros"
+          nonstoichiometric_transitions.each { |t|
+            places = t.codomain.free
+            inputs = mv.select( t.domain ) # this doesn't work this way
+            f = t.function
+            output = f.call( *inputs )
+            places.each { |p|
+              result[p] += output[p] # again, this doesn't work this way
+            }
+          }
+          stoichiometric_transitions.each { |t|
+            places = t.codomain.free
+            inputs = mv.select( t.domain ) # this doesn't work this way
+            f = t.function
+            output = f.call( *inputs ) * stoichiometry_vector # this doesn't work this way
+            places.each { |p|
+              result[p] += output[p]
+            }
+          }
+          # so you see how many selections one has to do if one doesn't
+          # construct a specific gadget for the operation, that's why
+          # I made those closures, unfortunately I didn't think about
+          # higher-order methods yet when making them, and maybe the core
+          # should own them instead of the simulation object
+          
+          return result.to_vector # this doesn't work this way
+    }
+
+    # this is supposed to be Runge-Kutta 4th order
+    # but how do I get those in-between f values...
+    
+    y = simulation.state # this must return a vector compatible with the one
+                         # returned by f
+    
+    k1 = f( y )
+    k2 = f( y + Δt / 2 * k1 )
+    k3 = f( y + Δt / 2 * k2 )
+    k4 = f( y + Δt * k3 )
+
+    rslt = Δt / 6 * ( k1 + 2 * k2 + 2 * k3 + k4 )
+    return rslt.to_the_kind_of_vector_that_delta_method_should_return
+    # which is the vector corresponding to the ordered list of
+    # free places of this simulation (here, every core either has a
+    # simulation assigned, or is parametrized with simulation, which
+    # might be dumb anyway, since core, by its name, should not be that
+    # heavily coupled with a simulation, but actually, atm, each core
+    # belongs to a specific simulation, so it's OK if it's parametrized
+    # with it for now
   end
   alias Δ delta
 end # YPetri::Core::Timed::RungeKutta

data/lib/y_petri/core.rb

@@ -3,6 +3,29 @@
 # This class represents a simulator.
 # 
 class YPetri::Core
+  # TODO: currently, Core and Simulation classes are tightly coupled.
+  # each simulation has just one core, and that core looks directly
+  # into the simulation's state. What needs to be done is a simulation
+  # that at least hints the process of core recruitment for the requested
+  # operation (be it step, step backwards, run forward aso.) and then
+  # imprints the core with its current marking vector, tells the core
+  # what to do, and then reads the result and updates its marking vector
+  # accordingly. There are multiple possibilities, such as constructing
+  # a new core for each operation, or keeping the same core for all the
+  # operations using a given method. A simulation method (like euler,
+  # gillespie, or runge-kutta) should be associated not so much with
+  # the simulation object, as it should be associated with the core
+  # object. A core object should be more or less one-trick pony. While
+  # later, it is possible for a simulation to have broader simulation
+  # strategy, or "method" in the broader sense. But simulation should
+  # also avoid doing too much, because above it, there is Agent class,
+  # and this class can be taught to do the more complicated things
+  # such as parameter optimization or computation of control coefficients
+  # and such. It is also possible to construct more specialized agent-like
+  # classes for these more specialized tasks, since the main purpose
+  # of Agent class, as I saw it, was to represent the user (represent
+  # what the user means), to provide the user interface.
+  
   require_relative 'core/timed'
   require_relative 'core/timeless'
   require_relative 'core/guarded'

data/lib/y_petri/place.rb

@@ -47,20 +47,20 @@ class YPetri::Place
   # +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
-  # 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_.
+  # +Quantum+ attribute is not in use presently. In the future, it might be used
+  # in deciding when to switch between continuous and discrete stochastic
+  # representation of the marking. +Guard+ is a restriction to the place's
+  # marking. (For example, the place could only admit non-negative numbers,
+  # or numbers smaller than 1, or odd numbers etc.) Any number of guards can
+  # be specified for a constructed place via +Place#guard+ method. For the cases
+  # when a place has only one guard, it is, as a syntactic sugar, possible to
+  # introduce exactly one guard already upon place initialization by supplying
+  # to this constructor, in addition to other parameters, a string expressing
+  # the guard as +:guard+ and a block expressing the same guard in code. If no
+  # guard block is supplied to this constructor, default guards are constructed
+  # based on the data type of the +:marking+ or +:default_marking+ argument. If
+  # it is wished that the place has no guards whatsoever, +:guard+ should be set
+  # to _false_.
   # 
   def initialize guard: L!, **named_args, &block
     @upstream_arcs, @downstream_arcs, @guards = [], [], [] # init to empty

data/lib/y_petri/simulation/dependency.rb

@@ -38,21 +38,21 @@ class YPetri::Simulation
       end
     end
     
-    # Necessary to overcoming the protected character of the listed methods.
+    # Necessary to overcome the protected character of the listed methods.
     # 
     [ :node,
       :place,
       :transition
     ].each { |sym| define_method sym do |e| simulation.send sym, e end }
 
-    # Necessary to overcoming the protected character of the listed methods.
+    # Necessary to overcome the protected character of the listed methods.
     # 
     [ :Nodes,
       :Places,
       :Transitions
     ].each { |sym| define_method sym do |array| simulation.send sym, array end }
 
-    # Necessary to overcoming the protected character of the listed methods.
+    # Necessary to overcome the protected character of the listed methods.
     # 
     [ :nodes,
       :places,

data/lib/y_petri/simulation/nodes.rb

@@ -24,7 +24,7 @@ class YPetri::Simulation
     
     # Creates a subset of this collection (of the same class).
     # 
-    def subset nodes=nil, &block
+    def subset nodes=nil, &block # TODO: Rename to subarray
       if block_given? then
         fail ArgumentError, "If block given, arguments not allowed!" unless
           nodes.nil?

data/lib/y_petri/version.rb

@@ -1,4 +1,4 @@
 module YPetri
-  VERSION = "2.3.10"
+  VERSION = "2.3.11"
   DEBUG = false
 end

data/lib/y_petri/world.rb

@@ -4,10 +4,11 @@ require_relative 'world/dependency'
 require_relative 'world/petri_net_aspect'
 require_relative 'world/simulation_aspect'
 
-# As the name suggests, represents the world. Holds places, transitions, nets
-# and other assets needed to set up and simulate Petri nets (settings, clamps,
-# initial markings etc.). Provides basic methods to do what is necessary. More
-# ergonomic and DSL-like methods are up to the YPetri::Agent.
+# Represents YPetri workspace, but "world" is shorter. Its instance holds
+# places, transitions, nets and other assets needed to perform the tasks
+# of system specification and simulation (simulation settings, place clamps,
+# initial markings etc.). Provides basic methods to do just what is necessary.
+# More ergonomic and DSL-like methods may be defined in YPetri::Agent.
 # 
 class YPetri::World
   ★ NameMagic                        # ★ means include
@@ -15,14 +16,17 @@ class YPetri::World
   ★ SimulationAspect
 
   def initialize
-    # Parametrize the Place / Transition / Net classes.
+    # Set up parametrized subclasses of Place, Transition, Net.
     param_class!( { Place: YPetri::Place,
                     Transition: YPetri::Transition,
                     Net: YPetri::Net },
                   with: { world: self } )
-    # Make them their own namespaces.
+    # Invoke #namespace! method (from YSupport's NameMagic) on each of them.
+    # This causes each of them to do bookkeeping of their instances. This is
+    # because there is little point in keeping the objects from separate
+    # worlds (ie. workspaces) on the same list.
     [ Place(), Transition(), Net() ].each &:namespace!
-    # And proceeed as usual.
+    # And proceed with initializations (if any) higher in the lookup chain.
     super
   end
 end

data/lib/y_petri.rb

@@ -35,33 +35,37 @@ require_relative 'y_petri/core'
 require_relative 'y_petri/agent'
 require_relative 'y_petri/dsl'
 
-# YPetri is a domain model and a domain-specific language (DSL) for modelling
-# dynamical systems. (Industrial modellers use the term DSML – domain specific
-# modelling language.) YPetri caters solely to the two main concerns of
-# modelling: model specification and simulation, excelling in the first one.
+# YPetri is a domain-specific language (DSL) for modelling dynamical systems. It
+# caters solely to the two main concerns of modelling: model specification and
+# simulation.
 #
-# YPetri model specification is based on a Petri net paradigm. A Petri net (PN)
-# is a bipartite graph with two kinds of nodes: places and transitions. Places
-# are visualised as circles, transitions as rectangles. During PN execution
-# (simulation), transitions act upon places and change their marking by adding
-# / removing tokens as dictated by the prescription of their operation. For
-# classical PNs, transition action is a discrete stoichiometric addition /
-# subtraction of tokens to / from the connected places. However, many extended
-# PN types have been defined, where the transition action is determined by a
-# mathematical function attached to the transition. Such transitions are called
-# functional, and almost all YPetri transitions are of this type. Borrowing more
-# from the terminology of functions, YPetri defines keywords domain an codomain
-# for transitions in a way similar to the domain and codomain of functions.
+# Model specification in YPetri is based on a Petri net. Classical Petri net
+# (PN), originally described by Carl Adam Petri in 1962, is a bipartite graph
+# with two kinds of nodes: places (circles) and transitions (rectangles),
+# connected by arcs (lines). Places act as variables – each place holds exactly
+# one value ("marking"), a discrete number imagined as consisting of individual
+# units ("tokens"). The action of transitions ("firing") is also discrete. Each
+# time a transition fires, a fixed number of tokens is added/subtracted to the
+# connected places. It turns out that classical PNs are very useful in describing
+# things like industrial systems, production lines, and also basic chemical
+# systems with a number of molecules is connected by stoichiometric reactions.
+#
+# YPetri allows specification of not just classical PNs, but also of many
+# extended Petri net (XPN) types, which have been described since Petri's work.
+# This is achieved by making YPetri transitions functional (mathematical
+# functions in lambda notation can be attached to them), and allowing the
+# possibility of transitions being defined as either timed and timeless, and as
+# eithier nonstoichiometric and explicitly stoichiometric. Together, this makes 4
+# types of functional transitions available in YPetri, which can be used to
+# capture almost any type of XPN. In this way, YPetri can serve as a common
+# platform for data exchange and cooperation between different XPN formalisms,
+# without sacrificing the special qualities of XPNs described thus far.
+#
+# The basic simulation method is simple PN execution. In its course, transitions
+# fire, and thereby change the places' marking by adding/removing tokens as
+# dictated by their operating prescription. Other simulation methods become
+# available for more specific net types, such as timed nets.
 #
-# Many extended PN types have been defined. YPetri implements a universal PN
-# abstraction designed to subsume and integrate the dichotomies of the common
-# extended PN types. YPetri unifies discrete and stochastic modelling of timed
-# transitions at the level of model specification in line with the present day
-# unifying Petri net frameworks. YPetri also integrates other dichotomies: timed
-# / timeless and stoichiometric / nonstoichiometric. The idea is to save the
-# Ruby-based modeller the work of researching different PN types and provide a
-# single abstraction and the DSL to rule them all.
-# 
 module YPetri
   class << self
     def included( receiver )

data/test/core_test.rb

@@ -0,0 +1,26 @@
+#! /usr/bin/ruby
+# encoding: utf-8
+
+gem 'minitest'
+require 'minitest/autorun'
+require_relative '../lib/y_petri'     # tested component itself
+# require 'y_petri'
+# require 'sy'
+
+describe "use of timed and timeless core" do
+  before do
+    # set up a user of core, which will imitate some of the needs
+    # of the Simulation class, or be an actual instance of that class
+  end
+
+  it "should behave" do
+    # the core will be informed of the task required (bring the system
+    # whose specification is known to the core user mentioned above from
+    # some initial state to some next state by performing a requested
+    # something in a way requested by the user, where something can be
+    # eg. step forward, or run forward by a specified period of time or
+    # number of steps or until some other condition is fulfilled, or
+    # step backward, or even run backward, if the system allows such thing
+    # at all.
+  end
+end

data/test/y_petri_test.rb

@@ -11,6 +11,7 @@ require_relative '../lib/y_petri' # tested component itself
 require_relative 'place_test'
 require_relative 'transition_test'
 require_relative 'net_test'
+require_relative 'core_test'
 require_relative 'simulation_test'
 require_relative 'world_test'
 require_relative 'agent_test'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: y_petri
 version: !ruby/object:Gem::Version
-  version: 2.3.10
+  version: 2.3.11
 platform: ruby
 authors:
 - boris
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-08 00:00:00.000000000 Z
+date: 2015-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -248,6 +248,7 @@ files:
 - test/acceptance/visualization_test.rb
 - test/acceptance_tests.rb
 - test/agent_test.rb
+- test/core_test.rb
 - test/examples/demonstrator.rb
 - test/examples/demonstrator_2.rb
 - test/examples/demonstrator_4.rb
@@ -299,6 +300,7 @@ test_files:
 - test/acceptance/visualization_test.rb
 - test/acceptance_tests.rb
 - test/agent_test.rb
+- test/core_test.rb
 - test/examples/demonstrator.rb
 - test/examples/demonstrator_2.rb
 - test/examples/demonstrator_4.rb