y_petri 2.2.4 → 2.3.2

data/README.md

@@ -1,11 +1,14 @@
 # YPetri
 
-`YPetri` is a domain model and a simulator of _functional_ _Petri_ _nets_,
-a family of Petri nets, whose transitions have functions attached to them.
+`YPetri` is a domain model and a simulator of _YPetri_ nets, a specific kind of
+_Petri_ _nets_ unifying discrete/continous, deterministic/stochastic,
+timed/timeless and stoichiometric/nonstoichiometric dichotomies, thus enabling
+modelling and simulation of dynamic systems of any kind whatsoever.
 
 ## Usage
 
-`YPetri` provides a _domain_ _specific_ _language_ (DSL), that can be loaded by:
+`YPetri` provides a _domain_ _specific_ _modeling_ _language_ (DSML), that can
+be loaded by:
 ```ruby
   require 'y_petri'
   include YPetri

data/Rakefile

@@ -1,2 +1,2 @@
-#!/usr/bin/env rake
 require "bundler/gem_tasks"
+

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

@@ -1,8 +1,8 @@
 # encoding: utf-8
 
-# Public command interface of YPetri.
+# Petri net aspect of +YPetri::Agent+.
 # 
-module YPetri::Agent::PetriNetRelated
+module YPetri::Agent::PetriNetAspect
   # Net selection class.
   # 
   NetSelection = Class.new YPetri::Agent::Selection
@@ -21,9 +21,9 @@ module YPetri::Agent::PetriNetRelated
     super
   end
 
-  # Elements and selections:
+  # Nodes and selections:
   # 
-  delegate :place, :transition, :element,
+  delegate :place, :transition, :node,
            :nets, :places, :transitions,
            to: :world
 
@@ -74,17 +74,41 @@ module YPetri::Agent::PetriNetRelated
     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.
+  # 
+  def AT( *codomain, **nn, &block )
+    fail ArgumentError, "Assignment transition constructor requires a block " +
+      "defining the assignment function!" unless block
+    world.Transition.send( :new,
+                           codomain: codomain,
+                           assignment: block,
+                           **nn )
+  end
+
   # Timed transition constructor: Creates a new timed transition in the current
-  # world. Rate closure has to be supplied as a block.
+  # world. Rate can be supplied either as +:rate+ named argument, or as a block.
+  # If none is supplied, rate argument defaults to 1.
   # 
   def TT( *ordered, **named, &block )
     if named.has? :rate then
       fail ArgumentError, "Block must not be given if :rate named argument " +
         "is given!" if block
     else
-      fail ArgumentError, "Timed transition constructor requires either " +
-        "a :rate argument, or a block!" unless block
-      named.update rate: block
+      named.update rate: block || 1 # default rate is 1
     end
     world.Transition.send( :new, *ordered, **named )
   end
@@ -101,7 +125,7 @@ module YPetri::Agent::PetriNetRelated
       args.update domain: nn.delete( :domain ) if nn.has? :domain
     else
       fail ArgumentError, "There must not be any ordered arguments if " +
-        "named argument :domain is given!" unless domain.empty?
+        "named argument :domain is given!" if nn.has? :domain
       args.update domain: domain
     end
     args.update rate: nn.delete( :rate ) if nn.has? :rate, syn!: :rate_closure
@@ -148,4 +172,4 @@ module YPetri::Agent::PetriNetRelated
   def net_point= id
     net_point_reset id
   end
-end # module YPetri::Agent::PetriNetRelated
+end # module YPetri::Agent::PetriNetAspect

data/lib/y_petri/agent/{simulation_related.rb → simulation_aspect.rb}

@@ -1,9 +1,9 @@
 # encoding: utf-8
 
-# Agent instance methods related to simulation (initial marking collections,
-# clamp collections, initial marking collections, management of simulations...)
+# Simulation aspect of +YPetri::Agent+: initial marking collections, clamp
+# collections, initial marking collections, management of simulations...
 # 
-module YPetri::Agent::SimulationRelated
+module YPetri::Agent::SimulationAspect
   require_relative 'hash_key_pointer'
   require_relative 'selection'
 
@@ -118,9 +118,8 @@ module YPetri::Agent::SimulationRelated
     return nil
   end
 
-  # Returns the simulation identified by the argument, or one at simulation
-  # point, if no argument given. The simulation is identified in the same way
-  # as for #simulation_point_to method.
+  # Returns the simulation identified by the argument. If no argument is given,
+  # returns the simulation at point.
   # 
   def simulation *args
     return simulation_point.get if args.empty?
@@ -155,7 +154,7 @@ module YPetri::Agent::SimulationRelated
   end
   alias ssc simulation_settings_collection
 
-  # FIXME: This is going to be tested
+  # FIXME: This is not tested yet.
 
   def clamp clamp_hash
     clamp_hash.each_pair do |place, clamp|
@@ -265,75 +264,91 @@ module YPetri::Agent::SimulationRelated
   # Plot the recording reduced into the given feature set.
   # 
   def plot features
-    ff = simulation.net.state.features( features )
+    ff = simulation.net.State.Features( features )
     simulation.recording.reduce_features( ff ).plot
   end
 
   # Plot system state history.
   # 
-  def plot_marking( place_ids=nil, except: [],
+  def plot_marking( places=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 )
+    pp = simulation.pp( *places ) - simulation.Pp( except )
+    rec.Marking( pp ).plot( title: title, ylabel: ylabel, **options )
   end
   alias plot_state plot_marking
 
   # Plot flux history of TS transitions.
   # 
-  def plot_flux( transition_ids=nil, except: [],
+  def plot_flux( transitions=nil, except: [],
                  title: "Flux plot", ylabel: "Flux [µM.s⁻¹]",
                  **options )
     rec = simulation.recording
-    tt = transition_ids.nil? ? simulation.TS_tt : transition_ids
-    tt = simulation.TS_tt( tt )
-    tt -= simulation.tt( except )
-    rec.flux( tt ).plot( title: title, ylabel: ylabel, **options )
+    tt = simulation.TS_tt( *transitions ) - simulation.Tt( except )
+    rec.Flux( tt ).plot( title: title, ylabel: ylabel, **options )
   end
 
   # Plot firing history of tS transitions.
   # 
-  def plot_firing( transition_ids=nil, except: [],
+  def plot_firing( transitions=nil, except: [],
                    title: "Firing plot", ylabel: "Firing [µM]",
                    **options )
     rec = simulation.recording
-    tt = transition_ids.nil? ? simulation.tS_tt : transition_ids
-    tt = simulation.tS_tt( tt )
-    tt -= simulation.tt( except )
-    rec.firing( tt ).plot( title: title, ylabel: ylabel, **options )
+    tt = simulation.tS_tt( *transitions ) - simulation.Tt( except )
+    rec.Firing( tt ).plot( title: title, ylabel: ylabel, **options )
   end
 
   # Plot gradient history of selected places with respect to a set of T
   # transitions.
   # 
-  def plot_gradient( place_ids=nil, except: [], transitions: nil,
+  def plot_gradient( places=nil, except: [], transitions: nil,
                      title: "Gradient plot", ylabel: "Gradient [µM.s⁻¹]",
                      **options )
     rec = simulation.recording
-    pp = simulation.pp( place_ids ) - simulation.ee( place_ids )
-    tt = transitions.nil? ? simulation.T_tt : transitions
-    tt = simulation.T_tt( tt )
-    tt -= simulation.ee( except )
-    rec.gradient( pp, transitions: tt )
+    pp = simulation.pp( *places ) - simulation.Nn( except )
+    tt = simulation.T_tt( *transitions ) - simulation.Nn( except )
+    rec.Gradient( pp, transitions: tt )
       .plot( title: title, ylabel: ylabel, **options )
   end
 
   # Plot delta history of selected places with respect to a set of transitions.
   # 
-  def plot_delta( place_ids=nil, except: [], transitions: nil,
+  def plot_delta( places=nil, except: [], transitions: nil,
                   title: "Delta plot", ylabel: "Delta [µM]",
                   **options )
     options.may_have :delta_time, syn!: :Δt
     rec = simulation.recording
-    pp = simulation.pp( place_ids ) - simulation.ee( except )
-    tt = transitions.nil? ? simulation.tt : transitions
-    tt = simulation.tt( tt )
-    tt -= simulation.ee( except )
-    rec.delta( pp, transitions: tt, Δt: options[:delta_time] )
+    pp = simulation.pp( *places ) - simulation.Nn( except )
+    tt = simulation.tt( *transitions ) - simulation.Nn( except )
+    simulation.recording.Delta( pp, transitions: tt, Δt: options[:delta_time] )
       .plot( title: title, ylabel: ylabel, **options )
   end
 
+  # Save a file.
+  # 
+  def save_file f, txt
+    File.open( f, 'w' ) { |f| f.write "txt" }
+  end
+
+  # Load a file
+  # 
+  def load_file f
+    rr = []
+    CSV.parse( File.open( f ), headers: true ) { |row|
+      rr << row
+    }
+    r1 = rr.first.to_hash.with_keys { |k| eval k }.with_values { |v| eval v }
+    ff = world.net.State.Features( r1.keys[ 1..-1 ] )
+    dataset = ff.DataSet.new
+    rr.each { |row|
+      r = row.to_hash.with_keys { |k| eval k }.with_values { |v| eval v }
+      event = r.delete :event
+      dataset[ event ] = ff.r.values
+    }
+    return dataset
+  end
+
   # # Pretty print marking of the current simulation.
   # # 
   # def marking
@@ -367,4 +382,4 @@ module YPetri::Agent::SimulationRelated
   #   tt = transitions.nil? ? simulation.tt : transitions
   #   simulation.delta( place_id, except: except, transitions: transitions )
   # end
-end # module YPetri::Agent::SimulationRelated
+end # module YPetri::Agent::SimulationAspect

data/lib/y_petri/agent.rb

@@ -2,14 +2,14 @@
 
 require_relative 'agent/selection'
 require_relative 'agent/hash_key_pointer'
-require_relative 'agent/petri_net_related'
-require_relative 'agent/simulation_related'
+require_relative 'agent/petri_net_aspect'
+require_relative 'agent/simulation_aspect'
 
-# Public command interface of YPetri.
+# A dumb agent that represents and helps the user.
 # 
 class YPetri::Agent
-  ★ PetriNetRelated                  # ★ means include
-  ★ SimulationRelated
+  ★ PetriNetAspect                  # ★ means include
+  ★ SimulationAspect
 
   attr_reader :world
 

data/lib/y_petri/core/guarded.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+# Guarded simulation mixin – not working yet.
+# 
+module YPetri::Core::Guarded
+  # Guarded version of the method.
+  # 
+  def increment_marking_vector( delta )
+    try "to update marking" do
+      super( note( "Δ state if tS transitions fire once",
+                   is: Δ_if_tS_fire_once ) +
+             note( "Δ state if tsa transitions fire once",
+                   is: Δ_if_tsa_fire_once ) )
+    end
+  end
+  
+  # Guarded version of the method.
+  # 
+  def A_all_fire!
+    try "to fire the assignment transitions" do
+      super
+    end
+  end
+end # module YPetri::Core::Guarded

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

@@ -1,15 +1,11 @@
 # encoding: utf-8
 
-# Euler method.
+# Euler method. Assumes that only T transitions are in the net.
 # 
 module YPetri::Core::Timed::Euler
-  # Name of this method.
-  # 
-  def simulation_method
-    :euler
-  end
-
-  # Computes Δ for the period of Δt.
+  # Computes Δ for the period of Δt. Since this method assumes that only
+  # timed transitions are in the net, delta state is computed simply bu
+  # multiplying the gradient by Δt.
   # 
   def delta Δt
     gradient * Δt

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

@@ -2,18 +2,17 @@
 
 # Plain Gillespie algorithm.
 #
-# The characteristic of the Gillespie method is, that it does not work starting
-# from Δt towards Δstate. Instead, it makes a random choice weighted by the
-# transition propensities, and the random choice determines both the next timed
-# transition to fire, and the size of Δt to slice off from the time axis.
+# The distinguishing quality of Gillespie method is, that it does not work from
+# from Δt towards Δstate. Instead, it makes a random choice of the transition to
+# fire (weighted by the transition propensities) and a random choice of Δt. Both
+# next transition to fire, and the size of Δt to slice off from the time axis are
+# thus stochastically determined.
 # 
 module YPetri::Core::Timed::Gillespie
-  attr_reader :rng
-
-  # Gillespie method initialization.
+  # Returns a random number generator, only created once.
   # 
-  def initialize
-    @rng = ::Random
+  def rng
+    @rng ||= ::Random
   end
 
   # Makes a stochastic number of Gillespie steps necessary to span the period Δt.
@@ -25,7 +24,7 @@ module YPetri::Core::Timed::Gillespie
     update_next_gillespie_time( propensities )
     until ( @next_gillespie_time > target_time )
       gillespie_step! propensities
-      simulation.recorder.alert
+      simulation.recorder.alert!
       propensities = propensity_vector_TS.column_to_a
       update_next_gillespie_time( propensities )
     end
@@ -33,12 +32,6 @@ module YPetri::Core::Timed::Gillespie
     print '.'
   end
 
-  # Name of this method.
-  # 
-  def simulation_method
-    :gillespie
-  end
-
   # This method updates next firing time given propensities.
   # 
   def update_next_gillespie_time( propensities )
@@ -57,7 +50,8 @@ module YPetri::Core::Timed::Gillespie
   # 
   def gillespie_delta_time( propensities )
     sum = Σ propensities
-    mean_period = 1 / sum
+    # mean_period = 1 / sum # TODO: This line seem to be useless
+    # Exponential distribution
     Distribution::Exponential.p_value( rng.rand, sum )
   end
 

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

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+# Timed simulation core.
+# 
+module YPetri::Core::Timed
+  require_relative 'euler'
+  require_relative 'pseudo_euler' # t transitions firing after each step
+  require_relative 'quasi_euler' # t transitions firing after each time tick
+  require_relative 'gillespie'
+  require_relative 'runge_kutta'
+
+  module Methods
+    def method_init
+      extend case simulation_method
+             when :euler then Euler
+             when :pseudo_euler then PseudoEuler
+             when :quasi_euler then QuasiEuler
+             when :gillespie then Gillespie
+             when :runge_kutta then RungeKutta
+             else fail TypeError, "Unknown timed simulation method: #{method}!" end
+    end
+  end
+end

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

@@ -1,29 +1,26 @@
 # encoding: utf-8
 
-# Euler method with timeless transitions firing after each step.
+# Adaptation of Euler method for the systems possibly with timeless transitions
+# and assignment transitions.
 # 
 module YPetri::Core::Timed::PseudoEuler
-  include YPetri::Core::Timed::Euler
-
-  # Name of this method.
-  # 
-  def simulation_method
-    :pseudo_euler
-  end
-
-  # Computes Δ for the period of Δt.
+  # Computes Δ for the period of Δt. Its result is a sum of the contribution of
+  # timed transitions over the period Δt and the contribution of timeless
+  # transitions as if each fired once.
   # 
   def delta Δt
-    super + delta_timeless
+    gradient * Δt + delta_timeless
   end
   alias Δ delta
 
-  # Makes a single step by Δt.
+  # Makes a single step by Δt. Computes system delta, increments marking vector
+  # by it. On top of that, fires all A transitions, increments the simulation
+  # time and alerts the sampler that the system has changed.
   # 
   def step! Δt=simulation.step
     increment_marking_vector Δ( Δt )
     assignment_transitions_all_fire!
     simulation.increment_time! Δt
-    alert
+    alert! # alerts the sampler that the system has changed
   end
 end # YPetri::Core::Timed::PseudoEuler

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

@@ -1,20 +1,21 @@
 # encoding: utf-8
 
-# Euler method with timeless transitions firing every time tick.
+# Adaptation of Euler method for the systems possibly with timeless transitions
+# and assignment transitions. Unlike +pseudo_euler+, which fires every step,
+# +quasi_euler+ fires every time tick. Not implemented yet.
 # 
 module YPetri::Core::Timed::QuasiEuler
-  include YPetri::Core::Timed::Euler
-
-  # Name of this method.
+  # Computes Δ for the period of Δt. Not mplemented yet.
   # 
-  def simulation_method
-    :quasi_euler
+  def delta Δt
+    fail NotImplementedError, "QuasiEuler not implemented yet!"
   end
 
-  # Makes a single step by Δt.
+
+  # Makes a single step by Δt. Not implemented yet.
   # 
   def step! Δt=simulation.step_size
-    fail NotImplementedError
+    fail NotImplementedError, "QuasiEuler not implemented yet!"
     # Now one would have to compare whichever comes first, time tick or the
     # end of Δt, and then again and again, until Δt is fired...
   end

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

@@ -1,22 +1,14 @@
 # encoding: utf-8
 
-# Gillespie method.
+# Runge-Kutta method. Like vanilla Euler method, assumes that only T transitions are in the net.
 # 
-module YPetri::Core::Timed::Euler
-  # Name of this method.
-  # 
-  def simulation_method
-    :runge_kutta
+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
   end
-
-  # FIXME
-
-  # This is from Euler:
-
-  # # Computes Δ for the period of Δt.
-  # # 
-  # def delta Δt
-  #   gradient * Δt
-  # end
-  # alias Δ delta
-end # YPetri::Core::Timed::Euler
+  alias Δ delta
+end # YPetri::Core::Timed::RungeKutta

data/lib/y_petri/core/timed.rb

@@ -2,18 +2,10 @@
 
 # Timed simulation core.
 # 
-class YPetri::Core::Timed < YPetri::Core
-  # Euler method.
-  require_relative 'timed/euler'
-  # Euler with timeless transitions firing after each step.
-  require_relative 'timed/pseudo_euler'
-  # Euler with timeless transitions firing each time tick.
-  require_relative 'timed/quasi_euler'
-  # Gillespie stochastic method.
-  require_relative 'timed/gillespie'
-  # Runge-Kutta fifth-order method.
-  require_relative 'timed/runge_kutta'
-  
+module YPetri::Core::Timed
+  require_relative 'timed/methods'
+  ★ Methods
+
   # Makes a single step by Δt.
   # 
   def step! Δt=simulation.step
@@ -57,9 +49,9 @@ class YPetri::Core::Timed < YPetri::Core
     simulation.TS_rate_closure.call
   end
   alias propensity_vector_TS flux_vector_TS
-end # class YPetri::Core::Timed
+end # module YPetri::Core::Timed
 
-# In general, it is not required that all net elements are simulated with the
+# In general, it is not required that all net nodes are simulated with the
 # same method. Practically, ODE systems have many good simulation methods
 # available.
 #

data/lib/y_petri/core/timeless/methods.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+# Timed simulation core.
+# 
+module YPetri::Core::Timeless
+  require_relative 'pseudo_euler'
+
+  module Methods
+    def method_init
+      extend case simulation_method
+             when :pseudo_euler then PseudoEuler
+             else fail TypeError, "Unknown timeless simulation method: #{method}!" end
+    end
+  end
+end

data/lib/y_petri/core/timeless/pseudo_euler.rb

@@ -1,18 +1,14 @@
 # encoding: utf-8
 
-# Implicit Euler for timeless nets. Simply, timeless transitions
-# fire simultaneously, after which A transitions (if any) fire.
+# Implicit Euler for timeless nets.
 #
 module YPetri::Core::Timeless::PseudoEuler
-  # Name of this method.
+  # Method #step! for timeless +pseudo_euler+ method. Simply, timeless
+  # transitions fire simultaneously, after which, A transitions (if any) fire.
   # 
-  def simulation_method
-    :pseudo_euler
-  end
-
   def step!
     increment_marking_vector Δ
     assignment_transitions_all_fire!
-    alert
+    alert!
   end
 end # module YPetri::Core::Timeless::PseudoEuler

data/lib/y_petri/core/timeless.rb

@@ -1,15 +1,20 @@
 # encoding: utf-8
 
-# Timeless simulation core.
+# Timeless simulator mixin.
 # 
-class YPetri::Core::Timeless < YPetri::Core
-  require_relative 'timeless/pseudo_euler'
+module YPetri::Core::Timeless
+  require_relative 'timeless/methods'
+  ★ Methods
 
+  # Makes a single step.
+  # 
   def delta
     delta_timeless
   end
 
+  # Computes the system state delta.
+  # 
   def Δ
     delta
   end
-end # class YPetri::Core::Timeless
+end # module YPetri::Core::Timeless