clarify "acceptance-walk" in dynesty guide

Dear maintainers, this is a partial attempt to make the dynesty guide's description of the "acceptance-walk" method easier to understand. The current version is

with this method, the length of each MCMC chain is predetermined. The specific length evolves during the run to yield an average of naccept accepted jumps during each chain. This method is well suited to parallelised applications, as each MCMC chain will run for the same amount of time. The value of naccept should be tuned based on the application. For example, one could run a single analysis with sample="act-walk" to estimate a viable number of accepted steps.

where, to me at least, the first two sentences seem directly contradictory - if it's "predetermined", how can it "evolve"? I only understood what was meant when checking the internal page https://git.ligo.org/lscsoft/bilby_pipe/-/wikis/O4-review/dynesty-updates : to my best understanding now, the "predetermined" was meant to refer to within a single iteration of the overall nested sampling loop. What do people think, does my edit catch that better? I'd also be happy for this MR to be discarded and for a true expert to make a different clarification.

Other aspects that could be good to address at the same time:

2. What exactly does the "average" refer to, just for the lifetime of a single-point single-iteration updating step, across all chains that are run in all updates of a specified live point, or the whole run?
3. Should the volumetric->differential proposal change (mentioned on the wiki) also be mentioned here in the docs?

added 3 commits

• bd2f5e65...c965f842 - 2 commits from branch lscsoft:master
• c950f62a - clarify "acceptance-walk" in dynesty guide

Compare with previous version

Hi @david-keitel thanks for this, I agree this change improves the clarity.

2. I think the answer is all of the above. If the acceptance rate varies slowly over the run then the first (the hardest condition) should be met. The distribution of the accepted number of jumps is Poisson(naccept), I'm not sure if that is too technical to add in here.

3. We have some text describing the different proposals, I agree we could have more. Maybe we should add to the volumetric bullet something like "This was the proposal distribution used for Bilby<2.0.0, we don't recommend this method as it generally leads to smaller accepted jumps than the differential evolution and struggles to explore multi-modal distributions."

added Documentation label

added 16 commits

• c950f62a...d0109542 - 15 commits from branch lscsoft:master
• 48e03f8c - clarify "acceptance-walk" in dynesty guide

Compare with previous version

changed milestone to %2.2.3

approved this merge request

approved this merge request

mentioned in merge request !1321 (merged)

marked this merge request as ready

resolved all threads

merged