Improve README

Axect · Axect · commit 902fcabdb284 · 2025-04-28T10:23:07.000+09:00
diff --git a/README.md b/README.md
@@ -2,18 +2,64 @@
 
 [English](README.md) | [한글](README_KR.md)
 
-This project provides a flexible template for PyTorch-based machine learning experiments.
-It includes configuration management using YAML files, logging with Weights & Biases (wandb), hyperparameter optimization with Optuna, custom learning rate schedulers, advanced pruning techniques, and a modular structure for easy customization and experimentation.
+A flexible and reusable template for PyTorch-based machine learning experiments. Streamline your workflow with YAML configurations, integrated hyperparameter optimization (Optuna), experiment tracking (Weights & Biases), custom components, and easy result analysis.
+
+## ✨ Key Features
+
+* **📄 YAML Configuration:** Easily manage all experiment settings (model, optimizer, scheduler, training parameters) using simple YAML files
+* **🚀 Hyperparameter Optimization:** Automatically find the best hyperparameters using Optuna integration
+* **📊 Experiment Tracking:** Log metrics, configurations, and models seamlessly with Weights & Biases
+* **✂️ Advanced Pruning:** Speed up optimization using custom pruners like the Predicted Final Loss (PFL) Pruner
+* **⚙️ Customizable Components:** Easily add or modify models ([`model.py`](model.py)), learning rate schedulers, optimizers, and the training loop ([`Trainer` in `util.py`](util.py)).
+* **📈 Analysis Tools:** Interactively load, analyze, and evaluate trained models and optimization results ([`analyze.py`](analyze.py)).
+* **🔄 Reproducibility:** Ensure consistent results with built-in seed management.
+
+## 🚀 Quick Start
+
+1.  **Create Your Repository:** Click "Use this template" on the GitHub page to create your own repository based on this template.
+2.  **Clone Your Repository:**
+    ```bash
+    git clone https://github.com/<your-username>/<your-new-repository-name>.git
+    cd <your-new-repository-name>
+    ```
+3.  **Set Up Environment & Install Dependencies:** (Using [uv](https://github.com/astral-sh/uv) is recommended)
+    ```bash
+    # Create and activate virtual environment
+    uv venv
+    source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
+
+    # Install requirements
+    uv pip sync requirements.txt
+    # Or using pip: pip install -r requirements.txt
+    ```
+4.  **(Optional) Login to Weights & Biases:**
+    ```bash
+    wandb login
+    ```
+5.  **Run a Default Experiment:**
+    ```bash
+    python main.py --run_config configs/run_template.yaml
+    ```
+6.  **Run Hyperparameter Optimization:**
+    ```bash
+    python main.py --run_config configs/run_template.yaml --optimize_config configs/optimize_template.yaml
+    ```
+7.  **Analyze Results:**
+    ```bash
+    python analyze.py
+    ```
+
+## 📖 Documentation
+
+For a deeper dive into the components and customization options, check out the detailed documentation:
+
+* **[Project Documentation](https://axect.github.io/pytorch_template)** (Covers Configuration, Execution, Training Loop, Model Definition, Optimization, Pruning, Analysis) (Generated by [Tutorial-Codebase-Knowledge](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge))
 
 ## Outline
 
 -   [PyTorch Template Project](#pytorch-template-project)
 -   [Project Structure](#project-structure)
 -   [Prerequisites](#prerequisites)
--   [Setup](#setup)
-    -   [1. Create Your Repository from this Template](#1-create-your-repository-from-this-template)
-    -   [2. Install dependencies](#2-install-dependencies)
-    -   [3. (Optional) Weights & Biases Setup](#3-optional-weights--biases-setup)
 -   [Usage](#usage)
     -   [1. Configure Your Run](#1-configure-your-run)
     -   [2. (Optional) Configure Optimization](#2-optional-configure-optimization)
@@ -57,46 +103,6 @@ It includes configuration management using YAML files, logging with Weights & Bi
 - Python 3.x
 - Git
 
-## Setup
-
-1.  **Create Your Repository from this Template:**
-    - Navigate to the main page of this repository on GitHub.
-    - Click the "Use this template" button (usually located near the top-right).
-    - Select "Create a new repository".
-    - Choose an owner, provide a repository name for your new project, and configure other options as needed.
-    - Click "Create repository from template".
-    - You now have a new repository in your account with a copy of this template's files. Clone *your* new repository to your local machine:
-      ```sh
-      git clone https://github.com/<your-username>/<your-new-repository-name>
-      cd <your-new-repository-name>
-      ```
-
-2.  **Install dependencies:**
-    It's recommended to use a virtual environment.
-    ```sh
-    # Create and activate a virtual environment (example using uv)
-    uv venv
-    source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
-
-    # Use uv (recommended)
-    uv pip sync requirements.txt
-
-    # Or use uv but install manually
-    uv pip install -U torch wandb rich beaupy polars numpy optuna matplotlib scienceplots
-
-    # Or use pip
-    pip install -r requirements.txt
-    ```
-    The requirements include PyTorch, wandb, Optuna, beaupy, and other necessary packages.
-
-3.  **(Optional) Weights & Biases Setup:**
-    If you want to use wandb for logging:
-    - Sign up for a free account at [https://wandb.ai/](https://wandb.ai/).
-    - Log in to your account in your terminal:
-      ```sh
-      wandb login
-      ```
-
 ## Usage
 
 1.  **Configure Your Run:**
diff --git a/README_KR.md b/README_KR.md
@@ -2,18 +2,64 @@
 
 [English](README.md) | [한글](README_KR.md)
 
-이 프로젝트는 PyTorch 기반 머신러닝 실험을 위한 유연한 템플릿을 제공합니다.
-YAML 파일을 이용한 설정 관리, Weights & Biases (wandb)를 사용한 로깅, Optuna를 이용한 하이퍼파라미터 최적화, 커스텀 학습률 스케줄러, 고급 프루닝 기법, 그리고 쉬운 커스터마이징과 실험을 위한 모듈식 구조를 포함합니다.
+PyTorch 기반 머신러닝 실험을 위한 유연하고 재사용 가능한 템플릿입니다. YAML 설정, 통합된 하이퍼파라미터 최적화(Optuna), 실험 추적(Weights & Biases), 커스텀 컴포넌트, 쉬운 결과 분석으로 워크플로우를 간소화하세요.
+
+## ✨ 주요 특징
+
+* **📄 YAML 설정:** 간단한 YAML 파일을 사용하여 모든 실험 설정(모델, 옵티마이저, 스케줄러, 학습 파라미터)을 쉽게 관리합니다.
+* **🚀 하이퍼파라미터 최적화:** Optuna 통합을 통해 최적의 하이퍼파라미터를 자동으로 찾습니다.
+* **📊 실험 추적:** Weights & Biases를 사용하여 메트릭, 설정, 모델을 원활하게 로깅합니다.
+* **✂️ 고급 프루닝:** Predicted Final Loss (PFL) Pruner와 같은 커스텀 프루너를 사용하여 최적화 속도를 높입니다.
+* **⚙️ 커스터마이징 가능한 컴포넌트:** 모델 ([`model.py`](model.py)), 학습률 스케줄러, 옵티마이저, 학습 루프 ([`Trainer` in `util.py`](util.py))를 쉽게 추가하거나 수정할 수 있습니다.
+* **📈 분석 도구:** 학습된 모델과 최적화 결과를 대화형으로 로드, 분석 및 평가합니다 ([`analyze.py`](analyze.py)).
+* **🔄 재현성:** 내장된 시드(seed) 관리를 통해 일관된 결과를 보장합니다.
+
+## 🚀 빠른 시작
+
+1.  **저장소 만들기:** GitHub 페이지에서 "Use this template"을 클릭하여 이 템플릿을 기반으로 자신의 저장소를 만듭니다.
+2.  **저장소 복제(Clone):**
+    ```bash
+    git clone https://github.com/<your-username>/<your-new-repository-name>.git
+    cd <your-new-repository-name>
+    ```
+3.  **환경 설정 및 의존성 설치:** ([uv](https://github.com/astral-sh/uv) 사용 권장)
+    ```bash
+    # 가상 환경 생성 및 활성화
+    uv venv
+    source .venv/bin/activate # Windows에서는 `.venv\Scripts\activate` 사용
+
+    # 의존성 설치
+    uv pip sync requirements.txt
+    # 또는 pip 사용: pip install -r requirements.txt
+    ```
+4.  **(선택) Weights & Biases 로그인:**
+    ```bash
+    wandb login
+    ```
+5.  **기본 실험 실행:**
+    ```bash
+    python main.py --run_config configs/run_template.yaml
+    ```
+6.  **하이퍼파라미터 최적화 실행:**
+    ```bash
+    python main.py --run_config configs/run_template.yaml --optimize_config configs/optimize_template.yaml
+    ```
+7.  **결과 분석:**
+    ```bash
+    python analyze.py
+    ```
+
+## 📖 문서
+
+컴포넌트 및 커스터마이징 옵션에 대한 자세한 내용은 상세 문서를 참조하세요:
+
+* **[프로젝트 문서](https://axect.github.io/pytorch_template)** (설정, 실행, 학습 루프, 모델 정의, 최적화, 프루닝, 분석 포함) (Generated by [Tutorial-Codebase-Knowledge](https://github.com/The-Pocket/Tutorial-Codebase-Knowledge))
 
 ## 목차
 
 -   [PyTorch Template 프로젝트](#pytorch-template-프로젝트)
 -   [프로젝트 구조](#프로젝트-구조)
 -   [사전 요구사항](#사전-요구사항)
--   [설정](#설정)
-    -   [1. 이 템플릿으로 저장소 만들기](#1-이-템플릿으로-저장소-만들기)
-    -   [2. 의존성 설치](#2-의존성-설치)
-    -   [3. (선택) Weights & Biases 설정](#3-선택-weights--biases-설정)
 -   [사용법](#사용법)
     -   [1. 실행 설정 구성](#1-실행-설정-구성)
     -   [2. (선택) 최적화 설정 구성](#2-선택-최적화-설정-구성)
@@ -58,46 +104,6 @@ YAML 파일을 이용한 설정 관리, Weights & Biases (wandb)를 사용한 
 -   Python 3.x
 -   Git
 
-## 설정
-
-1.  **이 템플릿으로 저장소 만들기:**
-    -   GitHub에서 이 저장소의 메인 페이지로 이동합니다.
-    -   "Use this template" 버튼 (보통 우측 상단 근처)을 클릭합니다.
-    -   "Create a new repository"를 선택합니다.
-    -   소유자를 선택하고, 새 프로젝트의 저장소 이름을 입력한 후, 필요에 따라 다른 옵션들을 설정합니다.
-    -   "Create repository from template"을 클릭합니다.
-    -   이제 당신의 계정에 이 템플릿 파일들의 복사본을 가진 새로운 저장소가 생성되었습니다. *당신의* 새 저장소를 로컬 컴퓨터에 복제(clone)하세요:
-      ```sh
-      git clone https://github.com/<your-username>/<your-new-repository-name>
-      cd <your-new-repository-name>
-      ```
-
-2.  **의존성 설치:**
-    가상 환경 사용을 권장합니다.
-    ```sh
-    # 가상 환경 생성 및 활성화 (uv 사용 예시)
-    uv venv
-    source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
-
-    # uv 사용 (권장)
-    uv pip sync requirements.txt
-
-    # 또는 uv 사용시 직접 설치 (권장)
-    uv pip install -U torch wandb rich beaupy polars numpy optuna matplotlib scienceplots
-
-    # 또는 pip 사용
-    pip install -r requirements.txt
-    ```
-    의존성에는 PyTorch, wandb, Optuna, beaupy 및 기타 필요한 패키지들이 포함됩니다.
-
-3.  **(선택) Weights & Biases 설정:**
-    로깅에 wandb를 사용하려면:
-    -   [https://wandb.ai/](https://wandb.ai/)에서 무료 계정에 가입합니다.
-    -   터미널에서 계정에 로그인합니다:
-      ```sh
-      wandb login
-      ```
-
 ## 사용법
 
 1.  **실행 설정 구성:**
@@ -229,7 +235,7 @@ scheduler_config: # 필요시 스케줄러 파라미터 조정 (예: 에폭 또
 python main.py --run_config configs/run_mlp_small_fastlr.yaml
 ```
 
-### 2\. 최적화 탐색 공간 커스터마이징
+### 2. 최적화 탐색 공간 커스터마이징
 
 최적화 설정 파일(예: `configs/optimize_template.yaml`)의 `search_space` 섹션을 수정하여 Optuna가 탐색할 하이퍼파라미터와 그 범위/선택지를 변경합니다.
 
@@ -301,7 +307,7 @@ search_space:
 
 이 업데이트된 설정은 다른 노드 크기, 레이어 수, 학습률 및 스케줄러 파라미터에 대해 탐색을 수행합니다.
 
-### 3\. 다른 Optuna Sampler 사용하기 (예: GridSampler)
+### 3. 다른 Optuna Sampler 사용하기 (예: GridSampler)
 
 `configs/optimize_template.yaml`의 `sampler` 섹션을 수정하여 Optuna가 사용하는 샘플러를 변경할 수 있습니다.
 
@@ -357,17 +363,17 @@ search_space:
 
 **조건:** `GridSampler`를 사용하려면 `search_space` 아래에 나열된 *모든* 파라미터가 `type: categorical`인지 확인하세요. 코드는 이 조건이 충족될 경우에만 `GridSampler`에 필요한 형식을 자동으로 구성합니다.
 
-### 4\. 커스텀 모델, 옵티마이저, 스케줄러, 프루너 추가하기
+### 4. 커스텀 모델, 옵티마이저, 스케줄러, 프루너 추가하기
 
   - **모델:** `model.py` 또는 새 Python 파일에 모델 클래스(`torch.nn.Module` 상속)를 만듭니다. `__init__` 메서드가 첫 번째 인수로 설정 딕셔너리(예: YAML의 `net_config`)를 받도록 합니다. 실행 설정 YAML에서 `net:` 경로를 업데이트합니다.
   - **옵티마이저/스케줄러:** 커스텀 클래스를 구현하거나 `torch.optim` 또는 다른 곳(예: `hyperbolic_lr.py`)의 기존 클래스를 사용합니다. YAML에서 `optimizer:` 또는 `scheduler:` 경로와 `*_config` 딕셔너리를 업데이트합니다. 템플릿은 제공된 경로를 기반으로 클래스를 동적으로 로드하기 위해 `importlib`를 사용합니다.
   - **프루너:** `pruner.py` 또는 새 파일에 프루너 클래스(`pruner.BasePruner` 상속 또는 Optuna 프루너 인터페이스 구현)를 만듭니다. 최적화 YAML의 `pruner:` 섹션을 업데이트합니다.
 
-### 5\. 데이터 로딩 커스터마이징
+### 5. 데이터 로딩 커스터마이징
 
   - `util.py`의 `load_data` 함수를 수정하여 특정 데이터셋을 로드합니다. 이 함수는 학습 및 검증용 PyTorch `Dataset` 객체를 반환해야 합니다.
 
-### 6\. 학습 루프 커스터마이징
+### 6. 학습 루프 커스터마이징
 
   - `util.py`의 `Trainer` 클래스를 수정합니다. 특정 작업, 손실 함수 또는 메트릭에 맞게 `train_epoch`, `val_epoch`, `train` 메서드를 조정합니다. 해당되는 경우, `train` 메서드가 최적화 설정의 `metric`으로 지정된 값을 반환하도록 합니다.
 
@@ -441,3 +447,4 @@ pruner:
 6.  시도가 완료되면 최종 검증 손실과 `pfl`이 `top_k` 목록 포함 여부를 결정하는 데 고려됩니다.
 
 </details>
+
