new simulation functions and documentaiton