add get_flattened, etc.
add some notes/doctests