✅ Fix CI workflows

.github/workflows/gh-page.yml

@@ -108,10 +108,22 @@ jobs:
             poetry run pip install mkdocs-material
           fi
           poetry install
+      # ======================== Convert Notebooks ========================
+      - name: Convert notebooks to markdown
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.dry_run != 'true' }}
+        run: |
+          chmod +x scripts/convert_notebooks.sh
+          if [ "${{ github.event_name == 'workflow_dispatch' && inputs.use_uv }}" = "true" ]; then
+            ./scripts/convert_notebooks.sh
+          else
+            poetry run jupyter nbconvert --to markdown $(find docs/tutorial -name "*.ipynb" -type f ! -path "*/.ipynb_checkpoints/*") --output-dir docs/tutorial
+          fi
       # ======================== Dry-run build ========================
       - name: Build docs only (dry-run)
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == 'true' }}
         run: |
+          chmod +x scripts/convert_notebooks.sh
+          ./scripts/convert_notebooks.sh
           if [ "${{ github.event_name == 'workflow_dispatch' && inputs.use_uv }}" = "true" ]; then
             uv run mkdocs build --strict
           else

.github/workflows/test-notebooks.yml

@@ -0,0 +1,33 @@
+name: test-notebooks
+
+on:
+  pull_request:
+  push:
+    branches: [ dev, master, main ]
+
+jobs:
+  nbmake:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install deps
+        run: |
+          uv sync --dev
+
+      - name: Run nbmake
+        env:
+          ABSESPY_PROJECT_ROOT: ${{ github.workspace }}
+        run: |
+          pytest
+

.github/workflows/tests.yml

@@ -10,6 +10,82 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  foundation-tests:
+    name: Foundation Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-py3.11-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-py3.11-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run foundation tests
+        run: |
+          uv run pytest tests/foundation/ -v --tb=short --cov=abses --cov-report=xml
+
+      - name: Upload foundation test coverage
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: false
+          file: ./coverage.xml
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  scenario-tests:
+    name: Scenario Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-py3.11-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-py3.11-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run scenario tests
+        run: |
+          uv run pytest tests/scenarios/ -v --tb=short --cov=abses --cov-report=xml
+
+      - name: Upload scenario test coverage
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: false
+          file: ./coverage.xml
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
   test:
     name: Test Python ${{ matrix.python-version }} on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
@@ -54,6 +130,51 @@ jobs:
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  performance-tests:
+    name: Performance Benchmark Tests
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-py3.11-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-py3.11-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Install pytest-benchmark
+        run: |
+          uv add pytest-benchmark
+
+      - name: Run performance benchmarks
+        run: |
+          uv run pytest tests/performance/ -v --benchmark-only --benchmark-save=baseline
+
+      - name: Compare with baseline
+        run: |
+          uv run pytest tests/performance/ -v --benchmark-compare=baseline --benchmark-compare-fail=mean:20%
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: .benchmarks/
+
   lint:
     name: Lint and Type Check
     runs-on: ubuntu-latest
@@ -80,20 +201,94 @@ jobs:
         run: |
           uv run mypy abses/
 
+  integration-tests:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-py3.11-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-py3.11-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run integration tests
+        run: |
+          uv run pytest tests/integration/ -v --tb=short
+
+  regression-tests:
+    name: Regression Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Cache uv
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-py3.11-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-py3.11-uv-
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run regression tests
+        run: |
+          uv run pytest tests/regression/ -v --tb=short
+
+      - name: Run backward compatibility tests
+        run: |
+          uv run pytest tests/test_backward_compatibility.py -v --tb=short
+
   test-matrix-summary:
     name: Test Matrix Summary
     runs-on: ubuntu-latest
-    needs: [test, lint]
+    needs: [foundation-tests, test, lint, scenario-tests]
     if: always()
     steps:
       - name: Check test results
         run: |
+          if [ "${{ needs.foundation-tests.result }}" != "success" ]; then
+            echo "❌ Foundation tests failed"
+            exit 1
+          fi
           if [ "${{ needs.test.result }}" != "success" ]; then
             echo "❌ Tests failed on one or more Python versions"
             exit 1
           fi
           if [ "${{ needs.lint.result }}" != "success" ]; then
             echo "⚠️ Linting or type checking issues detected (continuing)"
           fi
+          if [ "${{ needs.scenario-tests.result }}" != "success" ]; then
+            echo "❌ Scenario tests failed"
+            exit 1
+          fi
           echo "✅ All tests passed across Python 3.11, 3.12, and 3.13!"
+          echo "✅ Foundation tests passed!"
+          echo "✅ Scenario tests passed!"
 

.gitignore

@@ -1,3 +1,5 @@
+# Local environment files (do not commit secrets)
+.env
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -124,6 +126,24 @@ venv.bak/
 # mkdocs documentation
 /site
 
+# Generated markdown from notebooks (regenerate with: ./scripts/convert_notebooks.sh)
+# Only track non-converted markdown files (manually written guides)
+!docs/tutorial/tutorial.md
+!docs/tutorial/tutorial.zh.md
+!docs/tutorial/tutorial_guide_from_*.md
+
+# Ignore all converted .md files (auto-generated from .ipynb)
+docs/tutorial/beginner/*.md
+docs/tutorial/intermediate/*.md
+docs/tutorial/advanced/*.md
+docs/tutorial/completing/*.md
+
+# Generated image/asset directories (_files folders are regenerated during build)
+# Note: These are kept locally for mkdocs serve, but not committed
+docs/tutorial/**/*_files/
+docs/tutorial/**/*.checkpoint.ipynb
+docs/tutorial/advanced/.ipynb_checkpoints/
+
 # mypy
 .mypy_cache/
 .dmypy.json

CHANGELOG.md

@@ -1,66 +1,5 @@
 # Changelog
 
-## [0.8.5](https://github.com/SongshGeoLab/ABSESpy/compare/v0.8.4...v0.8.5) (2025-10-20)
-
-
-### Bug Fixes
-
-* **compatibility:** :bug: Ensure backward compatibility for raster and vector data application ([ae24d81](https://github.com/SongshGeoLab/ABSESpy/commit/ae24d819a98b9b7930f02f9ae509f861679dd7b7))
-
-## [0.8.4](https://github.com/SongshGeoLab/ABSESpy/compare/v0.8.3...v0.8.4) (2025-10-20)
-
-
-### Bug Fixes
-
-* **refactor:** :recycle: Ensure backward compatibility in exp parameters setting ([ea4e52a](https://github.com/SongshGeoLab/ABSESpy/commit/ea4e52a76e7238491ad9fefb9b6f83101b0cf9ea))
-
-## [0.8.3](https://github.com/SongshGeoLab/ABSESpy/compare/v0.8.2...v0.8.3) (2025-10-20)
-
-
-### Bug Fixes
-
-* **random:** :bug: Enhance ListRandom functionality with ActorsList support ([f790b7c](https://github.com/SongshGeoLab/ABSESpy/commit/f790b7c24695bd96f044f9f07bef615b87968f68))
-* **sequences:** :bug: Re-include better() method to handle None threshold ([104b104](https://github.com/SongshGeoLab/ABSESpy/commit/104b104a51dc25c647f973b4331b09847da04f9f))
-
-## [0.8.2](https://github.com/SongshGeoLab/ABSESpy/compare/v0.8.1...v0.8.2) (2025-10-17)
-
-
-### Bug Fixes
-
-* **sequences:** Fix attribute access in better() method ([9b3de51](https://github.com/SongshGeoLab/ABSESpy/commit/9b3de51c82594d444ce2eab33fb466cd2b85ddfb))
-
-
-### Documentation
-
-* **api:** :memo: Enhance type checking and documentation in actor module ([aafa7d3](https://github.com/SongshGeoLab/ABSESpy/commit/aafa7d36f3075d28271f399e6242178342781d07))
-
-## [0.8.1](https://github.com/SongshGeoLab/ABSESpy/compare/v0.8.0...v0.8.1) (2025-10-17)
-
-
-### Bug Fixes
-
-* **core:** :bug: Add datasets property to BaseModelElement for improved data access ([3cd5797](https://github.com/SongshGeoLab/ABSESpy/commit/3cd57976946c5cd43f833f3374277b38d296aeec))
-
-## [0.8.0](https://github.com/SongshGeoLab/ABSESpy/compare/v0.7.5...v0.8.0) (2025-10-16)
-
-
-### Features
-
-* **core:** Protocol-based architecture refactoring ([e424cae](https://github.com/SongshGeoLab/ABSESpy/commit/e424cae00207149e34757bc33ee986a36740662d))
-* **logging:** :sparkles: Implement unified logging configuration for ABSESpy ([0453646](https://github.com/SongshGeoLab/ABSESpy/commit/045364635829b98772d8e12f6160c62f706cb75c))
-
-
-### Documentation
-
-* 📚 Add versioning guide for ABSESpy documentation ([b1391bf](https://github.com/SongshGeoLab/ABSESpy/commit/b1391bf009835a50a162e7f9132d3fe7939dede9))
-* 📚 Update materials documentation for clarity and accuracy ([0cbe0c8](https://github.com/SongshGeoLab/ABSESpy/commit/0cbe0c8c1e1cbb3ed4d87cd38cf30b7d11a1d988))
-* 📚 Update tutorials and documentation for improved clarity and functionality ([55f80b4](https://github.com/SongshGeoLab/ABSESpy/commit/55f80b4870325ce8b34cd6e0485d44ddfcbc651a))
-* **docs:** :memo: Update documentation and examples for ABSESpy ([c0089fe](https://github.com/SongshGeoLab/ABSESpy/commit/c0089fe6ad6c8224895b8c5140dbf3941375cf10))
-* **examples:** :memo: Enhance Schelling model with detailed documentation and tests ([33e7e00](https://github.com/SongshGeoLab/ABSESpy/commit/33e7e008dad9d2adfd99575b90e1b4e3a12242ca))
-* **examples:** :memo: Enhance wolf-sheep model documentation and tests ([fdf8f11](https://github.com/SongshGeoLab/ABSESpy/commit/fdf8f11408608bd1c96c68c4618376e701455255))
-* **examples:** :memo: Update model documentation and configuration. ([7a11b25](https://github.com/SongshGeoLab/ABSESpy/commit/7a11b258fdc53ec33ba8056f5bc352cf11593c49))
-* **i18n:** :memo: Add multilingual support and enhance documentation for ABSESpy ([83640ee](https://github.com/SongshGeoLab/ABSESpy/commit/83640ee251eb9b984669adb5cb5e6edcc529cf6c))
-
 ## [0.7.5](https://github.com/SongshGeoLab/ABSESpy/compare/v0.7.4...v0.7.5) (2025-02-16)