code simplification and factoring.  basic goals are to:
 - avoid mutation
 - avoid global state
 - use meaningful names
 - avoid long functions
 - good python style

some progress made, but more to be done