chore: 初始化 MCM/ICM Toolkit 仓库骨架

审查并精简 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 后端)
This commit is contained in:
guzhujushi committed 2026-10-01 17:43:48 +08:00
commit 5319589dfd
76 files changed
+6812

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
"""图表导出。
工具箱的最终消费者是**论文**,所以这一层不是"附赠功能",
而是原建议里最被低估的部分(它只给了一句 `save_figure`)。
"""
from __future__ import annotations
from pathlib import Path
from typing import Any
__all__ = ["save_figure", "save_table"]
def save_figure(
fig: Any,
path: str | Path,
dpi: int = 300,
formats: tuple[str, ...] = ("png", "pdf"),
bbox_inches: str = "tight",
transparent: bool = False,
) -> list[Path]:
"""保存图,默认同时出 PNG(预览用)和 PDF(LaTeX 插图用)。
Parameters
----------
formats:
美赛论文如果用 LaTeX 排版,**矢量图(PDF/EPS)比 PNG 清晰得多**,
所以默认两种都出。
Returns
-------
实际写出的文件路径列表。
Notes
-----
建议配合项目的 figure 目录约定:`figures/fig{序号}_{短名}.pdf`,
图号与正文引用一一对应,最后核对时不容易错位。
"""
# TODO(L0)
raise NotImplementedError
def save_table(
df: Any,
path: str | Path,
fmt: tuple[str, ...] = ("csv", "latex", "markdown"),
caption: str | None = None,
label: str | None = None,
float_format: str = "%.4f",
index: bool = True,
) -> list[Path]:
r"""导出结果表,默认同时出 CSV + LaTeX + Markdown。
这是**节省时间最多的一个函数**:`compare_models`、`parameter_sweep`、
`topsis` 的结果都能直接 `save_table(r.data, "tab3_model_compare")`,
然后把 LaTeX 片段粘进论文,不用手工敲表格。
Parameters
----------
caption / label:
写进 LaTeX 的 `\caption{}` 与 `\label{}`,
表号与正文 `\ref{}` 的对应关系就不会断。
Returns
-------
实际写出的文件路径列表。
Examples
--------
>>> paths = save_table(df, "tables/tab2", caption="模型对比") # doctest: +SKIP
"""
# TODO(L1)
raise NotImplementedError