y_petri 2.0.14 → 2.0.15

data/lib/y_petri/{timed_simulation.rb → simulation/timed.rb}

@@ -1,8 +1,9 @@
 # -*- coding: utf-8 -*-
-# A descendant class of YPetri::Simulation that introduces timekeeping.
+
+# A mixin for timed simulations.
 # 
-class YPetri::TimedSimulation < YPetri::Simulation
-  SAMPLING_TIME_DECIMAL_PLACES = SAMPLING_DECIMAL_PLACES
+module YPetri::Simulation::Timed
+  SAMPLING_TIME_DECIMAL_PLACES = 5
   SIMULATION_METHODS =
     [
       [ :Euler ],
@@ -41,9 +42,9 @@ class YPetri::TimedSimulation < YPetri::Simulation
   # (:step_size, :sampling_period and :time_range).
   # 
   def settings
-    { step_size: step_size,
-      sampling_period: sampling_period,
-      time_range: time_range }
+    { step: step_size,
+      sampling: sampling_period,
+      time: time_range }
   end
   alias simulation_settings settings
 
@@ -72,26 +73,6 @@ class YPetri::TimedSimulation < YPetri::Simulation
   #   Δ_Euler_free
   # end
 
-  # In addition to the arguments required by the regular simulation
-  # constructor, timed simulation constructor also expects :step_size
-  # (alias :step), :sampling_period (alias :sampling), and :target_time
-  # named arguments.
-  # 
-  def initialize( **named_args )
-    named_args.must_have :step_size, syn!: :step
-    named_args.must_have :sampling_period, syn!: :sampling
-    named_args.may_have :target_time
-    named_args.may_have :initial_time
-    @step_size = named_args.delete :step_size
-    @sampling_period = named_args.delete :sampling_period
-    @target_time = named_args.delete :target_time
-    @initial_time = named_args.delete( :initial_time ) ||
-      @target_time.nil? ? nil : @sampling_period * 0 # @target_time.class.zero
-    super( **named_args )
-    @zero_gradient = @zero_ᴍ.map { |e| step_size.to_f / step_size * e }
-  end
-  # LATER: transition clamps
-
   # Allows to explore the system at different state / time. Creates a double,
   # which is set to the required state / time. In addition to the parent class,
   # this version alseo sets time.
@@ -100,11 +81,43 @@ class YPetri::TimedSimulation < YPetri::Simulation
     super( **oo ).tap { |duplicate| duplicate.send :set_time, time }
   end
 
-  # At the moment, near alias for #run_to_arget_time!
+  # Near alias for #run!, checks against infinite run.
   # 
-  def run! until_time=target_time
-    run_until_target_time! until_time
-    return self
+  def run( until_time=target_time, final_step: :exact )
+    fail "Target time equals infinity!" if target_time = Float::INFINITY
+    run! until_time, final_step: final_step
+  end
+
+  # Near alias for #run_until, uses @target_time as :until_time by default.
+  # 
+  def run!( until_time=target_time, final_step: :exact )
+    run_until until_time, final_step: final_step
+  end
+
+  # Runs the simulation until the target time, using step! method. The second
+  # optional parameter tunes the behavior towards the end of the run, with
+  # alternatives :just_before, :just_after and :exact (default).
+  #
+  # just_before:     all steps have normal size, simulation stops
+  #                  before or just on the target time
+  # just_after:      all steps have normal size, simulation stops
+  #                  after or just on the target time_step
+  # exact:           simulation stops exactly on the prescribed time,
+  #                  to make this possible last step is shortened if necessary
+  #
+  def run_until( target_time, final_step: :exact )
+    case final_step
+    when :before then              # step until on or just before the target
+      step! while @time + @step_size <= target_time
+    when :exact then               # simulate to exact time
+      step! while @time + @step_size < target_time
+      step!( target_time - @time ) # make a short last step as required
+      @time = target_time          # to get exactly on the prescribed time
+    when :after then               # step until on or after target
+      step! while @time < target_time
+    else
+      fail ArgumentError, "Unrecognized :final_step option: #{final_step}"
+    end
   end
 
   # Scalar field gradient for free places.
@@ -112,9 +125,9 @@ class YPetri::TimedSimulation < YPetri::Simulation
   def gradient_for_free_places
     g_sR = gradient_for_sR
     if g_sR then
-      S_for_SR() * flux_vector_for_SR + g_sR
+      S_SR() * flux_vector_for_SR + g_sR
     else
-      S_for_SR() * flux_vector_for_SR
+      S_SR() * flux_vector_for_SR
     end
   end
 
@@ -135,8 +148,8 @@ class YPetri::TimedSimulation < YPetri::Simulation
   # 
   def Δ_Euler_for_free_places( Δt=step_size )
     # Here, ∂ represents all R transitions, to which TSr and Tsr are added:
-    g_free = gradient_for_free_places * Δt
-    g_free + Δ_for_TSr( Δt ) + Δ_for_Tsr( Δt )
+    delta_free = gradient_for_free_places * Δt
+    delta_free + Δ_TSr( Δt ) + Δ_Tsr( Δt )
   end
   alias Δ_euler_for_free_places Δ_Euler_for_free_places
   alias ΔE Δ_Euler_for_free_places
@@ -189,13 +202,13 @@ class YPetri::TimedSimulation < YPetri::Simulation
       note_state_change!
     when :Euler_with_timeless_transitions_firing_after_each_step,
       :pseudo_Euler then
-      Euler_step!
+      Euler_step! Δt
       timeless_transitions_all_fire!
       note_state_change!
     when :Euler_with_timeless_transitions_firing_after_each_time_tick,
       :quasi_Euler then
       raise                          # FIXME: quasi_Euler doesn't work yet
-      Euler_step!
+      Euler_step! Δt
       # if time tick has elapsed, call #timeless_transitions_all_fire!
       note_state_change!
     else
@@ -204,41 +217,16 @@ class YPetri::TimedSimulation < YPetri::Simulation
     return self
   end
 
-  # Runs the simulation until the target time, using step! method. The second
-  # optional parameter tunes the behavior towards the end of the run, with
-  # alternatives :just_before, :just_after and :exact (default).
-  #
-  # just_before:     all steps have normal size, simulation stops
-  #                  before or just on the target time
-  # just_after:      all steps have normal size, simulation stops
-  #                  after or just on the target time_step
-  # exact:           simulation stops exactly on the prescribed time,
-  #                  to make this possible last step is shortened if necessary
-  #
-  def run_until_target_time!( t=target_time, stepping_opt=:exact )
-    case stepping_opt
-    when :just_before then    # step until on or just before the target
-      step! while @time + @step_size <= t
-    when :exact then          # simulate to exact time
-      step! while @time + @step_size < t
-      step!( t - @time )      # make a short last step as required
-      @time = t               # to get exactly on the prescribed time
-    when :just_after then     # step until on or after target
-      step! while @time < t
-    else raise "Invalid stepping option: #{stepping_opt}" end
-  end
-  alias run_until! run_until_target_time!
-
   # Produces the inspect string for this timed simulation.
   # 
   def inspect
-    "#<YPetri::TimedSimulation: #{pp.size} places, #{tt.size} " +
-      "transitions, time: #{time}, object id: #{object_id} >"
+    "#<Simulation: Time: #{time}, #{pp.size} places, #{tt.size} " +
+      "transitions, object id: #{object_id}>"
   end
 
   # Produces a string brief
   def to_s                         # :nodoc:
-    "TimedSimulation[ #{pp.size} pp, #{tt.size} tt, T: #{time} ]"
+    "Simulation[T: #{time}, pp: #{pp.size}, tt: #{tt.size}]"
   end
 
   private
@@ -270,15 +258,14 @@ class YPetri::TimedSimulation < YPetri::Simulation
     @time = t
   end
 
-  # Duplicate creation. TODO: Like with Simulation#duplicate, this should
-  # be thought over, whether this should actually be #dup or #clone method.
+  # Duplicate creation.
   # 
-  def duplicate
+  def dup
     instance = super
     instance.send :set_time, time
     return instance
   end
-end # class YPetri::TimedSimulation
+end # module YPetri::Simulation::Timed
 
 # In general, it is not required that all net elements are simulated with the
 # same method. Practically, ODE systems have many good simulation methods