lib/y_petri/transition/T.rb in y_petri-2.4.4 vs lib/y_petri/transition/T.rb in y_petri-2.4.6

@@ -8,11 +8,41 @@
   def function
     rate_closure
   end
 
   # Transition's action (before validation). Requires Δt as an argument.
-  # 
+  #
   def action Δt
+    # TODO: Unhelpful error occurs if the user constructs a transition
+    # like this:
+    #
+    #   T = Transition s: { A: -1, B: 2 },
+    #                  rate: -> { 0.1 }    # constant rate
+    #
+    # The user meant to construct a TS transition with constant rate and
+    # stoichiometry { A: -1, B: 2 }, but the lambda given under :rate
+    # parameter is nullary, while the stoichiometry is taken to imply that
+    # the domain consists of place 1.
+    #
+    #   T.action 5.0
+    #
+    # then causes error because it tries to supply the marking of A to
+    # the user-supplied rate closure, which is nullary.
+    #
+    # There are 2 problems with this:
+    #
+    # Firstly, if we choose to see this as the user's problem, the user
+    # supplied the Transition constructor with invalid input, but received
+    # no warning (problem 1). The user learned about the error by typing
+    # T.action 5.0, and the error message is quite unhelpful (problem 2) -
+    # it does not inform the user that the rate closure has wrong arity.
+    #
+    # We, we might deside to see this as a missing feature and make sure
+    # that in these cases, the constructor infers that the codomain is
+    # empty from the fact that the supplied rate closure is nullary. This
+    # requires additional thinking, because it is not possible to infer
+    # domain from rate lamdas with non-matching arity in general.
+    # 
     if stoichiometric? then
       rate = rate_closure.( *domain_marking )
       stoichiometry.map { |coeff| rate * coeff * Δt }
     else
       Array( rate_closure.( *domain_marking ) ).map { |e| e * Δt }