Merge a6f8889 into f923fad

docs/make.jl

@@ -1,7 +1,9 @@
 using Documenter, JumpProcesses
 
-cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
-cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
+docpath = Base.source_dir()
+assetpath = joinpath(docpath, "src", "assets")
+cp(joinpath(docpath, "Manifest.toml"), joinpath(assetpath, "Manifest.toml"), force = true)
+cp(joinpath(docpath, "Project.toml"), joinpath(assetpath, "Project.toml"), force = true)
 
 include("pages.jl")
 

docs/src/api.md

@@ -13,14 +13,15 @@ reset_aggregated_jumps!
 ## Types of Jumps
 ```@docs
 ConstantRateJump
-MassActionJump
 VariableRateJump
+MassActionJump
 JumpSet
 ```
 
 ## Aggregators
 Aggregators are the underlying algorithms used for sampling
-[`MassActionJump`](@ref)s and [`ConstantRateJump`](@ref)s.
+[`MassActionJump`](@ref)s, [`ConstantRateJump`](@ref)s and
+[`VariableRateJump`](@ref)s.
 ```@docs
 Direct
 DirectCR
@@ -30,10 +31,11 @@ RDirect
 RSSA
 RSSACR
 SortingDirect
+Coevolve
 ```
 
 # Private API Functions
 ```@docs
 ExtendedJumpArray
 SSAIntegrator
-```
+```

docs/src/faq.md

@@ -1,16 +1,19 @@
 # FAQ
 
 ## My simulation is really slow and/or using a lot of memory, what can I do?
-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` this can dramatically reduce memory usage.
-
-While `Direct` is often fastest for systems with 10 or less `ConstantRateJump`s
-or `MassActionJump`s, if your system has many jumps or one jump occurs most
-frequently, other stochastic simulation algorithms may be faster. See [Constant
-Rate Jump Aggregators](@ref) and the subsequent sections there for guidance on
-choosing different SSAs (called aggregators in JumpProcesses).
+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).
 
 ## When running many consecutive simulations, for example within an `EnsembleProblem` or loop, how can I update `JumpProblem`s?
 
@@ -22,8 +25,8 @@ 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 `MassActionJump` and
-`ConstantRateJump` defined earlier we can write
+`JumpProblem`s directly. For example, using the `ConstantRateJump`,
+`VariableRateJump` and `MassActionJump` defined earlier we can write
 
 ```julia
 jset = JumpSet(mass_act_jump, birth_jump)
@@ -66,16 +69,19 @@ 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` or `MassActionJump` 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. In the JumpProcesses terminology we call such methods "aggregators", and
-the cache structures that hold their basic data "aggregations". See [Constant
-Rate Jump Aggregators](@ref) for a list of the available SSA aggregators.
+`ConstantRateJump`, `VariableRateJump` or `MassActionJump` 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.
 
 ## How should jumps be ordered in dependency graphs?
 Internally, JumpProcesses SSAs (aggregators) order all `MassActionJump`s first,
-then all `ConstantRateJumps`. i.e. in the example
+then all `ConstantRateJumps` and/or `VariableRateJumps`. i.e. in the example
 
 ```julia
 using JumpProcesses
@@ -99,15 +105,15 @@ The four jumps would be ordered by the first jump in `maj`, the second jump in
 `maj`, `cj1`, and finally `cj2`. Any user-generated dependency graphs should
 then follow this ordering when assigning an integer id to each jump.
 
-See also [Constant Rate Jump Aggregators Requiring Dependency Graphs](@ref) for
+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` or `MassActionJump` systems?
+## How do I use callbacks with `ConstantRateJump`, `VariableRateJump` or `MassActionJump` systems?
 
-Callbacks can be used with `ConstantRateJump`s and `MassActionJump`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.
+Callbacks can be used with `ConstantRateJump`s, `VariableRateJump`s and
+`MassActionJump`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.
 
 *Note, when modifying `u` or `p` within a callback, you must call
 [`reset_aggregated_jumps!`](@ref) after making updates.* This ensures that the

docs/src/index.md

@@ -1,9 +1,10 @@
 # JumpProcesses.jl: Stochastic Simulation Algorithms for Jump Processes, Jump-ODEs, and Jump-Diffusions
 JumpProcesses.jl, formerly DiffEqJump.jl, provides methods for simulating jump
-processes, known as stochastic simulation algorithms (SSAs), Doob's method,
-Gillespie methods, or Kinetic Monte Carlo methods across different fields of
-science. It also enables the incorporation of jump processes into hybrid
-jump-ODE and jump-SDE models, including jump diffusions.
+(or point) processes. Across different fields of science such methods are also
+known as stochastic simulation algorithms (SSAs), Doob's method, Gillespie
+methods, or Kinetic Monte Carlo methods . It also enables the incorporation of
+jump processes into hybrid jump-ODE and jump-SDE models, including jump
+diffusions.
 
 JumpProcesses is a component package in the [SciML](https://sciml.ai/) ecosystem,
 and one of the core solver libraries included in
@@ -78,31 +79,33 @@ versioninfo() # hide
 ```
 ```@example
 using Pkg # hide
-Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 ```
 ```@raw html
 </details>
 ```
 ```@raw html
-You can also download the 
+You can also download the
 <a href="
 ```
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
+projtoml = joinpath("..", "..", "Project.toml")
+version = TOML.parse(read(projtoml, String))["version"]
+name = TOML.parse(read(projtoml, String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version * "/assets/Manifest.toml"
 ```
 ```@raw html
 ">manifest</a> file and the
 <a href="
 ```
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
+projtoml = joinpath("..", "..", "Project.toml")
+version = TOML.parse(read(projtoml, String))["version"]
+name = TOML.parse(read(projtoml, String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version * "/assets/Project.toml"
 ```
 ```@raw html
 ">project</a> file.
-```
+```

docs/src/jump_solve.md

@@ -6,19 +6,32 @@ solve(prob::JumpProblem,alg;kwargs)
 
 ## Recommended Methods
 
-A `JumpProblem(prob,aggregator,jumps...)` comes in two forms. The first major
-form is if it does not have a `RegularJump`. In this case, it can be solved with
-any integrator on  `prob`. However, in the case of a pure `JumpProblem` (a
-`JumpProblem` over a  `DiscreteProblem`), there are special algorithms
-available.  The `SSAStepper()` is an efficient streamlined algorithm for running
-the  `aggregator` version of the SSA for pure `ConstantRateJump` and/or
-`MassActionJump` problems. However, it is not compatible with event handling. If
-events are necessary, then `FunctionMap` does well.
-
-If there is a `RegularJump`, then specific methods must be used. The current
+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 `SimpleTauLeaping`
-can have performance benefits.
+just need the most barebones fixed time step leaping method, then
+`SimpleTauLeaping` can have performance benefits.
 
 ## Special Methods for Pure Jump Problems
 
@@ -28,9 +41,9 @@ algorithms are optimized for pure jump problems.
 
 ### JumpProcesses.jl
 
-- `SSAStepper`: a stepping algorithm for pure `ConstantRateJump` and/or
-  `MassActionJump` `JumpProblem`s. Supports handling of `DiscreteCallback`
-  and saving controls like `saveat`.
+- `SSAStepper`: a stepping integrator for pure `ConstantRateJump`,
+  `VariableRateJump` and/or `MassActionJump` `JumpProblem`s. Supports handling
+  of `DiscreteCallback` and saving controls like `saveat`.
 
 ## RegularJump Compatible Methods