Skip to content

Commit

Permalink
Add a model argument to getparams and setparams!! functions (#150)
Browse files Browse the repository at this point in the history
* add optional argument of logdensity_function

* version bump

* apply suggestions

* add some default implementations

* Apply suggestions from code review

Co-authored-by: Tor Erlend Fjelde <tor.erlend95@gmail.com>

* Update src/AbstractMCMC.jl

Co-authored-by: Tor Erlend Fjelde <tor.erlend95@gmail.com>

* Update Project.toml

* add some documentation improvement

* improve added doc

---------

Co-authored-by: Tor Erlend Fjelde <tor.erlend95@gmail.com>
  • Loading branch information
sunxd3 and torfjelde authored Oct 27, 2024
1 parent 467b076 commit bc760b0
Show file tree
Hide file tree
Showing 3 changed files with 23 additions and 6 deletions.
2 changes: 1 addition & 1 deletion Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ uuid = "80f14c24-f653-4e6a-9b94-39d6b0f70001"
keywords = ["markov chain monte carlo", "probabilistic programming"]
license = "MIT"
desc = "A lightweight interface for common MCMC methods."
version = "5.5.0"
version = "5.6.0"

[deps]
BangBang = "198e06fe-97b7-11e9-32a5-e1d131e6ad66"
Expand Down
8 changes: 7 additions & 1 deletion docs/src/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,13 @@ To make it a bit easier to interact with some arbitrary sampler state, we encour
AbstractMCMC.getparams
AbstractMCMC.setparams!!
```
These methods can also be useful for implementing samplers which wraps some inner samplers, e.g. a mixture of samplers.
`getparams` and `setparams!!` provide a generic interface for interacting with the parameters of a sampler's state, regardless of how that state is represented internally.

This allows generic code to be written that works with any sampler implementing this interface. For example, a generic ensemble sampler could use `getparams` to extract the parameters from each of its component samplers' states, and `setparams!!` to initialize each component sampler with a different set of parameters.

The optional `model` argument to these functions allows sampler implementations to customize their behavior based on the model being used. For example, some samplers may need to evaluate the log density at new parameter values when setting parameters, which requires access to the model. If access to `model` is not needed, the sampler only needs to implement the version without the `model` argument - the default implementations will then call those methods directly.

These methods are particularly useful for implementing samplers which wrap some inner samplers, such as a mixture of samplers. In the next section, we will see how `getparams` and `setparams!!` can be used to implement a `MixtureSampler`.

### Example: `MixtureSampler`

Expand Down
19 changes: 15 additions & 4 deletions src/AbstractMCMC.jl
Original file line number Diff line number Diff line change
Expand Up @@ -81,26 +81,37 @@ The `MCMCSerial` algorithm allows users to sample serially, with no thread or pr
struct MCMCSerial <: AbstractMCMCEnsemble end

"""
getparams(state[; kwargs...])
getparams([model::AbstractModel, ]state)
Retrieve the values of parameters from the sampler's `state` as a `Vector{<:Real}`.
"""
function getparams end

function getparams(model::AbstractModel, state)
return getparams(state)
end

"""
setparams!!(state, params)
setparams!!([model::AbstractModel, ]state, params)
Set the values of parameters in the sampler's `state` from a `Vector{<:Real}`.
This function should follow the `BangBang` interface: mutate `state` in-place if possible and
return the mutated `state`. Otherwise, it should return a new `state` containing the updated parameters.
Although not enforced, it should hold that `setparams!!(state, getparams(state)) == state`. In another
word, the sampler should implement a consistent transformation between its internal representation
Although not enforced, it should hold that `setparams!!(state, getparams(state)) == state`. In other
words, the sampler should implement a consistent transformation between its internal representation
and the vector representation of the parameter values.
Sometimes, to maintain the consistency of the log density and parameter values, a `model`
should be provided. This is useful for samplers that need to evaluate the log density at the new parameter values.
"""
function setparams!! end

function setparams!!(model::AbstractModel, state, params)
return setparams!!(state, params)
end

include("samplingstats.jl")
include("logging.jl")
include("interface.jl")
Expand Down

2 comments on commit bc760b0

@sunxd3
Copy link
Member Author

@sunxd3 sunxd3 commented on bc760b0 Oct 28, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/118190

Tip: Release Notes

Did you know you can add release notes too? Just add markdown formatted text underneath the comment after the text
"Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the
release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add them here just re-invoke and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v5.6.0 -m "<description of version>" bc760b07aca320bfa2d28bd5b16e055a6a131f80
git push origin v5.6.0

Please sign in to comment.