1 #ifndef SAMPLER_H_
2 #define SAMPLER_H_
3 
4 #include <vector>
5 #include <string>
6 #include <set>
7 
8 namespace jags {
9 
10 struct RNG;
11 class StochasticNode;
12 class GraphView;
13 
14 /**
15  * @short Updates a set of stochastic nodes
16  *
17  * A sampler updates a set of stochastic nodes at each iteration.
18  * In addition, the sampler is responsible for updating the immediate
19  * deterministic descendants of the sampled nodes.
20  *
21  * The Sampler class is designed to be as abstract as possible to give
22  * maximum freedom in implementing samplers.  In practice, all the
23  * Samplers in the modules distributed with JAGS are implementations
24  * of one of two subclasses -- MutableSampler or ImmutableSampler --
25  * depending on whether the Sampler does or does not have a state that
26  * it must preserve between iterations.
27  */
28 class Sampler {
29     GraphView *_gv;
30 public:
31     /**
32      * Constructor
33      *
34      * @param gv GraphView providing a view of the sampling graph for
35      * the sampler. This should be dynamically allocated by the
36      * SamplerFactory: the Sampler takes ownership of the GraphView
37      * and deletes it when the destructor is called.
38      */
39     Sampler(GraphView *gv);
40     virtual ~Sampler();
41     /**
42      * Returns the vector of stochastic nodes sampled by the Sampler
43      */
44     std::vector<StochasticNode*> const &nodes() const;
45     /**
46      * Every sampler must update the vector of nodes and its immediate
47      * deterministic descendants using the update function.
48      *
49      * @param rng vector of Pseudo-random number generator functions.
50      */
51     virtual void update(std::vector<RNG *> const &rng) = 0;
52     /**
53      * When a sampler is constructed, it may be in adaptive mode, which
54      * allows it to adapt its behaviour for increased
55      * efficiency. However, a sampler in adaptive mode may not converge
56      * to the correct target distribution. This function turns off
57      * adaptive mode, so that valid samples can be collected from the
58      * sampler.
59      */
60     virtual void adaptOff() = 0;
61     /**
62      * The adaptOff function may be called at any time. Premature
63      * ending of adaptive mode may result in an extremely inefficient
64      * sampler.  Therefore the checkAdaptation function implements an
65      * efficiency test that returns true if it is safe to call the
66      * adaptOff function.  Samplers that have no adaptive mode should
67      * simply return true.
68      */
69     virtual bool checkAdaptation() const = 0;
70     /**
71      * Indicates whether the sampler has an adaptive mode.
72      */
73     virtual bool isAdaptive() const = 0;
74     /**
75      * Returns a name for the sampler which should describe the method
76      * it uses to update the nodes.
77      */
78     virtual std::string name() const = 0;
79 };
80 
81 } /* namespace jags */
82 
83 #endif /* SAMPLER_H_ */
84