optimize data structures, improve comments/docstrings