[Fea] Support code trace (#1179)

HydrogenSulfate · web-flow · commit fd011a090203 · 2025-07-03T10:24:33.000+08:00
* support code snapshot tracing

* update doc
diff --git a/README.md b/README.md
@@ -150,7 +150,7 @@ PaddleScience 是一个基于深度学习框架 PaddlePaddle 开发的科学计
 <!-- --8<-- [start:feature] -->
 ## ✨特性
 
-- **支持自动化并行实验调度，一键串/并行启动实验任务([教程](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/user_guide/#113))**，提高科研效率。
+- 支持**[实验源码跟踪](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/user_guide/#112)，[一键启动并行实验](https://paddlescience-docs.readthedocs.io/zh-cn/latest/zh/user_guide/#114)**，提高科研效率。
 - 支持简单几何和复杂 STL 几何的采样与布尔运算。
 - 支持包括 Dirichlet、Neumann、Robin 以及自定义边界条件。
 - 支持物理机理驱动、数据驱动、数理融合三种问题求解方式。涵盖流体、结构、气象等领域 20+ 案例。
diff --git a/docs/zh/user_guide.md b/docs/zh/user_guide.md
@@ -45,7 +45,52 @@ EVAL:
     sup_validator: 128
 ```
 
-#### 1.1.2 命令行方式配置参数
+#### 1.1.2 保存实验代码快照⭐
+
+尽管我们提供了以 hydra 和 Omegaconf 为基础的运行配置系统，但除了配置文件外还可能会涉及修改源代码，这同样会导致实验代码版本混乱，难以追踪。
+
+为了解决这一问题，PaddleScience 提供了代码差异跟踪功能，通过在运行命令的末尾加上：`trace=True`，就能够自动将当前代码快照保存到 `output_dir/code_snapshot/uncommitted.diff` 文件中，便于后续追踪和复现。
+
+以 `allen_cahn_piratenet.py` 为例，首先确认 Python 环境中安装了 GitPython 包
+
+``` sh
+python -m pip install GitPython
+```
+
+然后在运行命令的末尾加上 `trace=True` 参数
+
+``` sh
+python allen_cahn_piratenet.py trace=True
+```
+
+则其打印的日志如下
+
+``` log hl_lines="1-8"
+ppsci MESSAGE: [Code Trace] Git Information:
+ppsci MESSAGE:   Branch : support_code_trace
+ppsci MESSAGE:   Commit : 5ea90ae584b7fff17ff5aa385ba5abb6c04c268c
+ppsci MESSAGE:   Date   : 2025-06-24T20:48:07+08:00
+ppsci MESSAGE:   Dirty  : True
+ppsci INFO: [Code Trace] Staged changes saved to: outputs_allen_cahn_piratenet/2025-07-02/20-13-46/code_snapshot/staged.diff
+ppsci INFO: [Code Trace] To restore your code to this staged version, run: git apply outputs_allen_cahn_piratenet/2025-07-02/20-13-46/code_snapshot/staged.diff
+ppsci INFO: [Code Trace] Unstaged changes saved to: outputs_allen_cahn_piratenet/2025-07-02/20-13-46/code_snapshot/unstaged.diff
+ppsci INFO: [Code Trace] To restore your code to this unstaged version, run: git apply outputs_allen_cahn_piratenet/2025-07-02/20-13-46/code_snapshot/unstaged.diff
+W0702 20:13:46.390472 37150 gpu_resources.cc:114] Please NOTE: device: 0, GPU Compute Capability: 7.0, Driver API Version: 12.0, Runtime API Version: 11.6
+ppsci MESSAGE: 'shuffle' and 'drop_last' are both set to False in default as sampler config is not specified.
+ppsci INFO: Auto collation is disabled and set num_workers to 0 to speed up batch sampling.
+ppsci INFO: Using paddlepaddle develop(f701bb1) on device Place(gpu:0)
+ppsci MESSAGE: Set to_static=False for computational optimization.
+...
+```
+
+可以看到开启此时会在日志中打印出更为详细的代码版本信息，并自动将当前代码快照保存到 `output_dir/code_snapshot/*.diff` 文件中，可通过 `git apply` 命令将实验代码恢复到快照版本。
+
+!!! note "注意事项"
+
+    - 如果需要跟踪新增文件，需先使用 `git add` 将新增文件添加到暂存区后才能被跟踪。
+    - 使用本功能需确保当前开发的代码库为 git 仓库，且当前代码库中存在 `.git` 文件夹，否则无法跟踪。
+
+#### 1.1.3 命令行方式配置参数
 
 仍然以配置文件 `bracket.yaml` 为例，关于学习率部分的参数配置如下所示。
 
@@ -94,7 +139,7 @@ TRAIN:
     # python example.py PATH="/workspace/lr=0.1,s=[3]/best_model.pdparams"
     ```
 
-#### 1.1.3 自动化运行实验
+#### 1.1.4 自动化运行实验⭐
 
 如 [1.1.2 命令行方式配置参数](#112) 所述，可以通过在程序执行命令的末尾加上合适的参数来控制多组实验的运行配置，接下来以自动化执行四组实验为例，介绍如何利用 hydra 的 [multirun](https://hydra.cc/docs/1.0/tutorials/basic/running_your_app/multi-run/#internaldocs-banner) 功能，实现该目的。
 
@@ -675,7 +720,7 @@ PaddleScience 提供了多种推理配置组合，可通过命令行进行组合
     solver.eval()
     ```
 
-### 1.7 实验过程可视化
+### 1.7 实验过程可视化⭐
 
 === "TensorBoardX"
 
@@ -945,7 +990,7 @@ best_value: 0.02460772916674614
 
 ### 2.2 分布式训练
 
-#### 2.2.1 数据并行
+#### 2.2.1 数据并行⭐
 
 接下来以 `examples/pipe/poiseuille_flow.py` 为例，介绍如何正确使用 PaddleScience 的数据并行功能进行训练。分布式训练细节可以参考：[Paddle-使用指南-分布式训练-快速开始-数据并行](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/06_distributed_training/cluster_quick_start_collective_cn.html)。
 
diff --git a/ppsci/utils/callbacks.py b/ppsci/utils/callbacks.py
@@ -14,6 +14,7 @@
 
 import importlib.util
 import inspect
+import os
 import sys
 import traceback
 from os import path as osp
@@ -134,3 +135,62 @@ def on_job_start(self, config: DictConfig, **kwargs: Any) -> None:
             core.set_prim_eager_enabled(True)
             core._set_prim_all_enabled(True)
             logger.message("Prim mode is enabled.")
+
+        # === Optionally log git info & dump uncommitted diff ===
+        if bool(full_cfg.get("trace", False)):
+            if not importlib.util.find_spec("git"):
+                logger.error(
+                    "[Code Trace] GitPython is required for trace=True.\n"
+                    "Please install it with: pip install GitPython"
+                )
+                sys.exit(RUNTIME_EXIT_CODE)
+
+            from git import InvalidGitRepositoryError
+            from git import Repo
+
+            try:
+                repo = Repo(".", search_parent_directories=True)
+                branch = repo.active_branch.name
+                commit = repo.head.commit
+                commit_hash = commit.hexsha
+                commit_time = commit.committed_datetime.isoformat()
+                is_dirty = repo.is_dirty()
+
+                logger.message("[Code Trace] Git Information:")
+                logger.message(f"  Branch : {branch}")
+                logger.message(f"  Commit : {commit_hash}")
+                logger.message(f"  Date   : {commit_time}")
+                logger.message(f"  Dirty  : {is_dirty}")
+
+                if is_dirty:
+                    trace_dir = osp.join(full_cfg.output_dir, "code_snapshot")
+                    os.makedirs(trace_dir, exist_ok=True)
+
+                    staged_diff = repo.git.diff("--cached")
+                    if len(staged_diff) > 0:
+                        staged_diff_path = osp.join(trace_dir, "staged.diff")
+                        with open(staged_diff_path, "w", encoding="utf-8") as f:
+                            f.write(staged_diff)
+                        logger.info(
+                            f"[Code Trace] Staged changes saved to: {staged_diff_path}"
+                        )
+                        logger.info(
+                            f"[Code Trace] To restore your code to this staged version, run: git apply {staged_diff_path}"
+                        )
+
+                    unstaged_diff = repo.git.diff()
+                    if len(unstaged_diff) > 0:
+                        unstaged_diff_path = osp.join(trace_dir, "unstaged.diff")
+                        with open(unstaged_diff_path, "w", encoding="utf-8") as f:
+                            f.write(unstaged_diff)
+                        logger.info(
+                            f"[Code Trace] Unstaged changes saved to: {unstaged_diff_path}"
+                        )
+                        logger.info(
+                            f"[Code Trace] To restore your code to this unstaged version, run: git apply {unstaged_diff_path}"
+                        )
+
+            except InvalidGitRepositoryError:
+                logger.warning("[Code Trace] Not a Git repository. Skipping.")
+            except Exception as e:
+                logger.warning(f"[Code Trace] Unexpected error: {e}")
diff --git a/ppsci/utils/config.py b/ppsci/utils/config.py
@@ -311,6 +311,7 @@ class SolverConfig(BaseModel):
             to_static: bool = False
             prim: bool = False
             log_level: Literal["debug", "info", "warning", "error"] = "info"
+            trace: bool = False
 
             # Training related config
             TRAIN: Optional[TrainConfig] = None
@@ -408,6 +409,7 @@ def use_wandb_check(cls, v, info: ValidationInfo):
             "to_static",
             "prim",
             "log_level",
+            "trace",
             "TRAIN.save_freq",
             "TRAIN.eval_during_train",
             "TRAIN.start_eval_epoch",
