Skip to content

Apply JuliaFormatter to fix code formatting #622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 31, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .JuliaFormatter.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
style = "sciml"
format_markdown = true
format_docstrings = true
1 change: 0 additions & 1 deletion LICENSE.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,3 @@ The StochasticDiffEq.jl package is licensed under the MIT "Expat" License:
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
> SOFTWARE.
>
66 changes: 33 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,77 +18,77 @@ using StochasticDiffEq
α=1
β=1
u₀=1/2
f(u,p,t) = α*u
g(u,p,t) = β*u
f(u, p, t) = α*u
g(u, p, t) = β*u
dt = 1//2^(4)
tspan = (0.0,1.0)
prob = SDEProblem(f,g,u₀,(0.0,1.0))
sol =solve(prob,SRIW1())
tspan = (0.0, 1.0)
prob = SDEProblem(f, g, u₀, (0.0, 1.0))
sol = solve(prob, SRIW1())
```

The options for `solve` are defined in the [common solver options page](https://diffeq.sciml.ai/stable/basics/common_solver_opts/) and are thoroughly explained in [the ODE tutorial](https://diffeq.sciml.ai/stable/tutorials/ode_example/).

That example uses the out-of-place syntax `f(u,p,t)`, while the inplace syntax (more efficient for systems of equations) is shown in the Lorenz example:

```julia
function lorenz(du,u,p,t)
du[1] = 10.0(u[2]-u[1])
du[2] = u[1]*(28.0-u[3]) - u[2]
du[3] = u[1]*u[2] - (8/3)*u[3]
function lorenz(du, u, p, t)
du[1] = 10.0(u[2]-u[1])
du[2] = u[1]*(28.0-u[3]) - u[2]
du[3] = u[1]*u[2] - (8/3)*u[3]
end

function σ_lorenz(du,u,p,t)
du[1] = 3.0
du[2] = 3.0
du[3] = 3.0
function σ_lorenz(du, u, p, t)
du[1] = 3.0
du[2] = 3.0
du[3] = 3.0
end

prob_sde_lorenz = SDEProblem(lorenz,σ_lorenz,[1.0,0.0,0.0],(0.0,10.0))
prob_sde_lorenz = SDEProblem(lorenz, σ_lorenz, [1.0, 0.0, 0.0], (0.0, 10.0))
sol = solve(prob_sde_lorenz)
plot(sol,vars=(1,2,3))
plot(sol, vars = (1, 2, 3))
```

The problems default to diagonal noise. Non-diagonal noise can be added by setting
the `noise_prototype`:

```julia
f = (du,u,p,t) -> du.=1.01u
g = function (du,u,p,t)
du[1,1] = 0.3u[1]
du[1,2] = 0.6u[1]
du[1,3] = 0.9u[1]
du[1,4] = 0.12u[2]
du[2,1] = 1.2u[1]
du[2,2] = 0.2u[2]
du[2,3] = 0.3u[2]
du[2,4] = 1.8u[2]
f = (du, u, p, t) -> du.=1.01u
g = function (du, u, p, t)
du[1, 1] = 0.3u[1]
du[1, 2] = 0.6u[1]
du[1, 3] = 0.9u[1]
du[1, 4] = 0.12u[2]
du[2, 1] = 1.2u[1]
du[2, 2] = 0.2u[2]
du[2, 3] = 0.3u[2]
du[2, 4] = 1.8u[2]
end
prob = SDEProblem(f,g,ones(2),(0.0,1.0),noise_rate_prototype=zeros(2,4))
prob = SDEProblem(f, g, ones(2), (0.0, 1.0), noise_rate_prototype = zeros(2, 4))
```

Colored noise can be set using [an `AbstractNoiseProcess`](https://diffeq.sciml.ai/stable/features/noise_process/). For example, we can set the underlying noise process to a `GeometricBrownianMotionProcess` via:

```julia
μ = 1.0
σ = 2.0
W = GeometricBrownianMotionProcess(μ,σ,0.0,1.0,1.0)
W = GeometricBrownianMotionProcess(μ, σ, 0.0, 1.0, 1.0)
# ...
# Define f,g,u0,tspan for a SDEProblem
# ...
prob = SDEProblem(f,g,u0,tspan,noise=W)
prob = SDEProblem(f, g, u0, tspan, noise = W)
```

StochasticDiffEq.jl also handles solving random ordinary differential equations. This is shown [in the RODE tutorial](https://diffeq.sciml.ai/stable/tutorials/rode_example/).

```julia
using StochasticDiffEq
function f(u,p,t,W)
2u*sin(W)
function f(u, p, t, W)
2u*sin(W)
end
u0 = 1.00
tspan = (0.0,5.0)
prob = RODEProblem(f,u0,tspan)
sol = solve(prob,RandomEM(),dt=1/100)
tspan = (0.0, 5.0)
prob = RODEProblem(f, u0, tspan)
sol = solve(prob, RandomEM(), dt = 1/100)
```

## Available Solvers
Expand Down
2 changes: 1 addition & 1 deletion docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@ makedocs(sitename = "StochasticDiffEq.jl",
pages = pages)

deploydocs(repo = "github.com/SciML/StochasticDiffEq.jl";
push_preview = true)
push_preview = true)
40 changes: 20 additions & 20 deletions docs/pages.jl
Original file line number Diff line number Diff line change
@@ -1,21 +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"
]
]
"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"
]
]
45 changes: 24 additions & 21 deletions docs/src/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,36 +43,39 @@ sol = solve(prob)
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
- **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

- **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
- **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
- 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.
See the individual solver pages for detailed information about each method's properties, when to use them, and their theoretical foundations.
91 changes: 52 additions & 39 deletions docs/src/jumpdiffusion/tau_leaping.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,97 +5,109 @@ Tau-leaping methods approximate jump processes by "leaping" over multiple potent
## Tau-Leaping Methods

### TauLeaping - Basic Tau-Leaping

```@docs
TauLeaping
```

### CaoTauLeaping - Cao's Tau-Leaping
### 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

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)

- μ(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

- 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

- 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

- Basic tau-leaping approximation
- Fixed tau approach
- Good for initial exploration

### CaoTauLeaping:
- Adaptive tau selection
- More sophisticated error control
- Better for production simulations

- 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

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)
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

- 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

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
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

Expand All @@ -107,7 +119,7 @@ function drift!(du, u, p, t)
# Continuous drift
end

function diffusion!(du, u, p, t)
function diffusion!(du, u, p, t)
# Continuous diffusion
end

Expand All @@ -124,5 +136,6 @@ 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"

- 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"
Loading
Loading