a few new functions and some refactors.  thorough comments.