GISMOL Toolkit

A Unified Computing Framework Based on Constrained Object Hierarchies (COH)

The GISMOL Toolkit is an open‑source Python framework implementing Constrained Object Hierarchies (COH) — a unified, declarative computational model for describing intelligent systems, agents, environments, learning processes, constraint‑based reasoning, and simulation.

GISMOL provides:

• A minimal but powerful COH object model
• Dynamic methods, attributes, and constraints
• Daemons for event‑driven or continuous simulation
• Integrated NeuralModule wrappers (PyTorch‑based)
• Tools for reinforcement learning, environment modeling, and policy learning
• A high‑performance Simulator for COH execution
• Interactive demos and visualizations, including a Gridworld RL environment with live training metrics and policy visualization

---

🌟 Key Features

1. Constrained Object Hierarchies (COH) Core

• A universal representation of systems as nested, constrained objects.
• Identity, structural, and behavioral constraints.
• Dynamically attachable methods, neural modules, and daemons.

2. Agent‑Environment Simulation

• A fully event‑driven Simulator executing COH methods with time steps.
• Supports reactive agents, continuous daemons, and hybrid systems.

3. Reinforcement Learning Tools

• Integrated Q-learning utilities.
• Policy networks via PyTorch wrapped in NeuralModule.
• Potential‑based reward shaping.
• Step‑wise and episode‑wise hooks for logging metrics.

4. Rich Visualization System

• Built‑in Daemon‑based visualizers (Matplotlib).
• Heatmaps, policy arrows, agent trails, and constraint indicators.
• Option‑C Multi‑Panel Layout:
  • Left: Gridworld
  • Right: Policy Arrow Field
  • Bottom: Training Loss & Episode Returns
• Keyboard control (W/A/S/D, arrows, space) with auto‑repeat.

5. Fixed‑Canvas Export for GIF/MP4

• Consistent 1120×800 frame size.
• No frame mismatches.
• Export to GIF or MP4 (ffmpeg required for MP4).

6. Clean Repository Workflow

• .gitignore defaults for Python, virtualenvs, cache directories.
• Recommended Git LFS for large models, datasets, or media.

---

🧩 Installation

Prerequisites

• Python 3.10+
• PyTorch 2.x
• Matplotlib
• ImageIO (for rendering/export)
• ffmpeg (optional, MP4 export)

Install via pip

pip install -r requirements.txt

Editable install

pip install -e .

---

📂 Project Structure

gismol/
│
├── core/                     # COH core classes & engine
│   ├── coh.py                # COH object model
│   ├── daemon.py             # Daemon base class
│   ├── simulator.py          # Simulator engine
│   ├── neural.py             # NeuralModule (PyTorch)
│   └── __init__.py
│
├── examples/
│   ├── gridworld_advanced.py # Full demo with visualization + RL + export
│   ├── basic_demo.py
│   └── ...
│
├── tests/
│
├── README.md
└── setup.py

---

🚀 Quick Start

Run the Interactive Gridworld

python examples/gridworld_advanced.py --mode interactive

Controls:

Key	Action
W / ↑	Move up
S / ↓	Move down
A / ←	Move left
D / →	Move right
Space	Wait
Hold keys	Auto‑repeat movement

Run Training Mode

python examples/gridworld_advanced.py --mode train --episodes 30

At the end of training, the demo:

• runs a greedy policy rollout
• exports gridworld.gif (and gridworld.mp4 if ffmpeg is available)

---

🧠 COH in a Nutshell

A Constrained Object Hierarchy is a tree of objects obeying:

• Identity Constraints: truths that must always hold
• Structural Constraints: shape and organization of the hierarchy
• Behavioral Constraints: methods and interactions

Every COH object contains:

• attributes: dynamic state
• children: nested objects
• methods: executable behaviors
• neural modules: learned components
• daemons: continuous processes

This allows building:

• RL environments
• Multi‑agent systems
• Planning/constraint systems
• Hybrid symbolic‑neural architectures
• Simulators and interactive demos

… all from the same unified model.

---

🎮 Featured Example: Gridworld Advanced

The advanced Gridworld environment demonstrates nearly every COH capability:

✔ Heatmap of goal distance

✔ Agent trail visualization

✔ Policy arrow field

✔ Live training curves

✔ Keyboard interactive mode

✔ Auto‑repeat key controls

✔ Fixed‑canvas export

A rich environment ideal for:

• Teaching RL
• Demonstrating COH
• Comparing policies
• Visualizing value functions
• Experimenting with reward shaping

---

📦 Exporting Animations

GIF requires only ImageIO:

imageio.mimsave("gridworld.gif", frames, fps=6)

For MP4:

sudo apt install ffmpeg

or on macOS:

brew install ffmpeg

---

🛠 Development

Install dev dependencies

pip install -r requirements-dev.txt

Run tests

pytest -q

Code style

• Black
• isort
• flake8

---

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Add tests where appropriate
4. Submit a pull request

Please follow:

• PEP8 style
• Write clear commit messages
• Avoid committing large binaries (use LFS)

---

🗺 Roadmap

• Stable release v1.0
• Additional RL algorithms (PPO, DQN, A2C)
• COH‑based multi‑agent GPU simulator
• WebGL visualization front‑end
• Tutorial notebooks
• Benchmark suite

---

📝 License

MIT License — see LICENSE.

---

👤 Author

Dr. Harris Wang
Computing & Information Systems
Athabasca University, Canada

Further Readings:

• A GitHub wiki
• A quickstart tutorial
• A logo/badge set
• A landing page for GitHub Pages