diff --git a/docs/make.jl b/docs/make.jl index 0f91422..818fe13 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -14,7 +14,10 @@ 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", "API Documentation" => "api.md" # "Subsection" => [ diff --git a/docs/src/compressor_interface.md b/docs/src/compressor_interface.md new file mode 100644 index 0000000..b6bf3dd --- /dev/null +++ b/docs/src/compressor_interface.md @@ -0,0 +1,28 @@ +# 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/concepts.md b/docs/src/concepts.md new file mode 100644 index 0000000..10ae36f --- /dev/null +++ b/docs/src/concepts.md @@ -0,0 +1,11 @@ +# 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](../../paper.md). \ No newline at end of file diff --git a/docs/src/sampler_interface.md b/docs/src/sampler_interface.md new file mode 100644 index 0000000..8bbc5b9 --- /dev/null +++ b/docs/src/sampler_interface.md @@ -0,0 +1,20 @@ +# 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 +``` +