update docs some

docs/pages.jl

@@ -1,11 +1,10 @@
 # Put in a separate page so it can be used by SciMLDocs.jl
 
 pages = ["index.md",
-    "getting_started.md",
     "Tutorials" => Any["tutorials/simple_poisson_process.md",
         "tutorials/discrete_stochastic_example.md",
-        "tutorials/jump_diffusion.md",
         "tutorials/point_process.md",
+        "tutorials/jump_diffusion.md",
         "tutorials/spatial.md"],
     "Type Documentation" => Any["Jumps, JumpProblem, and Aggregators" => "jump_types.md",
         "Jump solvers" => "jump_solve.md"],

docs/src/index.md

@@ -1,69 +1,113 @@
 # JumpProcesses.jl: Stochastic Simulation Algorithms for Jump Processes, Jump-ODEs, and Jump-Diffusions
 
-JumpProcesses.jl, formerly DiffEqJump.jl, provides methods for simulating jump
-and point processes. Across different fields of science, such methods are also
-known as stochastic simulation algorithms (SSAs), Doob's method, Gillespie
-methods, Kinetic Monte Carlo's methods, thinning method, Ogatha's method. It
-also enables the incorporation of jump processes into hybrid jump-ODE and
-jump-SDE models, including jump diffusions.
+JumpProcesses.jl provides methods for simulating jump and point processes.
+Across different fields of science, such methods are also known as stochastic
+simulation algorithms (SSAs), Doob's method, Gillespie methods, Kinetic Monte
+Carlo's methods, thinning method, and Ogata's method. It also enables the
+incorporation of jump processes into hybrid jump-ODEs models, including
+piecewise deterministic Markov processes, and into hybrid jump-SDE models,
+including jump diffusions. It is a component package in the
+[SciML](https://sciml.ai/) ecosystem, and one of the core solver libraries
+included in
+[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/).
 
 Historically, jump processes have been developed in the context of dynamical
-systems to describe dynamics with sudden changes — the jumps — in a system's
+systems to describe dynamics with discontinuous changes — the jumps — in a system's
 value at random times. In contrast, the development of point processes has been
 more focused on describing the occurrence of random events — the points — over
-a support. In reality, jump and point processes share many things in common
-which make JumpProcesses ideal for both.
+a support. However, both jump and point processes share many things in common
+which make JumpProcesses ideal for their study.
 
-Let ``dN_i(t)`` be a stochastic process such that ``dN_i(t) = 1`` with some
-probability and ``0`` otherwise. In a sense, ``dN_i(t)`` is a Bernoulli
-distribution over a tiny interval which represents our jump. The rate in which
-we observe jumps is given by the intensity rate, ``E(dN_i(t)) = \lambda_i(t)
-dt``. As ``dN_i(t)`` is a function of time, any differential equation can be
-extended by jumps.
+As jump and point processes are often considered from a variety of perspectives
+across different fields, JumpProcesses provides three tutorials on using the
+package for those with different backgrounds:
 
-For example, we have an ODE with jumps ``i``, denoted by
+- [Simulating basic Poisson processes](@ref poisson_proc_tutorial)
+- [Simulating jump processes via SSAs (i.e., Gillespie methods)](@ref ssa_tutorial)
+- [Temporal point processes (TPP)](@ref tpp_tutorial)
 
-```math
-du = f(u,p,t)dt + \sum_{i} h_i(u,p,t) dN_i(t) 
-```
+These tutorials also explain the types of jump/point processes that can be
+mathematically modelled with JumpProcesses.jl. For more complicated models that
+couple ODEs and/or SDEs with continuous noise to jump processes, we provide a
+tutorial on
+
+- [Simulating jump-diffusion processes](@ref jump_diffusion_tutorial)
+
+Finally, for jump processes that involve spatial transport on a graph/mesh, such
+as Reaction-Diffusion Master Equation models, we provide a tutorial on
+
+- [Spatial SSAs](@ref Spatial-SSAs-with-JumpProcesses.
 
-Functions ``f(u, p, t)`` and ``h(u, p, t)`` represent the impact of the drift
-and jumps on the state variable respectively.
+We provide a mathematical overview of the library below, but note users may also
+skip to the appropriate tutorial listed above to get started with using
+JumpProcesses.
 
-Extending a stochastic differential equation (SDE) to have jumps is commonly
-known as a jump-diffusion, and is denoted by
+## Mathematical Overview
+
+Let ``dN_i(t)`` be a stochastic process such that ``dN_i(t) = 1`` with some
+probability and ``0`` otherwise. That is, ``dN_i(t)`` encodes that a "jump" in
+the value of ``N_i(t)`` by one occurs at time ``t``. Denote the rate, i.e.
+probability per time, that such jumps occur by the intensity function,
+``\lambda_i(u(t), p, t)``. Here ``u(t)`` represents a vector of dynamic state
+variables, that may change when ``N_i(t)`` jumps. For example, these could be
+the size of a population changing due to births or deaths, or the number of
+mRNAs and proteins within a cell (which jump when a gene is transcribed or an
+mRNA is translated). ``p`` represents parameters the intensity may depend on.
+
+In different fields ``\lambda_i`` can also be called a propensity, transition
+rate function, or a hazard function. Note, if we denote ``N(t) \equiv N[0, t)``
+as the number of points since the start of time until ``t``, exclusive of ``t``,
+then ``N(t)`` is a stochastic random integer measure. In other words, we have a
+temporal point process (TPP).
+
+In JumpProcesses.jl's language, we call ``\lambda_i`` a rate function, and
+expect users to provide a function, `rate(u,p,t)`, that returns its value at
+time `t`. Given a collection of rates``\{\lambda_i\}_{i=1}^I``, JumpProcesses
+can then generate exact realizations of pure jump processes of the form
 
 ```math
-du = f(u,p,t)dt + \sum_{i}g_i(u,t)dW_i(t) + \sum_{j}h_i(u,p,t)dN_i(t)
+du = \sum_{i=1}^I h_i(u,p,t) dN_i(t),
 ```
+where ``h_i(u,p,t)`` represents the amount that ``u(t)`` changes when ``N_i(t)``
+jumps. JumpProcesses encodes such changes via a user-provided `affect!`
+function, which allows even more general changes to the state, ``u(t)``, when
+``N_i(t)`` jumps than just incrementing it by ``h_i(u,p,t)``. For example, such
+changes can themselves be random, allowing for the calculation of marks. In the
+special case of just one jump, ``I = 1``, with ``h_1 = 1``, we recover the
+temporal point process mentioned above.
+
+JumpProcesses provides a variety of algorithms, called *aggregators*, for
+determining the next time that a jump occurs, and which ``N_i(t)`` jumps at that
+time. Many of these are optimized for contexts in which each ``N_i(t)`` only
+changes the values of a few components in ``u(t)``, as common in many
+applications such as stochastic chemical kinetics (where each ``N_i``
+corresponds to a different reaction, and each component of ``u`` a different
+species). To simulate ``u(t)`` users must then specify both an aggregator
+algorithm to determine the time and type of jump that occurs, and a
+time-stepping method to advance the state from jump to jump. See the tutorials
+listed above, and reference links below, for more details and examples.
+
+JumpProcesses also allows such jumps to be coupled into ODE models, as in
+piecewise deterministic Markov Processes, or continuous-noise SDE models, as in
+jump-diffusions. For example, a jump-diffusion JumpProcesses can
+simulate would be
 
-By diffusion we mean a continuous stochastic process which is usually
-represented as Gaussian white noise (i.e. ``W_j(t)`` is a Brownian Motion).
-
-Concurrently, if we denote ``N(t) \equiv N[0, t)`` as the number of points
-since the start of time until ``t``, exclusive of ``t``, then ``N(t)`` is a
-stochastic random integer measure. In other words, we have a temporal point
-process (TPP).
+```math
+du = f(u,p,t)dt + \sum_{i}g_i(u,t)dW_i(t) + \sum_{j}h_j(u,p,t)dN_j(t)
+```
 
-JumpProcesses is designed to simulate all jumps above. It is a component
-package in the [SciML](https://sciml.ai/) ecosystem, and one of the core solver
-libraries included in
-[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/).
+where ``f`` encodes the drift of the process, ``g_i`` the strength of the
+diffusion of the process, and ``W_i(t)`` denotes a standard Brownian Motion.
 
-The documentation includes tutorials and examples:
+JumpProcesses is designed to simulate all the types of jumps described above.
 
-  - [Getting Started with JumpProcesses in Julia](@ref)
-  - [Simulating basic Poisson processes](@ref poisson_proc_tutorial)
-  - [Simulating jump processes via SSAs (i.e., Gillespie methods)](@ref ssa_tutorial)
-  - [Simulating jump-diffusion processes](@ref jump_diffusion_tutorial)
-  - [Temporal point processes (TPP)](@ref tpp_tutorial)
-  - [Spatial SSAs](@ref Spatial-SSAs-with-JumpProcesses.jl)
+## Reference Documentation
 
-In addition to that the document contains references to guide you through:
+In addition to the tutorials linked above, the documentation contains
 
   - [References on the types of jumps and available simulation methods](@ref jump_problem_type)
   - [References on jump time stepping methods](@ref jump_solve)
-  - [FAQ with information on changing parameters between simulations and using callbacks](@ref FAQ)
+  - [An FAQ with information on changing parameters between simulations and using callbacks](@ref FAQ)
   - [API documentation](@ref JumpProcesses.jl-API)
 
 ## Installation
@@ -96,7 +140,7 @@ Pkg.add("JumpProcesses")
 
   - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
   - There are a few community forums for getting help and asking questions:
-    
+
       + The #diffeq-bridged and #sciml-bridged channels in the
         [Julia Slack](https://julialang.org/slack/)
       + The #diffeq-bridged and #sciml-bridged channels in the

docs/src/tutorials/point_process.md

@@ -1,8 +1,8 @@
 # [Temporal Point Processes (TPP) with JumpProcesses] (@id tpp_tutorial)
 
 JumpProcesses was initially developed to simulate the trajectory of jump
-processes. Therefore, those with a background in point process might find a lot
-of the nomenclature in this library confusing. In reality, jump and point
+processes. Therefore, those with a background in point process might find the
+nomenclature in the library documentation confusing. In reality, jump and point
 processes share many things in common, but diverge in scope. This tutorial will
 cover JumpProcesses from the perspective of point process theory.
 
@@ -13,29 +13,29 @@ more focused on describing the occurrence of random events — the points — ov
 a support. The fact that any temporal point process (TPP) that satisfies some
 basic assumptions can be described in terms of a stochastic differential
 equation (SDE) with discontinuous jumps — more commonly known as a jump process
-— makes TPP a good model for JumpProcesses.
+— means TPPs can be simulated with JumpProcesses.
 
 ## [TPP Theory](@id tpp_theory)
 
 TPPs describe a set of discrete points over continuous time. Conventionally, we
 assume that time starts at ``0``. We can represent a TPP as a random integer
 measure ``N( \cdot )``, this random function counts the number of points in
-a set of intervals over the Real line. For instance, ``N([5, 10])`` denotes the
+a set of intervals over the real line. For instance, ``N([5, 10])`` denotes the
 number of points (or events) in between time ``5`` and ``10`` inclusive. The
 number of points in this interval is a random variable. If ``N`` is a Poisson
-process with conditional intensity (or rate) equals to ``1``, then ``N[5, 10]``
+process with conditional intensity (or rate) equal to ``1``, then ``N[5, 10]``
 is distributed according to a Poisson distribution with parameter ``\lambda = 5``.
 
 For convenience, we denote ``N(t) \equiv N[0, t)`` as the number of points since
-the start of time until ``t``, exclusive of ``t``. A TPP is _simple_, if only
-a single event can occur in any unit of time ``t``, that is, ``\Pr(N[t, t + \epsilon) > 2) = 0``. We can then define a differential operator for ``N``
-— ``dN`` — which describes the change in ``N(t)`` over an infinitesimal amount
-of time.
+the start of time until ``t``, exclusive of ``t``. A TPP is _simple_, if only a
+single event can occur in any unit of time ``t``, that is, ``\Pr(N[t, t +
+\epsilon) > 2) = 0``. We can then define a differential of ``N``, ``dN``, which
+describes the change in ``N(t)`` over an infinitesimal amount of time.
 
 ```math
 dN(t) = \begin{cases}
   1 \text{ , if } N[t, t + \epsilon] = 1 \\
-  0 \text{ , if } N[t, t + \epsilon] = 0
+  0 \text{ , if } N[t, t + \epsilon] = 0.
 \end{cases}
 ```
 
@@ -65,17 +65,18 @@ A TPP is marked if, in addition to the temporal support ``\mathbb{R}``, there is
 a mark space ``\mathcal{K}`` such that ``N`` is a random integer measure over
 ``\mathbb{R} \times \mathcal{K}``. Intuitively, for every point in the process
 there is a mark associated with it. If the mark space is discrete, we have
-a multivariate TPP. There are different ways to slice and dice a TPP, we will
-play with this fact throughout the tutorial.
+a multivariate TPP. There are different ways to interpret TPPs, and we will
+move between these interpretations throughout the tutorial.
 
 To make the connection between the JumpProcesses library and point process
-theory, we will use the PointProcess library, which offers a common interface
-for marked TPPs. Since TPP sampling is more efficient if we split any marked TPP
-into a sparsely connected multivariate TPP, we define `SciMLPointProcess` as
-a multivariate TPP such that each sub-component is itself a marked TPP on
-a continuous space. Therefore, we have that our structure includes a vector of
-sub-TPPs `jumps`, a vector of mark distributions `mark_dist` and the sparsely
-connected graph `g`.
+theory, we will compare against the
+[PointProcess.jl](https://github.com/gdalle/PointProcesses.jl) library, which
+offers a common interface for marked TPPs. Since TPP sampling is more efficient
+if we split any marked TPP into a sparsely connected multivariate TPP, we define
+`SciMLPointProcess` as a multivariate TPP such that each sub-component is itself
+a marked TPP on a continuous space. Therefore, we have that our structure
+includes a vector of sub-TPP `jumps`, a vector of mark distributions `mark_dist`
+and the sparsely connected graph `g`.
 
 ```@example tpp
 using JumpProcesses