Add StochasticDiffEq docs to lib/StochasticDiffEq/docs

lib/StochasticDiffEq/docs/Project.toml

@@ -0,0 +1,40 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
+StochasticDiffEqCore = "19c5a474-6cd1-4a5f-be79-46dc34e54d7f"
+StochasticDiffEqHighOrder = "0520c28c-50fd-4d16-9c96-902fc80b3bab"
+StochasticDiffEqIIF = "ebf54054-c36b-4494-9aba-657e36df524f"
+StochasticDiffEqImplicit = "5080b986-4c76-4669-b5dc-373a41579d5b"
+StochasticDiffEqLeaping = "aefaaa88-39f2-4e89-b162-d61b7e8cc81b"
+StochasticDiffEqLowOrder = "d15fe365-ce7f-450a-828a-7985bd5b681b"
+StochasticDiffEqMilstein = "8c95a807-c8e7-4581-8419-890d001af53e"
+StochasticDiffEqROCK = "db241ea8-0e6b-4abc-8f2d-1adff2294fd9"
+StochasticDiffEqRODE = "49714585-0aa1-4f53-b1e6-a9b8c0d5e03f"
+StochasticDiffEqWeak = "af2a2fcd-1c36-4cbe-a6d0-5afda784a085"
+
+[sources]
+StochasticDiffEq = {path = ".."}
+StochasticDiffEqCore = {path = "../../StochasticDiffEqCore"}
+StochasticDiffEqHighOrder = {path = "../../StochasticDiffEqHighOrder"}
+StochasticDiffEqIIF = {path = "../../StochasticDiffEqIIF"}
+StochasticDiffEqImplicit = {path = "../../StochasticDiffEqImplicit"}
+StochasticDiffEqLeaping = {path = "../../StochasticDiffEqLeaping"}
+StochasticDiffEqLowOrder = {path = "../../StochasticDiffEqLowOrder"}
+StochasticDiffEqMilstein = {path = "../../StochasticDiffEqMilstein"}
+StochasticDiffEqROCK = {path = "../../StochasticDiffEqROCK"}
+StochasticDiffEqRODE = {path = "../../StochasticDiffEqRODE"}
+StochasticDiffEqWeak = {path = "../../StochasticDiffEqWeak"}
+
+[compat]
+Documenter = "1"
+StochasticDiffEq = "7"
+StochasticDiffEqCore = "2"
+StochasticDiffEqHighOrder = "2"
+StochasticDiffEqIIF = "2"
+StochasticDiffEqImplicit = "2"
+StochasticDiffEqLeaping = "2"
+StochasticDiffEqLowOrder = "2"
+StochasticDiffEqMilstein = "2"
+StochasticDiffEqROCK = "2"
+StochasticDiffEqRODE = "2"
+StochasticDiffEqWeak = "2"

lib/StochasticDiffEq/docs/make.jl

@@ -0,0 +1,35 @@
+using Documenter
+using StochasticDiffEq
+# StochasticDiffEq @reexports its solver subpackages, but the docstrings the @docs
+# blocks reference live in those subpackages, so they must be in `modules` for
+# Documenter to find them.
+using StochasticDiffEqCore, StochasticDiffEqHighOrder, StochasticDiffEqIIF,
+    StochasticDiffEqImplicit, StochasticDiffEqLeaping, StochasticDiffEqLowOrder,
+    StochasticDiffEqMilstein, StochasticDiffEqROCK, StochasticDiffEqRODE,
+    StochasticDiffEqWeak
+
+cp(joinpath(@__DIR__, "Project.toml"), joinpath(@__DIR__, "src", "assets", "Project.toml"),
+    force = true)
+
+# Keep pages.jl separate so DiffEqDocs.jl can include it when aggregating these docs.
+include("pages.jl")
+
+makedocs(
+    sitename = "StochasticDiffEq.jl",
+    authors = "Chris Rackauckas et al.",
+    clean = true,
+    doctest = false,
+    modules = [StochasticDiffEq, StochasticDiffEqCore, StochasticDiffEqHighOrder,
+        StochasticDiffEqIIF, StochasticDiffEqImplicit, StochasticDiffEqLeaping,
+        StochasticDiffEqLowOrder, StochasticDiffEqMilstein, StochasticDiffEqROCK,
+        StochasticDiffEqRODE, StochasticDiffEqWeak],
+    warnonly = [:docs_block, :missing_docs, :eval_block],
+    format = Documenter.HTML(
+        assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/StochasticDiffEq/stable/"
+    ),
+    pages = pages
+)
+
+# Note: these pages are aggregated into the unified SciML docs by DiffEqDocs.jl
+# (which copies docs/src + docs/pages.jl); deployment happens there.

lib/StochasticDiffEq/docs/pages.jl

@@ -0,0 +1,21 @@
+pages = [
+    "StochasticDiffEq.jl: SDE solvers and utilities" => "index.md",
+    "Usage" => "usage.md",
+    "Nonstiff Solvers" => [
+        "nonstiff/basic_methods.md",
+        "nonstiff/sra_sri_methods.md",
+        "nonstiff/high_weak_order.md",
+        "nonstiff/commutative_noise.md",
+    ],
+    "Stiff Solvers" => [
+        "stiff/implicit_methods.md",
+        "stiff/split_step_methods.md",
+        "stiff/stabilized_methods.md",
+    ],
+    "Jump Diffusion" => [
+        "jumpdiffusion/tau_leaping.md",
+    ],
+    "Misc Solvers" => [
+        "misc.md",
+    ],
+]

lib/StochasticDiffEq/docs/src/assets/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"
+
+[compat]
+Documenter = "0.27, 1"

lib/StochasticDiffEq/docs/src/index.md

@@ -0,0 +1,81 @@
+# StochasticDiffEq.jl
+
+StochasticDiffEq.jl is a component package in the DifferentialEquations ecosystem for solving stochastic differential equations (SDEs) and random ordinary differential equations (RODEs). It provides a comprehensive suite of high-performance numerical methods for stochastic problems.
+
+## Installation
+
+To install StochasticDiffEq.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("StochasticDiffEq")
+```
+
+## Quick Start
+
+Here's a simple example of solving an SDE:
+
+```julia
+using StochasticDiffEq
+
+# Define the drift and diffusion functions
+function drift!(du, u, p, t)
+    du[1] = 1.01 * u[1]
+end
+
+function diffusion!(du, u, p, t)
+    du[1] = 0.87 * u[1]
+end
+
+# Initial condition and time span
+u0 = [0.5]
+tspan = (0.0, 1.0)
+
+# Define the SDE problem
+prob = SDEProblem(drift!, diffusion!, u0, tspan)
+
+# Solve using the default algorithm
+sol = solve(prob)
+```
+
+## Solver Categories
+
+StochasticDiffEq.jl provides several categories of solvers optimized for different types of problems:
+
+### Nonstiff Solvers
+
+  - **Basic Methods**: Euler-Maruyama, Heun methods
+  - **SRA/SRI Methods**: High-order adaptive methods (SOSRI, SOSRA)
+  - **High Weak Order**: Methods optimized for weak convergence (DRI1)
+  - **Commutative Noise**: Specialized methods for commuting noise terms
+
+### Stiff Solvers
+
+  - **Implicit Methods**: Drift-implicit methods for stiff problems
+  - **Split-Step Methods**: Methods handling stiffness in diffusion
+  - **Stabilized Methods**: SROCK-type methods for parabolic PDEs
+
+### Jump-Diffusion
+
+  - **Tau-Leaping**: Methods for jump-diffusion processes
+
+## Recommended Methods
+
+For most users, we recommend starting with these methods:
+
+  - **General Purpose**: `SOSRI()` - Excellent for diagonal/scalar Itô SDEs
+  - **Additive Noise**: `SOSRA()` - Optimal for problems with additive noise
+  - **Stiff Problems**: `SKenCarp()` - Best for stiff problems with additive noise
+  - **Commutative Noise**: `RKMilCommute()` - For multi-dimensional commutative noise
+  - **High Efficiency**: `EM()` - When computational speed is most important
+
+## Advanced Features
+
+  - Adaptive time stepping with sophisticated error control
+  - Support for all noise types (diagonal, non-diagonal, additive, scalar)
+  - Both Itô and Stratonovich interpretations
+  - Integration with the broader DifferentialEquations.jl ecosystem
+  - GPU compatibility for high-performance computing
+  - Extensive callback and event handling capabilities
+
+See the individual solver pages for detailed information about each method's properties, when to use them, and their theoretical foundations.

lib/StochasticDiffEq/docs/src/jumpdiffusion/tau_leaping.md

@@ -0,0 +1,141 @@
+# Tau-Leaping Methods for Jump-Diffusion
+
+Tau-leaping methods approximate jump processes by "leaping" over multiple potential jump events in a single time step. These methods are essential for efficiently simulating systems with jump-diffusion processes.
+
+## Tau-Leaping Methods
+
+### TauLeaping - Basic Tau-Leaping
+
+```@docs
+TauLeaping
+```
+
+### CaoTauLeaping - Cao's Tau-Leaping
+
+```@docs
+CaoTauLeaping
+```
+
+## Understanding Jump-Diffusion Processes
+
+Jump-diffusion processes combine:
+
+ 1. **Continuous diffusion**: Standard Brownian motion terms
+ 2. **Jump processes**: Discontinuous jumps at random times
+
+General form:
+
+```
+dX = μ(X,t)dt + σ(X,t)dW + ∫ h(X-,z)Ñ(dt,dz)
+```
+
+Where:
+
+  - μ(X,t)dt: Drift term
+  - σ(X,t)dW: Diffusion term
+  - Ñ(dt,dz): Compensated random measure (jumps)
+
+## When to Use Tau-Leaping
+
+**Appropriate for:**
+
+  - Systems with many small jumps
+  - When exact jump simulation is computationally prohibitive
+  - Chemical reaction networks
+  - Population models with birth-death processes
+  - Financial models with rare events
+
+**Not appropriate for:**
+
+  - Systems dominated by large, infrequent jumps
+  - When exact jump timing is critical
+  - Small systems where exact methods are feasible
+
+## Method Characteristics
+
+### TauLeaping:
+
+  - Basic tau-leaping approximation
+  - Fixed tau approach
+  - Good for initial exploration
+
+### CaoTauLeaping:
+
+  - Adaptive tau selection
+  - More sophisticated error control
+  - Better for production simulations
+
+## Configuration
+
+Tau-leaping methods require:
+
+ 1. **Jump rate functions**: λ(X,t) for each reaction/jump type
+ 2. **Jump effects**: How state changes with each jump
+ 3. **Tau selection**: Time step size strategy
+
+```julia
+# Basic setup
+prob = JumpProblem(base_problem, aggregator, jumps...)
+sol = solve(prob, TauLeaping())
+
+# With adaptive tau
+sol = solve(prob, CaoTauLeaping(), tau_tol = 0.01)
+```
+
+## Accuracy Considerations
+
+**Tau-leaping approximation quality depends on:**
+
+  - Jump frequency vs. tau size
+  - State change magnitude per jump
+  - System stiffness
+  - Error tolerance requirements
+
+**Rule of thumb:** Tau should be small enough that jump rates don't change significantly over [t, t+tau].
+
+## Alternative Approaches
+
+**If tau-leaping is inadequate:**
+
+ 1. **Exact methods**: Gillespie algorithm for small systems
+ 2. **Hybrid methods**: Combine exact and approximate regions
+ 3. **Moment closure**: For statistical properties only
+ 4. **Piecewise deterministic**: For systems with rare jumps
+
+## Performance Tips
+
+ 1. **Vectorize jump computations** when possible
+ 2. **Use sparse representations** for large systems
+ 3. **Tune tau carefully** - too large gives poor accuracy, too small is inefficient
+ 4. **Monitor jump frequencies** to validate approximation
+
+## Integration with DifferentialEquations.jl
+
+```julia
+using DifferentialEquations, StochasticDiffEq
+
+# Define base SDE
+function drift!(du, u, p, t)
+    # Continuous drift
+end
+
+function diffusion!(du, u, p, t)
+    # Continuous diffusion
+end
+
+# Define jumps
+jump1 = ConstantRateJump(rate1, affect1!)
+jump2 = VariableRateJump(rate2, affect2!)
+
+# Combine into jump-diffusion problem
+sde_prob = SDEProblem(drift!, diffusion!, u0, tspan)
+jump_prob = JumpProblem(sde_prob, Direct(), jump1, jump2)
+
+# Solve with tau-leaping
+sol = solve(jump_prob, TauLeaping())
+```
+
+## References
+
+  - Gillespie, D.T., "Approximate accelerated stochastic simulation of chemically reacting systems"
+  - Cao, Y., Gillespie, D.T., Petzold, L.R., "Efficient step size selection for the tau-leaping method"