Major restructuring and cleanup before run_headless implementation

.gitignore

@@ -1,28 +1,84 @@
-.*
-!.gitignore
-/.idea
+# OS
 .DS_Store
+.AppleDouble
+.LSOverride
+
+# IDEs / Editors
+.idea/
+.vscode/
+*.iml
+.run/
+
+# Python
 __pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.pytype/
+.pyre/
+.ruff_cache/
+.hypothesis/
+.ipynb_checkpoints
+
+# Virtual envs / tooling
+.venv/
+venv/
+env/
+ENV/
+.python-version
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Coverage / reports / caches
+.coverage
+.coverage.*
+.cache/
+htmlcov/
+coverage.xml
+*.cover
+*.py,cover
+nosetests.xml
+pytestdebug.log
+
+# Logs / temp
+logs/
+*.log
+*.log.*
+*.tmp
+tmp/
+temp/
+
+# Jupyter
 *.ipynb
-/examples
-/starter_model
-/mesa
+
+# C extensions
+*.so
+
+# Node / JS
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.webpack-cache/
+.parcel-cache/
+
+# MkDocs
 site/
-sorted-out-tests
-/benchmarks
-/notes
-/docs/work_in_progress_exclude
-# short term:
-Dockerfile
-docker-compose.yml
-Singularity.def
-/app.py
-/main.py
-templates
-/docs/images/CI-images
-.coverage*
-*.cache
-ai_info.txt
-convert_docstrings.py
-TODO.txt
-democracy_sim/simulation_output
+docs/images/
+
+# Project data and artifacts
+data/
+!data/.gitkeep
+
+# Configs
+configs/**/*.yaml
+!configs/**/default.yaml
+
+# Local env and secrets
+.env
+.env.*
+*.env
+*.secrets
+secrets/

configs/config.yaml

@@ -0,0 +1,46 @@
+# configs.yaml
+model:
+  # Elections
+  election_costs: 1
+  max_reward: 1
+  election_impact_on_mutation: 1.8
+  mu: 0.05
+  rule_idx: 1
+  distance_idx: 1
+
+  # Model parameters
+  num_agents: 800
+  common_assets: 40000
+  num_colors: 3
+  color_patches_steps: 3
+  patch_power: 1.0
+  heterogeneity: 0.3  # color_heterogeneity
+  known_cells: 10
+
+  # Voting Agents
+  num_personalities: 4
+
+  # Grid parameters
+  height: 100            # (grid_rows)
+  width: 80              # (grid_cols)
+
+  # Voting Areas
+  num_areas: 16
+  av_area_height: 25
+  av_area_width: 20
+  area_size_variance: 0.0
+
+# Visualization parameters
+visualization:
+  # Grid parameters
+  cell_size: 10
+  draw_borders: true
+  # Statistics and Views
+  show_area_stats: true
+
+simulation:
+  runs:         3     # number of independent seeds
+  num_steps:    3
+  processes:    8      # ≤ CPU cores
+  store_grid:   true  # set true only if you really need full grids
+  grid_interval: 1    # save every 10th step if grids enabled

configs/default.yaml

@@ -0,0 +1,42 @@
+model:
+  # Elections
+  election_costs: 1
+  max_reward: 2
+  election_impact_on_mutation: 1.8
+  mu: 0.05
+  rule_idx: 1
+  distance_idx: 1
+
+  # Model parameters
+  num_agents: 800
+  common_assets: 40000
+  num_colors: 3
+  color_patches_steps: 3
+  patch_power: 1.0
+  heterogeneity: 0.3
+  known_cells: 10
+
+  # Voting Agents
+  num_personalities: 4
+
+  # Grid parameters
+  height: 100
+  width: 80
+
+  # Voting Areas
+  num_areas: 16
+  av_area_height: 25
+  av_area_width: 20
+  area_size_variance: 0.0
+
+visualization:
+  cell_size: 10
+  draw_borders: true
+  show_area_stats: true
+
+simulation:
+  runs: 3
+  num_steps: 3
+  processes: 8
+  store_grid: true
+  grid_interval: 1

configs/toy.yaml

@@ -0,0 +1,46 @@
+# To use this configuration, set: CONFIG_FILE=toy.yaml
+model:
+  # Elections
+  election_costs: 1
+  max_reward: 2
+  election_impact_on_mutation: 1.8
+  mu: 0.05
+  rule_idx: 1
+  distance_idx: 1
+
+  # Model parameters
+  num_agents: 5
+  common_assets: 5000
+  num_colors: 3
+  color_patches_steps: 3
+  patch_power: 1.0
+  heterogeneity: 0.3  # color_heterogeneity
+  known_cells: 5
+
+  # Voting Agents
+  num_personalities: 3
+
+  # Grid parameters
+  height: 20            # (grid_rows)
+  width: 10             # (grid_cols)
+
+  # Voting Areas
+  num_areas: 2
+  av_area_height: 10
+  av_area_width: 10
+  area_size_variance: 0.0
+
+# Visualization parameters
+visualization:
+  # Grid parameters
+  cell_size: 30
+  draw_borders: true
+  # Statistics and Views
+  show_area_stats: true
+
+simulation:
+  runs:         3     # number of independent seeds
+  num_steps:    3
+  processes:    8      # ≤ CPU cores
+  store_grid:   true  # set true only if full grid is needed
+  grid_interval: 1    # save every i'th step if grids enabled