From 785dde02f29cf3ccec9456b6f6ff32b61fb1e629 Mon Sep 17 00:00:00 2001 From: Logan Mondal Bhamidipaty <76822456+FlyingWorkshop@users.noreply.github.com> Date: Sat, 6 Apr 2024 13:29:09 -0700 Subject: [PATCH] consolidate documentation --- docs/make.jl | 10 ++----- docs/src/compressor_interface.md | 28 -------------------- docs/src/compressors.md | 45 +++++++++++++++++++++++++++----- docs/src/concepts.md | 11 -------- docs/src/index.md | 13 ++++++++- docs/src/sampler_interface.md | 20 -------------- docs/src/samplers.md | 33 ++++++++++++++++++----- 7 files changed, 78 insertions(+), 82 deletions(-) delete mode 100644 docs/src/compressor_interface.md delete mode 100644 docs/src/concepts.md delete mode 100644 docs/src/sampler_interface.md diff --git a/docs/make.jl b/docs/make.jl index 606dff3..1a2be4a 100644 --- 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 deleted file mode 100644 index b6bf3dd..0000000 --- a/docs/src/compressor_interface.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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. \ No newline at end of file diff --git a/docs/src/compressors.md b/docs/src/compressors.md index 1ea59b6..54f35d6 100644 --- 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 deleted file mode 100644 index cce5f3b..0000000 --- a/docs/src/concepts.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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. \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 0f13b18..e962386 100644 --- 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 deleted file mode 100644 index 8bbc5b9..0000000 --- a/docs/src/sampler_interface.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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 -``` - diff --git a/docs/src/samplers.md b/docs/src/samplers.md index 54e8eff..bbbe03c 100644 --- 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 ```