consolidate documentation

JuliaPOMDP · Apr 6, 2024 · 785dde0 · 785dde0
1 parent c5a6fde
commit 785dde0
Show file tree

Hide file tree

Showing 7 changed files with 78 additions and 82 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -14,15 +14,9 @@ makedocs(
     modules = [CompressedBeliefMDPs],
     pages = [
         "CompressedBeliefMDPs.jl" => "index.md",
-        "Concepts and Architecture" => "concepts.md",
-        "Defining a Sampler" => "sampler_interface.md",
-        "Implemented Samplers" => "samplers.md",
-        "Defining a Compressor" => "compressor_interface.md",
-        "Implemented Compressors" => "compressors.md",
+        "Samplers" => "samplers.md",
+        "Compressors" => "compressors.md",
         "API Documentation" => "api.md"
-        # "Subsection" => [
-        #     ...
-        # ]
     ]
 )
 

diff --git a/docs/src/compressor_interface.md b/docs/src/compressor_interface.md
diff --git a/docs/src/compressors.md b/docs/src/compressors.md
@@ -1,4 +1,35 @@
-# Implemented Compressors
+# Compressors
+
+## Defining a Belief Compressor
+
+In this section, we outline the requirements and guidelines for defining a belief `Compressor`.
+
+### Interface
+
+The `Compressor` interface is extremely minimal. It only supports two methods: `fit!` and the associated [functor](https://docs.julialang.org/en/v1/manual/methods/#Function-like-objects). For example, if you wanted to implement your own `Compressor`, you could write something like this
+
+```julia
+struct MyCompressor <: Compressor
+    foo
+    bar
+end
+
+# functor definition
+function (c::MyCompressor)(beliefs)
+    # YOUR CODE HERE
+end
+
+function fit!(c::MyCompressor, beliefs)
+    # YOUR CODE HERE
+end
+```
+
+#### Implementation Tips
+* For robustness, both the functor and `fit!` should be able to handle `AbstractVector` and `AbstractMatrix` inputs. 
+* `fit!` is called only once after beliefs are sampled from the POMDP.
+* `CompressedBeliefSolver` will attempt to convert each belief state (often of type [`DiscreteBelief`](https://juliapomdp.github.io/POMDPs.jl/latest/POMDPTools/beliefs/#POMDPTools.BeliefUpdaters.DiscreteBelief)) into an `AbstractArray{Float64}` using [`convert_s`](https://juliapomdp.github.io/POMDPs.jl/latest/api/#POMDPs.convert_s). As a convenience, CompressedBeliefMDP implements conversions for commonly used belief types; however, if the POMDP has a custom belief state, then it is the users' responsibility to implement the appropriate conversion. See the source code for help. 
+
+## Implemented Compressors
 
 CompressedBeliefMDPs currently provides wrappers for the following compression types:
 - a principal component analysis (PCA) compressor,
@@ -9,32 +40,32 @@ CompressedBeliefMDPs currently provides wrappers for the following compression t
 - an autoencoder compressor
 - a variational auto-encoder (VAE) compressor
 
-## Principal Component Analysis (PCA)
+### Principal Component Analysis (PCA)
 ```@docs 
 PCACompressor
 ```
 
-## Kernel PCA
+### Kernel PCA
 ```@docs 
 KernelPCACompressor
 ```
 
-## Probabilistic PCA
+### Probabilistic PCA
 ```@docs 
 PPCACompressor
 ```
 
-## Factor Analysis
+### Factor Analysis
 ```@docs 
 FactorAnalysisCompressor
 ```
 
-## Isomap
+### Isomap
 ```@docs
 IsomapCompressor
 ```
 
-## Autoencoder
+### Autoencoder
 ```@docs
 AutoencoderCompressor
 ```

diff --git a/docs/src/concepts.md b/docs/src/concepts.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -64,7 +64,6 @@ rs = RolloutSimulator(max_steps=50)
 r = simulate(rs, pomdp, policy)
 ```
 
-
 ### Continuous Example
 
 This example demonstrates using CompressedBeliefMDP in a continuous setting with the `LightDark1D` POMDP. It combines particle filters for belief updating and Monte Carlo Tree Search (MCTS) as the solver. While compressing a 1D space is trivial toy problem, this architecture can be easily scaled to larger POMDPs with continuous state and action spaces.
@@ -113,4 +112,16 @@ rs = RolloutSimulator(max_steps=50)
 r = simulate(rs, pomdp, policy)
 ```
 
+## Concepts and Architecture
+
+CompressedBeliefMDPs.jl aims to implement a generalization of the [belief compression algorithm](https://papers.nips.cc/paper_files/paper/2002/hash/a11f9e533f28593768ebf87075ab34f2-Abstract.html) for solving large POMDPs. The algorithm has four steps:
+1. collect belief samples,
+2. compress the samples,
+3. create the compressed belief-state MDP,
+4. solve the MDP.
+
+Each step is handled by `Sampler`, `Compressor`, `CompressedBeliefMDP`, and `CompressedBeliefSolver` respectively.
+
+For more details, please see the rest of the documentation or the associated paper.
+
 
diff --git a/docs/src/sampler_interface.md b/docs/src/sampler_interface.md
diff --git a/docs/src/samplers.md b/docs/src/samplers.md
@@ -1,24 +1,43 @@
-# Implemented Sampler
+# Samplers
+
+## Defining a Sampler
+
+In this section, we outline the requirements and guidelines for defining a belief `Sampler`.
+
+### Interface
+
+The `Sampler` interface only has one method: the [functor](https://docs.julialang.org/en/v1/manual/methods/#Function-like-objects). For example, if you wanted to implement your own `Sampler`, you could write something like this
+
+```julia
+struct MySampler <: Compressor
+    foo
+    bar
+end
+
+# functor definition
+function (c::MySampler)(pomdp::POMDP)
+    # YOUR CODE HERE
+end
+```
+
+## Implemented Sampler
 
 CompressedBeliefMDPs provides the following generic belief samplers:
 - an exploratory belief expansion sampler
 - a [Policy](https://juliapomdp.github.io/POMDPs.jl/latest/api/#POMDPs.Policy) rollout sampler
 - an [ExplorationPolicy](https://juliapomdp.github.io/POMDPs.jl/latest/POMDPTools/policies/#Exploration-Policies) rollout sampler
 
-## Exploratory Belief Expansion
-
+### Exploratory Belief Expansion
 ```@docs 
 BeliefExpansionSampler
 ```
 
-## Policy Sampler
-
+### Policy Sampler
 ```@docs 
 PolicySampler
 ```
 
-## ExplorationPolicy Sampler
-
+### ExplorationPolicy Sampler
 ```@docs 
 ExplorationPolicySampler
 ```