comments and docstrings in simulator.py