Coevolve aggregator for VariableRateJump

HISTORY.md

@@ -0,0 +1,9 @@
+# Breaking updates and feature summaries across releases
+
+## JumpProcesses unreleased (master branch)
+- Support for "bounded" `VariableRateJump`s that can be used with the `Coevolve`
+ aggregator for faster simulation of jump processes with time-dependent rates.
+ In particular, if all `VariableRateJump`s in a pure-jump system are bounded one
+ can use `Coevolve` with `SSAStepper` for better performance. See the
+ documentation, particularly the first and second tutorials, for details on
+ defining and using bounded `VariableRateJump`s.

docs/src/api.md

@@ -13,16 +13,18 @@ reset_aggregated_jumps!
 ## Types of Jumps
 ```@docs
 ConstantRateJump
-VariableRateJump
 MassActionJump
+VariableRateJump
+RegularJump
 JumpSet
 ```
 
 ## Aggregators
 Aggregators are the underlying algorithms used for sampling
-[`MassActionJump`](@ref)s, [`ConstantRateJump`](@ref)s and
+[`ConstantRateJump`](@ref)s, [`MassActionJump`](@ref)s, and
 [`VariableRateJump`](@ref)s.
 ```@docs
+Coevolve
 Direct
 DirectCR
 FRM
@@ -31,7 +33,6 @@ RDirect
 RSSA
 RSSACR
 SortingDirect
-Coevolve
 ```
 
 # Private API Functions

docs/src/faq.md

@@ -1,19 +1,20 @@
 # FAQ
 
 ## My simulation is really slow and/or using a lot of memory, what can I do?
-Exact methods simulate each and every jump. To reduce memory use, use
-`save_positions=(false,false)` in the `JumpProblem` constructor as described
-[earlier](@ref save_positions_docs) to turn off saving the system state before
-and after every jump. You often do not need to save all jump poisitons when you
-only want to track cumulative counts. Combined with use of `saveat` in the call
-to `solve` this can dramatically reduce memory usage.
-
-While `Direct` is often fastest for systems with 10 or less `ConstantRateJump`s,
-`VariableRateJump`s, and/or or `MassActionJump`s, if your system has many jumps
-or one jump occurs most frequently, other stochastic simulation algorithms may
-be faster. See [Jump Aggregators for Exact Simulation](@ref) and the subsequent
-sections there for guidance on choosing different SSAs (called aggregators in
-JumpProcesses).
+Exact methods simulate every jump, and by default save the state before and
+after each jump. To reduce memory use, use `save_positions = (false, false)` in
+the `JumpProblem` constructor as described [earlier](@ref save_positions_docs)
+to turn off saving the system state before and after every jump. Combined with
+use of `saveat` in the call to `solve`, to specify the specific times at which
+to save the state, this can dramatically reduce memory usage.
+
+While `Direct` is often fastest for systems with 10 or less `ConstantRateJump`s
+and/or `MassActionJump`s, if your system has many jumps or one jump occurs most
+frequently, other stochastic simulation algorithms may be faster. See [Jump
+Aggregators for Exact Simulation](@ref) and the subsequent sections there for
+guidance on choosing different SSAs (called aggregators in JumpProcesses). For
+systems with bounded `VariableRateJump`s using `Coevolve` with `SSAStepper`
+instead of an ODE/SDE time stepper can give a significant performance boost.
 
 ## When running many consecutive simulations, for example within an `EnsembleProblem` or loop, how can I update `JumpProblem`s?
 
@@ -25,8 +26,9 @@ internal aggregators for each new parameter value or initial condition.
 ## How can I define collections of many different jumps and pass them to `JumpProblem`?
 
 We can use `JumpSet`s to collect jumps together, and then pass them into
-`JumpProblem`s directly. For example, using the `ConstantRateJump`,
-`VariableRateJump` and `MassActionJump` defined earlier we can write
+`JumpProblem`s directly. For example, using a `MassActionJump` and
+`ConstantRateJump` defined in the [second tutorial](@ref ssa_tutorial), we can
+write
 
 ```julia
 jset = JumpSet(mass_act_jump, birth_jump)
@@ -45,8 +47,8 @@ vj1 = VariableRateJump(rate3, affect3!)
 vj2 = VariableRateJump(rate4, affect4!)
 vjtuple = (vj1, vj2)
 
-jset = JumpSet(; constant_jumps=cjvec, variable_jumps=vjtuple,
-                 massaction_jumps=mass_act_jump)
+jset = JumpSet(; constant_jumps = cjvec, variable_jumps = vjtuple,
+                 massaction_jumps = mass_act_jump)
 ```
 
 ## How can I set the random number generator used in the jump process sampling algorithms (SSAs)?
@@ -69,15 +71,15 @@ default. On versions below 1.7 it uses `Xoroshiro128Star`.
 ## What are these aggregators and aggregations in JumpProcesses?
 
 JumpProcesses provides a variety of methods for sampling the time the next
-`ConstantRateJump`, `VariableRateJump` or `MassActionJump` occurs, and which
+`ConstantRateJump`, `MassActionJump`, or `VariableRateJump` occurs, and which
 jump type happens at that time. These methods are examples of stochastic
 simulation algorithms (SSAs), also known as Gillespie methods, Doob's method, or
-Kinetic Monte Carlo methods. These are catch-all terms for jump (or point)
-processes simulation methods most commonly used in the biochemistry literature.
-In the JumpProcesses terminology we call such methods "aggregators", and the
-cache structures that hold their basic data "aggregations". See [Jump
-Aggregators for Exact Simulation](@ref) for a list of the available SSA
-aggregators.
+Kinetic Monte Carlo methods. These are all names for jump (or point) processes
+simulation methods used across the biology, chemistry, engineering, mathematics,
+and physics literature. In the JumpProcesses terminology we call such methods
+"aggregators", and the cache structures that hold their basic data
+"aggregations". See [Jump Aggregators for Exact Simulation](@ref) for a list of
+the available SSA aggregators.
 
 ## How should jumps be ordered in dependency graphs?
 Internally, JumpProcesses SSAs (aggregators) order all `MassActionJump`s first,
@@ -108,10 +110,10 @@ then follow this ordering when assigning an integer id to each jump.
 See also [Jump Aggregators Requiring Dependency Graphs](@ref) for
 more on dependency graphs needed for the various SSAs.
 
-## How do I use callbacks with `ConstantRateJump`, `VariableRateJump` or `MassActionJump` systems?
+## How do I use callbacks with jump simulations?
 
-Callbacks can be used with `ConstantRateJump`s, `VariableRateJump`s and
-`MassActionJump`s. When solving a pure jump system with `SSAStepper`, only
+Callbacks can be used with `ConstantRateJump`s, `MassActionJump`s, and
+`VariableRateJump`s. When solving a pure jump system with `SSAStepper`, only
 discrete callbacks can be used (otherwise a different time stepper is needed).
 When using an ODE or SDE time stepper any callback should work.
 

docs/src/jump_solve.md

@@ -6,31 +6,36 @@ solve(prob::JumpProblem,alg;kwargs)
 
 ## Recommended Methods
 
-Because `JumpProblem`s can be solved with two classes of methods, exact and
-inexact, they come in two forms. Exact algorithms tend to describe the
-realization of each jump chronologically. Alternatively, inexact methods tend to
-take small leaps through time so they are guaranteed to terminate in finite
-time. These methods can be much faster as they only simulate the total number of
-points in each leap interval and thus do not need to simulate the realization of
-every single jump. Jumps for exact methods can be defined with
-`ConstantRateJump`, `VariableRateJump` and/or `MassActionJump`  On the other
-hand, jumps for inexact methods are defined with `RegularJump`.
-
-There are special algorithms available for a pure exact `JumpProblem` (a
-`JumpProblem` over a  `DiscreteProblem`).  The `SSAStepper()` is an efficient
-streamlined integrator for running simulation algorithms of such problems. This
-integrator is named after the term Stochastic Simulation Algorithm (SSA) which
-is a catch-all term in biochemistry to denote algorithms for simulating jump
-processes. In turn, we denote aggregators algorithms for simulating jump
-processes that can use the `SSAStepper()` integrator. These algorithms can solve
-problems initialized with `ConstantRateJump`, `VariableRateJump` and/or
-`MassActionJump`.  Although `SSAStepper()` is usually faster, it is not
-compatible with event handling. If events are necessary, then `FunctionMap` does
-well.
-
-If there is a `RegularJump`, then inexact methods must be used. The current
-recommended method is `TauLeaping` if you need adaptivity, events, etc. If you
-just need the most barebones fixed time step leaping method, then
+`JumpProblem`s can be solved with two classes of methods, exact and inexact.
+Exact algorithms currently sample realizations of the jump processes in
+chronological order, executing individual jumps sequentially at randomly sampled
+times. In contrast, inexact (τ-leaping) methods are time-step based, executing
+multiple occurrences of jumps during each time-step. These methods can be much
+faster as they only simulate the total number of jumps over each leap interval,
+and thus do not need to simulate the realization of every single jump. Jumps for
+use with exact simulation methods can be defined as `ConstantRateJump`s,
+`MassActionJump`s, and/or `VariableRateJump`. Jumps for use with inexact
+τ-leaping methods should be defined as `RegularJump`s.
+
+There are special algorithms available for efficiently simulating an exact, pure
+`JumpProblem` (i.e. a `JumpProblem` over a `DiscreteProblem`).  `SSAStepper()`
+is an efficient streamlined integrator for time stepping such problems from
+individual jump to jump. This integrator is named after Stochastic Simulation
+Algorithms (SSAs), commonly used naming in chemistry and biology applications
+for the class of exact jump process simulation algorithms. In turn, we denote by
+"aggregators" the algorithms that `SSAStepper` calls to calculate the next jump
+time and to execute a jump (i.e. change the system state appropriately). All
+JumpProcesses aggregators can be used with `ConstantRateJump`s and
+`MassActionJump`s, with a subset of aggregators also working with bounded
+ `VariableRateJump`s (see [the first tutorial](@ref poisson_proc_tutorial) for
+the definition of bounded `VariableRateJump`s). Although `SSAStepper()` is
+usually faster, it only supports discrete events (`DiscreteCallback`s), for pure
+jump problems requiring continuous events (`ContinuousCallback`s) the less
+performant `FunctionMap` time-stepper can be used.
+
+If there is a `RegularJump`, then inexact τ-leaping methods must be used. The
+current recommended method is `TauLeaping` if one needs adaptivity, events, etc.
+If ones only needs the most barebones fixed time-step leaping method, then
 `SimpleTauLeaping` can have performance benefits.
 
 ## Special Methods for Pure Jump Problems
@@ -41,9 +46,10 @@ algorithms are optimized for pure jump problems.
 
 ### JumpProcesses.jl
 
-- `SSAStepper`: a stepping integrator for pure `ConstantRateJump`,
-  `VariableRateJump` and/or `MassActionJump` `JumpProblem`s. Supports handling
-  of `DiscreteCallback` and saving controls like `saveat`.
+- `SSAStepper`: a stepping integrator for `JumpProblem`s defined over
+  `DiscreteProblem`s involving `ConstantRateJump`s, `MassActionJump`s, and/or
+  bounded `VariableRateJump`s . Supports handling of `DiscreteCallback`s and
+  saving controls like `saveat`.
 
 ## RegularJump Compatible Methods