Changing OPTIONS

The OPTIONS file is where we set the sampler options for DNest4. This page contains a description of each option, based on Brewer & Foreman-Mackey (2016, BF16).

A typical OPTIONS file looks like this

1	# Number of particles
5000	# new level interval
1000	# save interval
100	# number of steps each thread does independently before communication
0	# maximum number of levels
15	# Backtracking scale length (lambda)
100	# Strength of effect to force histogram to equal push (beta)
10	# Maximum number of saves (0 = infinite)

• The number of particles defines how many independent MCMC particles will explore the mixture of nested probability distributions. This can be a fairly small number in most problems: BF16 recommend 5, but you can usually get by with 1 or 2 particles, especially if your run is going to use multiple threads.

• new level interval sets the number of MCMC steps after which DNest4 creates a new level. In the example above, a new level is created when 5000 MCMC steps have given 5000 likelihood values above the current top level.

• save interval sets the number of steps after which a sample is saved in sample.txt. A good value is somewhere close to or smaller than the new level interval.

• threadSteps defines how many steps each thread does independently, before communicating with the other threads. BF16 recommend about 100 steps.

• maximum number of levels, as the name suggests, sets the maximum number of levels DNest4 will create. If this is set to 0, DNest4 will try to determine the maximum number of levels automatically. If this is set to 1, the code will only sample from the joint prior, which can be very useful to diagnose issues with the priors.

• The backtracking scale length is the scale length used in the mixture weights (see Brewer et al. (2011) for a more detailed explanation on the weighting scheme). This controls how much the particles will fall back to a lower level when the levels are being built. Higher values are safer, but increase the time taken to build new levels.

• The next option controls the strength of enforcing the target weighting (see Brewer et al. 2011). 100 is usually recommended, and there's little reason to ever use a different value.

• maximum number of saves will set the length of a DNest4 run. This is equal to the number of samples saved in the sample.txt file. If this is set to 0, the code will keep running indefinitely until it is manually terminated (with Crtl+c).