Merge pull request #24 from codegithubka/kimon

codegithubka · web-flow · commit 40650b0b3587 · 2026-01-31T14:38:13.000+01:00
Kimon
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+data/** filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
@@ -9,7 +9,6 @@ results/
 # Jupyter Notebook checkpoints
 .ipynb_checkpoints/
 # Data files
-data/
 .pytest_cache/
 
 .DS_Store/
diff --git a/.rsync-exclude b/.rsync-exclude
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-## Predator-Prey Cellular Automaton: Model Documentation
+## Predator-Prey Cellular Automaton
 
 ### Overview
 
@@ -8,6 +8,26 @@ The codebase uses Numba JIT compilation for computationally intensive kernels an
 
 ---
 
+### Project Structure
+
+The repository is organized to separate model logic, high-performance execution scripts, and data analysis:
+
+```text
+.
+├── models/               # Core simulation logic
+│   ├── CA.py             # Base Cellular Automaton class
+│   ├── config.py         # Phase-specific experiment configurations
+│   └── numba_optimized.py # JIT kernels and cluster detection
+├── scripts/              # HPC execution scripts
+│   └── run_phase{1..5}.sh # Bash scripts for Slurm/SGE jobs
+├── notebooks/            # Data analysis and visualization
+│   └── plots.ipynb       # Results plotting and Hydra effect analysis
+├── tests/                # Pytest suite for model validation
+├── data/                 # Local storage for simulation outputs (JSONL)
+└── requirements.txt      # Project dependencies
+```
+---
+
 ### Background
 
 #### The Hydra Effect
@@ -278,15 +298,83 @@ Metadata files (`phase{N}_metadata.json`) accompany each results file with confi
 
 ---
 
-### Dependencies
+### Testing
+
+The project includes a pytest test suite covering all core modules.
+
+#### Test Modules
+
+| File | Coverage |
+|------|----------|
+| `tests/test_ca.py` | CA base class, PP model initialization, update mechanics, evolution, edge cases |
+| `tests/test_numba_optimized.py` | Cluster detection, PCF computation, PPKernel updates, performance |
+| `tests/test_experiments.py` | Utility functions, I/O operations, simulation runner, phase registration |
+| `tests/test_config.py` | Configuration defaults, phase configs, helper methods |
+
+#### Running Tests
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_ca.py -v
+
+# Run with coverage report
+pytest tests/ --cov=models --cov-report=html
+
+# Fast mode (stop on first failure)
+pytest tests/ -x --tb=short
+```
+
+### Documentation
+
+Full API documentation is available at: **[https://codegithubka.github.io/CSS_Project/](https://codegithubka.github.io/CSS_Project/)**
+
+
+#### Generating Docs Locally
+```bash
+# Generate HTML documentation
+pdoc --output-dir docs --docformat numpy --no-include-undocumented \
+    models.CA models.config models.numba_optimized experiments.py
 
-**Required:**
+# View locally
+open docs/index.html
+```
+
+Documentation is auto-generated from NumPy-style docstrings using [pdoc](https://pdoc.dev/).
+
+
+### Getting Started
+
+#### 1. Dependencies
+
+Required:
 - Python 3.8+
 - NumPy
 - Numba (for JIT compilation)
 - tqdm (progress bars)
 - joblib (parallelization)
 
-**Optional:**
+Optional:
 - matplotlib (visualization)
 - scipy (additional analysis)
+
+#### 2. Installation
+Clone the repository and install the dependencies. It is recommended to use a virtual environment.
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+```
+
+#### 3. Running simulations
+
+The experiments are automated via bash-scripts in the ```scripts``` directory. These are configured for high-performance computing environments:
+
+```bash
+# Grant execution permissions
+chmod +x scripts/*.sh
+
+# Execute a specific phase (e.g., Phase 1)
+./scripts/run_phase1.sh
+```
diff --git a/data/.DS_Store b/data/.DS_Store
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7b0fb1b40fc38f961e98edff1913806e6a69657cc6f00a33b928ca4707db17f3
+size 10244
diff --git a/data/phase1.5.1_18682575/experiments.log b/data/phase1.5.1_18682575/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5240642fb1fcb44674b419003ddc4db60c741b22bdce03d3b6d0aab279b0f2ea
+size 2490
diff --git a/data/phase1.5.1_18682575/phase1_config.json b/data/phase1.5.1_18682575/phase1_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ffdb80f39294e226872f6e807c56210677d0de19528f33c530a8d1d01da86b6a
+size 1255
diff --git a/data/phase1.5.1_18682575/phase1_metadata.json b/data/phase1.5.1_18682575/phase1_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db0d33f0ff6ae019184cc92e43ffae61ba410662fbcf53ba4420ef6cfcd245a6
+size 1551
diff --git a/data/phase1.5.1_18682575/phase1_results.jsonl b/data/phase1.5.1_18682575/phase1_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ad4648db8575f80d2ece3bc8bf30e18ab84fa769a71d6ead9757d33e5eff948
+size 41186635
diff --git a/data/phase1.5.2_18777691/experiments.log b/data/phase1.5.2_18777691/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f2c7d6a2e3dd0be584efd430ad49bd3ce7cf2ac0ce7d534668889ef5033e7727
+size 2494
diff --git a/data/phase1.5.2_18777691/phase1_config.json b/data/phase1.5.2_18777691/phase1_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:82a579ae88923225c789314b68b4bbb7e644d8e441ffea563bcbb4b16f25ba37
+size 1208
diff --git a/data/phase1.5.2_18777691/phase1_metadata.json b/data/phase1.5.2_18777691/phase1_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0382079bfff1d769c3d4d32c145b972ecc82bbf8564a2eb7525b6af047497059
+size 1496
diff --git a/data/phase1.5.2_18777691/phase1_results.jsonl b/data/phase1.5.2_18777691/phase1_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:64a5fad536d70f292e00926ab32c8fd257105337e0f5094bb9ecf7169bd00fda
+size 43275027
diff --git a/data/phase1_18677015/experiments.log b/data/phase1_18677015/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:729f4201c360f0d29384a76f29cf0d702ddc24354290d21d3aaea188c0e51d67
+size 2490
diff --git a/data/phase1_18677015/phase1_config.json b/data/phase1_18677015/phase1_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f68d50864d7e3174e639713d9fef688763291b51a11961317d5fe2d739407001
+size 1235
diff --git a/data/phase1_18677015/phase1_metadata.json b/data/phase1_18677015/phase1_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84349952459a64ed4b5674cab7bddd583a29c523b35b5f4a0e1ca9f0f7a7023d
+size 1527
diff --git a/data/phase1_18677015/phase1_results.jsonl b/data/phase1_18677015/phase1_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d779d4e7a0add801576b1c3555af21c6839e3f522677504a3b56d5f940cb1576
+size 26227779
diff --git a/data/phase1_18831093/experiments.log b/data/phase1_18831093/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8b5cb26780d67794474f8fb78bbbcfd8d225c9ce508fa2b1085b90ffab9f4e9e
+size 2491
diff --git a/data/phase1_18831093/phase1_config.json b/data/phase1_18831093/phase1_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c6fb9843e90c3f2a199f20177b03bc36428323320e52939d037b73c4dc34dc51
+size 1212
diff --git a/data/phase1_18831093/phase1_metadata.json b/data/phase1_18831093/phase1_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b73bfe98e55548b8ad9618b056483929347d8d36a2a0124428b369328a0eec18
+size 1500
diff --git a/data/phase1_18831093/phase1_results.jsonl b/data/phase1_18831093/phase1_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:962eb6d6a5583d88cf2b8aea4e47c6bd83aa24abe2a4a94b6254bc8f7acf2e84
+size 39709495
diff --git a/data/phase2_18693004/experiments.log b/data/phase2_18693004/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b4627cef4b371b2a36633c432e2ea3270a2853d04160be204bb95379c17b0689
+size 2560
diff --git a/data/phase2_18693004/phase2_config.json b/data/phase2_18693004/phase2_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e130574b6faac0aad25f77770d7f796dfbce1884fbe640cb065d15204000c18c
+size 1204
diff --git a/data/phase2_18693004/phase2_metadata.json b/data/phase2_18693004/phase2_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0e4cc596a346d0d2e758f5315497a87542dcb77f8aed4ed1ac37aeb143604bd2
+size 630
diff --git a/data/phase2_18693004/phase2_results.jsonl b/data/phase2_18693004/phase2_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0362ebd75365fd15cb4c6b8cd0a6f94a045985c08aa63b58ad5b60dbf1fbd4f8
+size 15276583
diff --git a/data/phase3_18698382/experiments.log b/data/phase3_18698382/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:55c63f4fb30c52ee95edf0d8429eb8a7d6b612924f8e18ae5079fc12393bccd5
+size 2557
diff --git a/data/phase3_18698382/phase3_config.json b/data/phase3_18698382/phase3_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d148be050feb160778a5f178f6e8868e218cc6d86f4346ea61e52a5ae9aad6a4
+size 1205
diff --git a/data/phase3_18698382/phase3_metadata.json b/data/phase3_18698382/phase3_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:913b8d305501882ace1d145ed487b9de4f89b555d220eed5ab8d993a2ac7addd
+size 263
diff --git a/data/phase3_18698382/phase3_results.jsonl b/data/phase3_18698382/phase3_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f793c2b13eaa135faf3ce7fa0f7fcf17dba7424809670e0ffe82882b5dfe2fdb
+size 10638659
diff --git a/data/phase4.2_18832956/experiments.log b/data/phase4.2_18832956/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a3a051ae6d233ed3decfe95ed72f3d32e261bbb850c61d45955b2bfcd06d17cd
+size 2729
diff --git a/data/phase4.2_18832956/phase4_config.json b/data/phase4.2_18832956/phase4_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ef9e76a77d7d34f58732f52d6d9bc4291f6d553310304093bed24ce9e21f763
+size 1202
diff --git a/data/phase4.2_18832956/phase4_metadata.json b/data/phase4.2_18832956/phase4_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46d6ea377eea10988f97f8575d7f7dc0ad40d8a3daf304eb8b20db37257f312b
+size 1931
diff --git a/data/phase4.2_18832956/phase4_results.jsonl b/data/phase4.2_18832956/phase4_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:140bed8987eb37a7b6d068e18d46046af95fd5dc6c691772320397145928c39f
+size 210033280
diff --git a/data/phase4_18735304/experiments.log b/data/phase4_18735304/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:61873b621572a2248b0398ce6fa932e92f1a053d4d87bcd33ec1438f92913c1b
+size 2710
diff --git a/data/phase4_18735304/phase4_config.json b/data/phase4_18735304/phase4_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:772c90b2ea5538e6d415a20e6e03e3335a2a91947ed7aee457dccedaeb6c02d0
+size 1201
diff --git a/data/phase4_18735304/phase4_metadata.json b/data/phase4_18735304/phase4_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:db305edc67dc85c6d30ce60153aaa9cba6e09a6a315d8134f26a82621ce4fe12
+size 1766
diff --git a/data/phase4_18735304/phase4_results.jsonl b/data/phase4_18735304/phase4_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f4cbd3fb21adc3a1dea5597261d9f2ca7a346ade0894dd947f04d5af25be5678
+size 299324191
diff --git a/data/phase6.2_18832958/experiments.log b/data/phase6.2_18832958/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:388b8657914a635d430b129f19ba3519b4e6a566ba9ec0dcc8ef2521e1129983
+size 2804
diff --git a/data/phase6.2_18832958/phase6_config.json b/data/phase6.2_18832958/phase6_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f136ed45fd807d8715e8e870dafa0b4e9f1e3bd3c2aafa9a7fb274588da3abad
+size 1201
diff --git a/data/phase6.2_18832958/phase6_metadata.json b/data/phase6.2_18832958/phase6_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1dca31266b2913e096eae4964a397378b046ab76c2295be66083fb42457eade1
+size 1980
diff --git a/data/phase6.2_18832958/phase6_results.jsonl b/data/phase6.2_18832958/phase6_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b3926c6145019a089fe5b8d2d74fc0291645f97725b1cf10137762efce8835a3
+size 148526646
diff --git a/data/phase6_18780164/experiments.log b/data/phase6_18780164/experiments.log
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c860bc50bdafa4a13710140e9c5478e008f6d63fd8daa090348962959add9f6
+size 2789
diff --git a/data/phase6_18780164/phase6_config.json b/data/phase6_18780164/phase6_config.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d2a46b398cb0bbfefb3d9332a9849f2d66ec7449df017ffca4d301ed49712114
+size 1200
diff --git a/data/phase6_18780164/phase6_metadata.json b/data/phase6_18780164/phase6_metadata.json
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:967c81e441ac5df17a56e0cf005a78d8886e5d13329cbfc03ba673c82f35eb40
+size 1815
diff --git a/data/phase6_18780164/phase6_results.jsonl b/data/phase6_18780164/phase6_results.jsonl
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:efc15165b62eb97a5908083f7c79e021420a1f392f8882955d13206a294a497d
+size 237517377
diff --git a/genai_usage/GEN_AI.md b/genai_usage/GEN_AI.md
diff --git a/genai_usage/kimon_prompts.md b/genai_usage/kimon_prompts.md
diff --git a/genai_usage/sary_prompts.md b/genai_usage/sary_prompts.md
diff --git a/genai_usage/sofronia_prompts.md b/genai_usage/sofronia_prompts.md
diff --git a/genai_usage/storm_prompts.md b/genai_usage/storm_prompts.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+data/** filter=lfs diff=lfs merge=lfs -text`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:7b0fb1b40fc38f961e98edff1913806e6a69657cc6f00a33b928ca4707db17f3`
	`3`	`+size 10244`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:5240642fb1fcb44674b419003ddc4db60c741b22bdce03d3b6d0aab279b0f2ea`
	`3`	`+size 2490`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:ffdb80f39294e226872f6e807c56210677d0de19528f33c530a8d1d01da86b6a`
	`3`	`+size 1255`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:db0d33f0ff6ae019184cc92e43ffae61ba410662fbcf53ba4420ef6cfcd245a6`
	`3`	`+size 1551`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:2ad4648db8575f80d2ece3bc8bf30e18ab84fa769a71d6ead9757d33e5eff948`
	`3`	`+size 41186635`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:f2c7d6a2e3dd0be584efd430ad49bd3ce7cf2ac0ce7d534668889ef5033e7727`
	`3`	`+size 2494`