What is the difference between alphaTarget and alphaMin?

Question

The description from the API is confusing. I expect target to be the value where the simulation stops ticking, but what target does is not defined in the API. Also alpha itself is not defined in the API but I found that on another website: https://roshansanthosh.wordpress.com/2016/09/25/forces-in-d3-js-v4/

An important aspect of simulations is alpha. alpha is a number between 0 and 1 and defines how far the simulation has progressed. When a simulation starts alpha is set to 1 and this value slowly decays, based on the alphaDecay rate, until it reaches the alphaTarget of the simulation. Once the alpha value is less than the alphaTarget, the simulation comes to a halt. The alphaTarget by default is set to 0.1

Now for the official API:

simulation.alphaMin([min])

If min is specified, sets the minimum alpha to the specified number in the range [0,1] and returns this simulation. If min is not specified, returns the current minimum alpha value, which defaults to 0.001. The simulation’s internal timer stops when the current alpha is less than the minimum alpha. The default alpha decay rate of ~0.0228 corresponds to 300 iterations.

simulation.alphaTarget([target])

If target is specified, sets the current target alpha to the specified number in the range [0,1] and returns this simulation. If target is not specified, returns the current target alpha value, which defaults to 0.

Answer 1

Concepts like alphaMin and alphaTarget are, indeed, quite hard to understand, and on top of that they are not very well explained in the docs.

You got it almost right in your comment:

OK I figured most of it out by just logging alpha to the console: alphaMin sets the alpha-level where the simulation will stop running (tick-events stop happening), alphaTarget redefines where the alpha will eventually end up (the asymptote), so instead of slowly going to 0 it will slowly go to 0.2. Lord only knows what the purpose of the alphaTarget is. (emphasis mine)

So, the missing part for you to understand these concepts is to understand "what [is] the purpose of the alphaTarget". And that's quite simple:

As you know, alphaMin sets the minimum alpha, which will be responsible for stopping the simulation when the current alpha falls below it. So, if we set the alphaTarget to a value above the alphaMin, the simulation never stops.

For instance, have a look at this forked bl.ocks, where I set the alphaTarget to 0.8: https://bl.ocks.org/GerardoFurtado/91368069a381009d30468aa9774c0de3/e58316dfdb05b68b02e5692c26b360c990da0383

As you can see, that simulation will run forever.

Of course, even with a high alphaTarget value the simulation will stop if the alphaMin is higher, but in a quite unpleasant and abrupt way. For instance, alphaMin = 0.991 and alphaTarget = 0.99: https://blockbuilder.org/GerardoFurtado/72961f5e63eb75b6202d9e24dc25e67b