Add initial parameters for multiple chains

Author: penelopeysm

usage/sampling-options/index.qmd

@@ -108,7 +108,7 @@ typeof(transitions)
 
 In Turing.jl, initial parameters for MCMC sampling can be specified using the `initial_params` keyword argument.
 
-For single-chain sampling, the AbstractMCMC interface generally expects that you provide a completely flattened vector of parameters.
+For **single-chain sampling**, the AbstractMCMC interface generally expects that you provide a completely flattened vector of parameters.
 
 ```{julia}
 chn = sample(demo_model(), MH(), 5; initial_params=[1.0, -5.0])
@@ -148,6 +148,17 @@ init_x, init_y = rand(LKJCholesky(3, 0.5)), rand(MvNormal(zeros(3), I))
 chn = sample(demo_complex(), MH(), 5; initial_params=(x=init_x, y=init_y));
 ```
 
+For **multiple-chain sampling**, the `initial_params` keyword argument should be a vector with length equal to the number of chains being sampled.
+Each element of this vector should be the initial parameters for the corresponding chain, as described above.
+Thus, for example, a vector of vectors, or a vector of `NamedTuple`s, can be used.
+If you want to use the same initial parameters for all chains, you can use `fill`:
+
+```{julia}
+initial_params = fill((x=1.0, y=-5.0), 3)
+chn = sample(demo_model(), MH(), MCMCThreads(), 5, 3; initial_params=initial_params)
+chn[:x][1,:], chn[:y][1,:]
+```
+
 ::: {.callout-important}
 ## Upcoming changes in Turing v0.41