new argument refactor: doc on adapt-engaged?

[Jiqiang Guo]

May I ask what will happen if I set engaged to 0?  I did not find the doc about it. 

And I did not find the doc about arguments gamma, delta, kappa.  If I did not miss the doc somewhere, I think they need to be doced or pointed to a reference. 

--

Jiqiang

[Michael Betancourt]

It's documented in both the LaTeX and the help output,

adapt
Warmup Adaptation
Valid subarguments: engaged, gamma, delta, kappa, t0

engaged=<boolean>
Adaptation engaged?
Valid values: [0, 1]
Defaults to 1

gamma=<double>
Adaptation regularization scale
Valid values: 0 < gamma
Defaults to 0.05

delta=<double>
Adaptation target acceptance statistic
Valid values: 0 < delta < 1
Defaults to 0.65

kappa=<double>
Adaptation relaxation exponent
Valid values: 0 < kappa
Defaults to 0.75

t0=<double>
Adaptation iteration offset
Valid values: 0 < t0
Defaults to 10

engaged=0 turns off adaptation (engaged=false without quotes might also work, depending on how the local system interprets booleans).

> --
> You received this message because you are subscribed to the Google Groups "stan development mailing list" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to stan-dev+u...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.

[Jiqiang Guo]

I knew the online help.  But it does not make much sense to me.  I did not know what adaptation it refers to as it seems not to be the warmup I know. 

$ ./dogs data=dogs.data.R sample adapt engaged=0

 method = sample (Default)

   sample

     num_samples = 1000 (Default)

     num_warmup = 1000 (Default)

     save_warmup = 0 (Default)

     thin = 1 (Default)

     adapt

       engaged = 0

       gamma = 0.050000000000000003 (Default)

       delta = 0.65000000000000002 (Default)

       kappa = 0.75 (Default)

       t0 = 10 (Default)

     algorithm = hmc (Default)

       hmc

         engine = nuts (Default)

           nuts

             max_depth = 10 (Default)

         metric = diag_e (Default)

         stepsize = 1 (Default)

         stepsize_jitter = 0 (Default)

 id = 0 (Default)

 data = dogs.data.R

 init = 2 (Default)

 random

   seed = 2583904630

 output

   sample = samples.csv (Default)

   append_sample = 0 (Default)

   diagnostic =  (Default)

   append_diagnostic = 0 (Default)

   refresh = 100 (Default)

Iteration:    1 / 2000 [  0%]  (Warmup)

Iteration:  100 / 2000 [  5%]  (Warmup)

Iteration:  200 / 2000 [ 10%]  (Warmup)

Iteration:  300 / 2000 [ 15%]  (Warmup)

Iteration:  400 / 2000 [ 20%]  (Warmup)

Iteration:  500 / 2000 [ 25%]  (Warmup)

Iteration:  600 / 2000 [ 30%]  (Warmup)

Iteration:  700 / 2000 [ 35%]  (Warmup)

Iteration:  800 / 2000 [ 40%]  (Warmup)

Iteration:  900 / 2000 [ 45%]  (Warmup)

Iteration: 1000 / 2000 [ 50%]  (Warmup)

Iteration: 1001 / 2000 [ 50%]  (Sampling)

[Michael Betancourt]

It refers to whatever adaption each sampler implements. For HMC, for example, this depends on the metric used. Basically we're assuming that dual averaging will be used (hence the parameters being defined here for all samplers) and that adaptation in general can either be on or off.

[Jiqiang Guo]

Thanks for the explanation.  But in my example, the first half iterations are still indicated as "Warmup."  So I still have not understood this argument.  

Iteration:    1 / 2000 [  0%]  (Warmup)

Iteration:  100 / 2000 [  5%]  (Warmup)

--

Jiqiang 

[Michael Betancourt]

Oh, I see what you mean.

Warmup and adaptation are two different things. A warmup period allows the Markov chain to converge to the target distribution -- this is always required of an MCMC method. In Stan we also take advantage of the warmup period to perform various adaptation routines -- these are not necessary but can be helpful for performance. Turning adaptation off leaves all algorithmic parameters at their nominal values and just tries to converge to the target distribution.