update source selection algo + improve documentation