cleaned up core.py: added some documentation