guzhujushi
5319589dfd
审查并精简 ChatGPT 的建库建议后落地的第一版骨架，只定接口不写实现。 - 建议审查：14 个包 → 7 个；约 250 个函数 → 约 40 个；5 个 Result 类 → 1 个 （docs/01-suggestion-review.md） - docs/：架构、路线图（含永久不做清单）、环境、Git 工作流、函数卡片模板 - src/mcm_toolkit/：core / data / stats / models / solve / decision / viz 共 23 个模块，均为签名 + docstring + NotImplementedError - tests/：9 个文件，其中 test_api_surface.py 已通过（20 passed） - examples/ problems/ notebooks/ figures/ tables/ 骨架 - pyproject.toml（核心依赖 4 个 + 6 组 extras）、environment.yml - scripts/：setup-venv.ps1（ASCII + LF）、setup-conda.ps1、doctor.ps1 - 环境：.venv（system-site-packages）与 conda 环境 mcm-toolkit 均已建好， 数值栈版本与 base 完全对齐（numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6，MKL 后端）
69 lines
2.3 KiB
Markdown
69 lines
2.3 KiB
Markdown
# MCM/ICM Toolkit
|
||
|
||
美赛（MCM/ICM）编程手的**竞赛层工具箱**：
|
||
把比赛中反复手写的代码沉淀成"高频算法自己实现 + 成熟库薄封装 + 统一结果接口"。
|
||
|
||
> **不**替代 SciPy / scikit-learn / statsmodels / NetworkX / SALib / SymPy。
|
||
> 只做它们到"4 天赛程能用"之间的那一层。
|
||
|
||
## 快速开始
|
||
|
||
```powershell
|
||
# 1) 建环境（两条路选一条）
|
||
.\scripts\setup-venv.ps1 # venv，零下载，复用 Anaconda base 的科学栈
|
||
.\scripts\setup-conda.ps1 # conda 环境 mcm-toolkit（clone base，离线）
|
||
|
||
# 2) 自检
|
||
.\scripts\doctor.ps1
|
||
|
||
# 3) 激活
|
||
.\.venv\Scripts\Activate.ps1
|
||
```
|
||
|
||
```python
|
||
import mcm_toolkit as mcm
|
||
|
||
mcm.set_seed(42)
|
||
r = mcm.bootstrap_ci(data, statistic=np.median, random_state=42)
|
||
print(r.params["low"], r.params["high"])
|
||
```
|
||
|
||
## 当前状态（v0.0.1）
|
||
|
||
**接口已定，实现未填。** 所有函数体是 `raise NotImplementedError` + `TODO(L0/L1/v0.2)` 标记，
|
||
按 [docs/03-roadmap.md](docs/03-roadmap.md) 的 L0 → L1 顺序填。
|
||
|
||
## 目录
|
||
|
||
| 路径 | 说明 |
|
||
|---|---|
|
||
| `src/mcm_toolkit/` | 包源码，7 个子包 |
|
||
| `tests/` | 测试，与包一一对应（测已知解析解，不测实现细节） |
|
||
| `examples/` | 每个模块一个能跑的最小例子 |
|
||
| `problems/` | 历年真题（每做完一题，反向沉淀 1～3 个通用函数） |
|
||
| `notebooks/` | 探索用 |
|
||
| `docs/` | 需求、架构、路线图、环境、规范 |
|
||
| `scripts/` | 环境脚本 |
|
||
| `STATUS.md` | 当前进度 |
|
||
|
||
## 子包
|
||
|
||
| 包 | 职责 | 关键函数 |
|
||
|---|---|---|
|
||
| `core` | 基础设施 | `Result` `get_rng` `check_*` |
|
||
| `data` | 读 / 洗 / 变换 / 采样 | `load_table` `detect_outliers` `normalize` |
|
||
| `stats` | 描述 / 推断 / bootstrap | `describe` `bootstrap_ci` `fit_distribution` |
|
||
| `models` | 回归 / 时序 / ML | `fit_linear` `fit_arima` `compare_models` |
|
||
| `solve` | 优化 / 模拟 / 敏感性 | `monte_carlo` `simulated_annealing` `sobol_analyze` |
|
||
| `decision` | 评价决策 | `entropy_weights` `ahp_weights` `topsis` `gm11` |
|
||
| `viz` | 出图出表 | `plot` `save_figure` `save_table` |
|
||
|
||
## 文档
|
||
|
||
开始动手前请先读 [docs/01-suggestion-review.md](docs/01-suggestion-review.md)——
|
||
它记录了"为什么最终结构是这样"，以及**明确不做什么**。
|
||
|
||
## 许可
|
||
|
||
MIT，见 [LICENSE](LICENSE)。
|