modified the debugging and context to make documentation more complete so it's a good outcome

Author: adolgert

docs/src/commonrandom.jl

@@ -15,11 +15,10 @@
 
 # CompetingClocks implements common random numbers by recording the state of the random number generator every time a clock is enabled. There are other ways to do this, but this one works with the [CombinedNextReaction](@ref) and [FirstToFire](@ref) samplers. The workflow you would use looks notionally like:
 
-#   1. Create a sampler.
-#   2. Wrap it in a [CommonRandom](@ref).
-#   3. Run a lot of simulations in order to explore and record all possible clock states. Run `reset!(recorder)` after each simulation.
-#   4. For every parameter set to try, run it the same way, using `reset!` after each run.
-#   5. Compare outcomes.
+#   1. Create a sampler with the keyword argument `common_random=true`.
+#   2. Run a lot of simulations in order to explore and record all possible clock states. Run `reset!(recorder)` after each simulation.
+#   3. For every parameter set to try, run it the same way, using `reset!` after each run.
+#   4. Compare outcomes.
 
 # Because the `CommonRandom` stores the state of the random number generator at each step, it works best with random number generators that have small state, such as Xoshiro on a linear congruential generator (LCG).
 

docs/src/importance_skills.md

@@ -14,7 +14,15 @@ When you apply importance sampling in simulation, the workflow feels like this:
 
 The main problem is that too large of bias on distributions can lead to mathematical underflow in calculation of the weights. Intuitively, a stochastic simulation can have a lot of individual sampled events, and each event's probability multiplies to get the probability of a path of samples in a trajectory. If those samples are repeatedly biased, they can cause numbers that are too small to represent.
 ```math
-w = \frac{L(\lambda_{\mbox{target}})}{L(\lambda_{\mbox{proposal}})} = \left(\frac{\lambda_{\mbox{target}}}{\lambda_{\mbox{proposal}}}\right)^N e^{-(\lambda_{\mbox{target}} - \lambda_{\mbox{proposal}})T}
+w = \frac{L(\lambda_{\mbox{target}})}{L(\lambda_{\mbox{proposal}})}
+```
+
+```math
+ = \left(\frac{\lambda_{\mbox{target}}}{\lambda_{\mbox{proposal}}}\right)^N
+```
+
+```math
+e^{-(\lambda_{\mbox{target}} - \lambda_{\mbox{proposal}})T}
 ```
 What you'll see in practice is that the initial simulation, under $p$, works fine, that a small change in a distribution's parameters still works fine, and then the importance-weighted estimates fall off a cliff and show values like $10^{-73}$.