readme and comments changed
interface changes, utility functions