Merge pull request #102 from adolgert/docs/two-readers

Docs/two readers

Author: adolgert

docs/make.jl

@@ -73,51 +73,41 @@ makedocs(;
         canonical="https://adolgert.github.io/CompetingClocks.jl",
         assets=String[],
     ),
-    # develop.md
-    # importance_skills.md
-    # objects.md
-    # rules.md
-    # simple_board.md
-    # splitting.jl
-    # vas.md
     pages=[
         "Home" => "index.md",
         "Getting Started" => [
             "install.md",
+            "quickstart.md",
             "mainloop.md",
+            "choosing_sampler.md",
             "guide.md",
             "distributions.md"
         ],
         "User Guide" => [
-            "Background" => [
-                "distrib.md",
-                "background.md",
-                "GSMP" => "gsmp.md",
-                "samplers.md",
-                "hierarchical.md",
-            ],
-            "Simulation" => [
-                "samplingcontext.md",
-                "memory.md",
-                "commonrandom.md",
-            ],
-            "Statistics" => [
-                "hamiltonianmontecarlo.md",
-                "importance_skills.md",
-            ],
-            "Debugging" => [
-                "debugging.md"
-            ]
+            "integration-guide.md",
+            "interface.md",
+            "samplers.md",
+            "hierarchical.md",
+            "debugging.md",
+            "distrib.md",
+            "background.md",
+            "GSMP" => "gsmp.md",
+            "memory.md",
         ],
         "Examples" => [
             "Birth-death Process" => "constant_birth.md",
             "SIR Model" => "sir.md",
             "Reliability" => "reliability.md",
             "Gene Expression" => "gene_expression.md"
         ],
+        "Statistical Methods" => [
+            "commonrandom.md",
+            "importance_skills.md",
+            "hamiltonianmontecarlo.md",
+        ],
         "API Reference" => [
+            "samplingcontext.md",
             "contextinterface.md",
-            "interface.md",
             "reference.md",
             "algorithms.md"
         ]

docs/src/choosing_sampler.md

@@ -0,0 +1,67 @@
+# Choosing a Sampler
+
+How to make a sampler for events in CompetingClocks.jl.
+
+## Quick Reference
+
+| Name           | Distribution support | Best use cases                 |
+|----------------|----------------------|--------------------------------|
+| First-to-fire  | All                  | Fastest for simple simulation  |
+| Next Reaction  | All                  | Best for common random numbers |
+| First Reaction | All                  | Fastest for very few events    |
+| Direct         | Exponential-only     | Quicker likelihood calculation |
+| Petri          | All                  | Debug rare errors              |
+
+## High-level Interface
+
+Every event in a simulation has an identifying key which can be any immutable Julia
+type. A `Tuple` key type works fine, but it will be more performant to use a
+concrete type for the `KeyType`. The second argument to the `SamplerBuilder`
+is a type to use for time. Basic usage:
+```julia
+builder = SamplerBuilder(KeyType, Float64)
+sampler = SamplingContext(builder, rng)
+```
+The sampler, itself, takes an `AbstractRNG` as its second argument.
+
+Specify features for the sampler with keyword arguments to the `SamplerBuilder`.
+These features determine the type of the sampler.
+
+ * `step_likelihood=false`---Setting this to `true` let's you calculate the
+   the likelihood of the next event and time before firing it.
+ * `path_likelihood=false`---Set to true in order to calculate likelihood of a
+   whole trajectory at any point in the simulation. This is more efficient than
+   adding up steps in the likelihood along the way.
+ * `likelihood_cnt=1`---Applies when likelihoods are enabled and supports
+   importance sampling. Specifies how
+   many event distributions will be used to calculate a vector of likelihoods.
+ * `common_random=false`---For variance reduction, turn on recording of
+   random number usage during sampling.
+ * `start_time=0`---Sometimes you want a simulation to start at a different time.
+ * `debug=false`---Whether to print debug messages using the `Logging` package.
+ * `recording=false`---This will create a vector of every enable and disable
+   event for test and debug.
+
+## Hierarchical Samplers
+
+For spatial simulations or for chemical simulations that aren't well-mixed,
+it can help to split a sampler into multiple buckets so that each bucket can
+update its own list of what fires next. This package does this by adding
+sampler groups.
+
+A sampler group is
+
+ * A Symbol name for the sampler.
+ * An inclusion function from `(ClockKey, Distribution)` to `Bool` that decides
+   whether a given event belongs to this sampler.
+ * An optional `sampler_spec` to say what kind of sampler this group should use.
+
+```julia
+builder = SamplerBuilder(KeyType, Float64)
+add_group!(builder, :sparky => (x,d) -> x[1] == :recover, sampler_spec=(:nextreaction,))
+add_group!(builder, :forthright=>(x,d) -> x[1] == :infect)
+sampler = SamplingContext(builder, rng)
+```
+
+The resulting sampler will be hierarchical. For every event, it will choose the
+soonest time among the soonest times from all sampler groups.

docs/src/index.md

@@ -3,6 +3,7 @@ CurrentModule = CompetingClocks
 ```
 
 # CompetingClocks
+[![Coverage](https://codecov.io/gh/adolgert/CompetingClocks.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/adolgert/CompetingClocks.jl)
 
 Fast, composable samplers for stochastic discrete-event simulation.
 This package gives your simulation or simulation framework statistical features like common random
@@ -20,8 +21,16 @@ or to calculate the likelihood of a sample path for statistical estimation.
 
 ![CompetingClocks chooses the next transition but the simulation tracks state and changes to state.](assets/CompetingClocksTopLevel.svg)
 
-The background work for this library comes from [Continuous-time, discrete-event simulation from counting processes](https://arxiv.org/abs/1610.03939), by Andrew Dolgert, 2016.
+## Implementation Based on
 
+ * P. J. Haas, _Stochastic Petri Nets: Modelling, Stability, Simulation._ in Springer Series in Operations Research. New York, NY: Springer-Verlag New York, Inc, 2002. doi: 10.1007/b97265.
+ * D. F. Anderson and T. G. Kurtz, Stochastic Analysis of Biochemical Systems. Springer International Publishing AG Switzerland, 2015.
+ * [Continuous-time, discrete-event simulation from counting processes](https://arxiv.org/abs/1610.03939), by Andrew Dolgert, 2016.
+
+## Version History
+
+ - v0.2.0 (2025-12) - Likelihood calculation, variance reduction.
+ - v0.1.0 (2024-06) - Initial release of samplers.
 
 ## Usage
 
@@ -37,14 +46,16 @@ The library provides you with samplers. Each sampler has the same interface. Her
 
 Different samplers are specialized for sampling more quickly and accurately for different applications. For instance, some applications have very few events enabled at once, while some have many. Some applications use only exponentially-distributed events, while some have a mix of distribution types. Because continuous-time discrete event systems can fire many events, the literature has focused on reducing the number of CPU instructions required to sample each event, and this library reflects that focus.
 
-## Why Use This?
-
-If I make a quick simulation for myself, I sample distributions the moment an event is enabled and store the firing times in a [priority queue](https://juliacollections.github.io/DataStructures.jl/v0.12/priority-queue.html). When would I switch to this library?
-
- * I want to evaluate the effect of changing simulation parameters by comparing multiple runs with [common random numbers](https://en.wikipedia.org/wiki/Variance_reduction#Common_Random_Numbers_(CRN)).
+## When NOT to use Competing Clocks
 
- * I'm looking at rare events, so I want to use splitting techniques and [importance sampling](https://en.wikipedia.org/wiki/Importance_sampling).
+ * **Pure exponential distributions?** JumpProcesses.jl is a complete framework for this.
+ * **Need ODE coupling?** Again, it's easier to stay within SciML and JumpProcesses.jl.
+ * **Want high-level frameworks?** Try Agents.jl.
 
- * Performance matters (which it often doesn't), so I would like to try different samplers on my problem.
+CompetingClocks.jl is for:
 
- * I want to focus on developing and testing my *model* not my *simulation algorithm*; CompetingClocks is designed and tested with care to ensure correctness.
+ * Building a simulation framework with
+   * General distributions (Weibull, Gamma, etc.),
+   * Likelihood calculations or rare events, or
+   * Variance reduction.
+ * Advanced work in reliability models, disease models, queueing models.