Crowd-Management

Imported from Wu-kaixin/Crowd-Management (AGENTS.md). Install upstream with npx skills add Wu-kaixin/Crowd-Management. Copyright stays with the author.

AGENTS.md

Code map (start here if lost)

Chinese role map (core vs input vs output): docs/CODEMAP.zh.md.

Quick labels:

• Core math: src/crowd_management/controllers/, estimation/, geometry/, crowd/
• Orchestration: experiments/, evaluation/, runtime/, reporting/
• CLI entry: scripts/ (thin wrappers only)
• Inputs: configs/*.yaml
• Local outputs: runs/, outputs/, artifacts/, .tmp/ (mostly gitignored)
• Frozen evidence / media: reports/
• Local stash / pytest work: _stash/ (gitignored; preferred pytest basetemp when .tmp is locked)

Project Direction

This repository is now centered on ABCG static unknown-crowd containment. The active workflow is not DBAct evacuation optimization. DBAct, density-DBAct, and old evacuation-guidance material have been removed from main and are preserved on the read-only archive branch archive/legacy-evacuation-2026-07-21:

archive/legacy-evacuation-2026-07-21:legacy/evacuation_guidance/
archive/legacy-evacuation-2026-07-21:src/crowd_management/legacy/

The former proof-strengthening branch tip is preserved separately as archive/g7-proof-strengthening-failed-2026-07-20. The G6-era main tip is stored as archive/main-2026-09-19. Current main preserves the completed Step 1 Core baseline. Continue development on STEP1-Research-Extension. See docs/ARCHIVE_INDEX.md before reusing historical code.

Active Step 1 Core closure is on STEP1-Research-Extension. Do not add algorithms, crowd dynamics, gather, or multi-crowd features to Core. Evidence: reports/step1_known_boundary/STEP1_CLOSURE_REPORT.md. Start Core work from:

scripts/run_static_containment.py
configs/step1_known_boundary/*.yaml
src/crowd_management/controllers/abcg_v2.py
src/crowd_management/controllers/abcg_v2_route.py
src/crowd_management/controllers/boundary_route.py
src/crowd_management/scenarios/
docs/STEP1_RESEARCH_ROADMAP.md
docs/STEP1_V2_PROTOCOL.md

Step 2 gather-then-surround (dispersed → gather → surround):

scripts/run_gather_then_surround.py
configs/step2_gather/square_dispersed_gather.yaml
src/crowd_management/controllers/step2_gather/
src/crowd_management/experiments/step2_gather/

Environment

This is a Python 3.12 CLI research simulator. There is no long-running server or web app. Run experiments through scripts and inspect generated metrics/figures.

Preferred setup:

python -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e ".[dev]"

Project Conda environment:

conda env update -n abcg -f environment.yml
conda run -n abcg python -m pip install -e ".[dev]"

Testing

Standard command:

pytest --basetemp=.tmp/pytest-temp -o cache_dir=.tmp/pytest-cache

If .tmp is locked on Windows (PermissionError), use the stash work dir instead:

pytest --basetemp=_stash/pytest_work/temp -o cache_dir=_stash/pytest_work/cache

Lint / type (after pip install -e ".[dev]"):

python -m ruff check src scripts
python -m mypy

The authoritative suite size is whatever pytest --collect-only reports on the current branch (see the TEST_COUNT marker in README.md, checked by scripts/check_readme_consistency.py). Legacy evacuation tests live on the archive/legacy-evacuation-2026-07-21 branch.

Dependency health command:

python -m pip check

The success message No broken requirements found. has exit code zero and is not an error.

Main Commands

Run ABCG static containment:

python scripts/run_static_containment.py --config configs/static_crowd_circle.yaml --output runs/static_containment_circle --methods random static_circle legacy_center_radius abcg

Run the PR6 held-out paired evaluation:

python scripts/run_step1_pr6_evaluation.py --output reports/step1_pr6_evaluation --seed-count 30

Evaluation scripts select worker processes hardware-adaptively by default (--workers auto, balanced mode). Override with --workers N or --performance-mode conservative|balanced|maximum. Worker count never changes scientific results (verified by scripts/compare_results.py); see docs/performance/final_report.md.

Regenerate README media:

python scripts/build_readme_media.py

Legacy evacuation scripts, their compatibility wrappers, and old media no longer live on main. Use archive/legacy-evacuation-2026-07-21 to inspect them; do not merge the archive wholesale back into main.