Work on docstrings and restructure the file tree

Author: guilgautier

src/PartialRejectionSampling.jl

@@ -52,26 +52,26 @@ export generate_sample,
 # Code inclusions
 
 include("common.jl")
-
 include("utils.jl")
-include("window.jl")
 
-# sampling
-include("dominated_cftp.jl")
+include(joinpath("spatial", "window.jl"))
+include(joinpath("graph", "window.jl"))
+
 include("grid_prs.jl")
 
-# Spatial point processes
-include("poisson.jl")
-include("strauss.jl")
-include("hard_core_spatial.jl")
+## Spatial point processes
+include(joinpath("spatial", "dominated_cftp.jl"))
+include(joinpath("spatial", "poisson.jl"))
+include(joinpath("spatial", "hard_core.jl"))
+include(joinpath("spatial", "strauss.jl"))
 
-# Graph point processes
-include("ising.jl")
-include("hard_core_graph.jl")
-include("rooted_spanning_forest.jl")
-include("sink_free_graph.jl")
+## Graph point processes
+include(joinpath("graph", "ising.jl"))
+include(joinpath("graph", "hard_core.jl"))
+include(joinpath("graph", "rooted_spanning_forest.jl"))
+include(joinpath("graph", "sink_free_graph.jl"))
 
 # Misc
-include("pattern_free_string.jl")
+include(joinpath("misc", "pattern_free_string.jl"))
 
 end

src/common.jl

@@ -11,6 +11,13 @@ The type `T` corresponds to the elements' type of the point process (vectors, gr
 abstract type AbstractPointProcess{T} end
 Base.eltype(pp::AbstractPointProcess{T}) where {T} = T
 
+@doc raw"""
+    AbstractGraphPointProcess{T<:Vector{Float64}} <: AbstractPointProcess{T}
+
+Abstract type encoding point processes defined on graphs
+"""
+abstract type AbstractGraphPointProcess{T} <: AbstractPointProcess{T} end
+
 @doc raw"""
     AbstractSpatialPointProcess{T<:Vector{Float64}} <: AbstractPointProcess{T}
 
@@ -21,28 +28,48 @@ Concrete instances must have a `window` field of type [`PRS.AbstractSpatialWindo
 abstract type AbstractSpatialPointProcess{T<:Vector{Float64}} <: AbstractPointProcess{T} end
 
 """
-    window(pp::AbstractSpatialPointProcess) = pp.window
+    window(pp::AbstractSpatialPointProcess)::AbstractSpatialWindow = pp.window
 """
-window(pp::AbstractSpatialPointProcess) = pp.window
+function window(pp::AbstractSpatialPointProcess)::AbstractSpatialWindow
+    return pp.window
+end
 
 """
     dimension(pp::AbstractSpatialPointProcess) = dimension(window(pp))
 
-**See also**
-    - [`window`](@ref)
+**See also** [`window`](@ref)
 """
 dimension(pp::AbstractSpatialPointProcess) = dimension(window(pp))
 
-abstract type AbstractGraphPointProcess{T} <: AbstractPointProcess{T} end
+"""
+Abstract type representing a window
 
-# Default methods
+**See also**
 
+- [`PRS.AbstractDiscreteWindow`](@ref)
+- [`PRS.AbstractSpatialWindow`](@ref)
 """
-Default exact sampling method
+abstract type AbstractWindow end
+
+@doc raw"""
+    AbstractSpatialWindow{T<:Float64} <: AbstractWindow{T}
+
+Abstract type representing a spatial window ``\subseteq \mathbb{R}^d``
+
+**See also**
+
+- [`PRS.AbstractRectangleWindow`](@ref)
+    - [`PRS.RectangleWindow`](@ref)
+    - [`PRS.SquareWindow`](@ref)
+- [`PRS.BallWindow`](@ref)
 """
-function generate_sample end
+abstract type AbstractSpatialWindow{T<:Float64} <: AbstractWindow end
 
 """
-Default exact sampling method using Partial Rejection Sampling (PRS, [GuJeLi19](@cite))
+Abstract type representing a window on a discrete state space
+
+**See also**
+
+- [`PRS.GraphNode`](@ref)
 """
-function generate_sample_prs end
+abstract type AbstractDiscreteWindow{T} <: AbstractWindow end

src/hard_core_graph.jl renamed to src/graph/hard_core.jl

@@ -1,24 +1,23 @@
 @doc raw"""
     HardCoreGraph{T<:Integer} <: AbstractGraphPointProcess{T}
 
-Point process defined on the vertices of a `graph` ``=(V, E)``, and parametrized by β ``\geq 0``, with joint density
+Concrete type representing a point process on the vertices of a `graph` ``=(V, E)`` parametrized by `\beta ≥ 0` which characterizes the distribution on the [independent sets](https://en.wikipedia.org/wiki/Independent_set_(graph_theory)) of `graph`, where each vertex is present with marginal probability ``\frac{\beta}{1+\beta}``.
+
+In other words, it can also be viewed as the product distribution ``\operatorname{Bernoulli}(\frac{\beta}{1+\beta})^{\otimes |V|}`` on the vertices of `graph` conditioned on forming an independent set,
 
 ```math
     \mathbb{P}\!\left[ \mathcal{X} = X \right]
     \propto
     \prod_{x\in X}
         \frac{\beta}{1+\beta}
-     1_{X \text{forms an independent set}}
+     1_{X \text{forms an independent set}}.
 ```
 
-It can be viewed as a distribution on the [independent sets](https://en.wikipedia.org/wiki/Independent_set_(graph_theory)) of `graph`, where each vertex is present with marginal probability ``\frac{\beta}{1+\beta}``.
-In other words, it can also be viewed as the product distribution ``\operatorname{Bernoulli}(\frac{\beta}{1+\beta})^{\otimes |V|}`` on the vertices of `graph` conditioned on forming an independent set.
-
 **See also**
 
 - Section 7.2 of [GuJeLi19](@cite)
 - Example 4.1 of [MoKr20](@ref)
-- [`PRS.HardCoreSpatial`](@ref)
+- [`PRS.HardCorePointProcess`](@ref), the spatial counterpart of [`PRS.HardCoreGraph`](@ref)
 """
 struct HardCoreGraph{T<:Integer} <: AbstractGraphPointProcess{T}
     "Graph"
@@ -32,7 +31,7 @@ end
         β::Real
     ) where {T<:Integer}
 
-Construct a [`HardCoreGraph`](@ref)
+Construct a [`HardCoreGraph`](@ref).
 """
 function HardCoreGraph(
     graph::LG.SimpleGraph{T},
@@ -44,11 +43,28 @@ end
 
 # Sampling
 
+"""
+    generate_sample(
+        pp::HardCoreGraph{T};
+        rng=-1
+    )::Vector{T} where {T}
+
+Generate an exact sample from the [`PRS.SinkFreeGraph`](@ref).
+
+Default sampler is [`PRS.generate_sample_prs`](@ref).
+"""
+function generate_sample(
+    pp::HardCoreGraph{T};
+    rng=-1
+)::Vector{T} where {T}
+    return generate_sample_prs(pp; rng=rng)
+end
+
 ## Partial Rejeciton Sampling (PRS)
 
 """
     generate_sample_prs(
-        hcg::HardCoreGraph{T};
+        pp::HardCoreGraph{T};
         rng=-1
     )::Vector{T} where {T}
 
@@ -59,15 +75,15 @@ Sample from [`PRS.HardCoreGraph`](@ref) using Partial Rejection Sampling (PRS),
 - Example 4.1 of [MoKr20](@ref)
 """
 function generate_sample_prs(
-    hcg::HardCoreGraph{T};
+    pp::HardCoreGraph{T};
     rng=-1
 )::Vector{T} where {T}
 
-    proba = hcg.β / (one(hcg.β) + hcg.β)
+    proba = pp.β / (one(pp.β) + pp.β)
 
     rng = getRNG(rng)
-    adj = LG.adjacency_matrix(hcg.graph)
-    occupied = randsubseq(rng, LG.vertices(hcg.graph), proba)
+    adj = LG.adjacency_matrix(pp.graph)
+    occupied = randsubseq(rng, LG.vertices(pp.graph), proba)
     while true
         # Check if occupied vertices form an independent set
         sub_graph = LG.SimpleGraph(adj[occupied, occupied])
@@ -80,7 +96,7 @@ function generate_sample_prs(
             else  # Construct the resampling set of vertices
                 union!(resample, occupied[cc])
                 for v in cc
-                    union!(resample, LG.neighbors(hcg.graph, occupied[v]))
+                    union!(resample, LG.neighbors(pp.graph, occupied[v]))
                 end
             end
         end

src/ising.jl renamed to src/graph/ising.jl

@@ -1,17 +1,18 @@
 @doc raw"""
     Ising{T<:Int} <: AbstractGraphPointProcess{T}
 
-[Ising](https://en.wikipedia.org/wiki/Ising_model) is a point process defined on the vertices of `graph` ``=(V, E)`` with joint density proportional to
+The [Ising model](https://en.wikipedia.org/wiki/Ising_model) characterizes a point process defined on the vertices of graph ``(V, E)`` with joint density proportional to
 
 ```math
     \mathbb{P}\!\left[ \mathcal{X}=X \right]
+    \propto
     \prod_{i \in V}
         \exp(h_i x_i)
-    \prod_{\{i, j\} \subseteq E}
+    \prod_{\{i, j\} \in E}
         \exp(J x_i x_j)
 ```
 
-where ``(h_i)_{V}`` are called magnetization paremeters and ``J`` the interaction coefficient (``J \pm 0`` characterizes ferro/antiferro magnetic interactions).
+where ``(h_i)_{V}`` are called magnetization paremeters and ``J`` the interaction coefficient (``J \gtreqless 0`` characterizes ferro/antiferro magnetic interactions).
 """
 struct Ising{T<:Int} <: AbstractGraphPointProcess{T}
     graph::LG.SimpleGraph{T}
@@ -96,7 +97,51 @@ function Ising(
     return Ising{T}(graph, float.(h), J)
 end
 
+@doc raw"""
+    generate_sample_prs(pp::Ising; rng=-1)
+
+Generate an exact sample form `pp` using Partial Rejection Sampling (PRS), see Section 4.2 of [GuJeLi19](@cite)
+
+Default sampler is [`PRS.generate_sample_grid_prs`](@ref)
+
+**See also**
+
+- [FeViYi19](@cite)
+- [FeGuYi19](@cite) [`PRS.generate_sample_gibbs_perfect`](@ref)
+"""
+generate_sample_prs(pp::Ising; rng=-1) = generate_sample_grid_prs(pp; rng=rng)
+
+@doc raw"""
+    generate_sample(
+        pp::Ising{T},
+        idx::T;
+        rng=-1
+    )::T where {T<:Int}
+
+Generate an exact sample from the marginal distribution of state ``i=`` `idx` of `pp`.
+
+More specifically,
+
+```math
+    x_i
+        \sim
+        \operatorname{Bernoulli}_{-1, 1}
+            (\sigma(h_i)),
+```
+
+where ``\sigma`` denotes the [`PRS.sigmoid`](@ref) function.
+"""
+function generate_sample(
+    pp::Ising{T},
+    idx::T;
+    rng=-1
+)::T where {T<:Int}
+    rng = getRNG(rng)
+    hᵢ = pp.h isa Real ? pp.h : pp.h[idx]
+    return rand(rng) < sigmoid(hᵢ) ? one(T) : -one(T)
+end
+
 ## Sampling
 
-include("ising/ising_sampling_gibbs_perfect.jl")
-include("ising/ising_sampling_grid_prs.jl")
+include("ising_sampling_gibbs_perfect.jl")
+include("ising_sampling_grid_prs.jl")

src/ising/ising_sampling_gibbs_perfect.jl renamed to src/graph/ising_sampling_gibbs_perfect.jl

@@ -20,7 +20,7 @@ function generate_sample_gibbs_perfect(
 
     while !isempty(R)
         i = rand(rng, R)
-        if bayes_filter(ising, state, i, R; rng=-1)
+        if bayes_filter(ising, state, i, R; rng=rng)
             generate_sample_conditional!(state, i, ising; rng=rng)
             delete!(R, i)
         else
@@ -39,15 +39,7 @@ end
         rng=-1
     ) where {T<:Int}
 
-Generate an exact sample from the marginal distribution of each states of the [`Ising`](@ref) model `ising` at the prescribed `indices`
-
-```math
-    x_i
-        \sim
-        \operatorname{Bernoulli}_{-1, 1}
-            (\sigma(h_i)),
-```
-where ``\sigma`` denotes the [`sigmoid`](@ref) function.
+Generate an exact sample from the marginal distribution of each states of the [`Ising`](@ref) model `ising` at the prescribed `indices`.
 """
 function generate_sample!(
     state::AbstractVector{T},