62 lines
4.1 KiB
Markdown
62 lines
4.1 KiB
Markdown
# `res-*`, `ppr-*` (연구/논문) Repository README 작성 가이드
|
|
|
|
`res-*` (research) 또는 `ppr-*` (paper) 접두사가 붙은 저장소는 특정 학술 연구나 논문의 실험 코드를 관리합니다. README의 핵심 목표는 제3자가 해당 연구의 실험 결과를 정확하게 재현(reproduce)하고, 나아가 확장(extend)할 수 있도록 상세하고 명확한 가이드를 제공하는 것입니다.
|
|
|
|
---
|
|
|
|
### 1. 연구 개요 (Research Overview)
|
|
- **논문 정보 (Citation)**:
|
|
- **제목**: 연구 논문의 전체 제목
|
|
- **저자**: 모든 저자 목록
|
|
- **학회/저널**: 논문이 발표된 학회나 저널 정보 (예: `NeurIPS 2023`)
|
|
- **링크**: 논문 PDF나 arXiv 링크를 반드시 포함합니다.
|
|
- **BibTeX 인용**: 다른 연구자가 쉽게 인용할 수 있도록 BibTeX 형식을 제공합니다.
|
|
- **연구 배경 및 가설 (Background and Hypothesis)**:
|
|
- 이 연구가 해결하고자 하는 문제가 무엇인지 간략히 설명합니다.
|
|
- 연구를 통해 검증하고자 했던 핵심 가설을 명확히 기술합니다.
|
|
|
|
### 2. 실험 환경 설정 (Setup for Reproducibility)
|
|
- **목적**: 논문에 기술된 실험 결과를 그대로 재현하는 데 필요한 모든 환경 정보를 제공합니다.
|
|
- **필수 구성 요소**:
|
|
- **하드웨어 요구사항**: GPU 종류(예: `NVIDIA A100`), 메모리(RAM, VRAM) 등 실험에 사용된 하드웨어 스펙을 명시합니다.
|
|
- **소프트웨어 의존성**:
|
|
- `requirements.txt` (Python), `environment.yml` (Conda) 등 패키지 목록을 제공합니다.
|
|
- CUDA, cuDNN 버전과 같이 시스템 레벨의 의존성을 명확히 표기합니다.
|
|
- Docker를 사용한 경우, `Dockerfile`과 빌드 및 실행 방법을 안내하는 것이 가장 좋습니다.
|
|
- **데이터셋 준비**:
|
|
- 원본 데이터셋을 다운로드하는 링크와 스크립트를 제공합니다.
|
|
- 데이터 전처리가 필요한 경우, `bash scripts/preprocess_data.sh` 와 같이 실행 명령어를 안내하고, 예상 소요 시간을 명시합니다.
|
|
|
|
### 3. 실험 재현 스크립트 (Reproduction Scripts)
|
|
- **목적**: 논문에 보고된 주요 실험 결과를 재현하는 스크립트와 실행 방법을 안내합니다.
|
|
- **핵심 실험별 가이드**:
|
|
- **모델 학습 (Training)**:
|
|
```bash
|
|
# Table 1의 ResNet-50 모델 학습 재현
|
|
python train.py --config configs/resnet50_cifar10.yaml --output_dir results/resnet50
|
|
```
|
|
- **모델 평가 (Evaluation)**:
|
|
```bash
|
|
# 사전 학습된 모델 가중치로 Figure 2의 정확도 평가 재현
|
|
python evaluate.py --checkpoint_path pretrained_models/resnet50.pth --config configs/resnet50_cifar10.yaml
|
|
```
|
|
- **사전 학습된 모델 (Pre-trained Models)**:
|
|
- 논문에서 사용한 모델의 가중치 파일을 다운로드할 수 있는 링크(예: Google Drive, Hugging Face Hub)를 제공합니다. 이는 전체 학습 과정을 생략하고 평가만 진행하려는 사용자에게 매우 유용합니다.
|
|
|
|
### 4. 코드 구조 (Codebase Structure)
|
|
- **목적**: 전체 코드베이스의 디렉토리 구조와 각 파일의 역할을 설명하여, 다른 연구자가 코드를 이해하고 수정하거나 확장하기 용이하게 만듭니다.
|
|
- **예시**:
|
|
```plaintext
|
|
/
|
|
├── configs/ # 실험 설정 파일 (YAML, JSON)
|
|
├── data/ # 데이터 로더 및 전처리 코드
|
|
├── models/ # 모델 아키텍처 정의
|
|
├── scripts/ # 데이터 준비, 실험 실행 쉘 스크립트
|
|
├── src/ or lib/ # 핵심 로직 및 유틸리티 함수
|
|
├── train.py # 모델 학습 스크립트
|
|
└── evaluate.py # 모델 평가 스크립트
|
|
```
|
|
|
|
### 5. 기대 결과 (Expected Results)
|
|
- **목적**: 사용자가 스크립트를 올바르게 실행했는지 확인할 수 있도록, 논문에 보고된 결과(예: 정확도, 손실 값)를 명시합니다.
|
|
- **팁**: 특정 실험 스크립트 실행 후 출력되는 로그 예시나, 생성되는 결과 파일의 형태를 보여주면 좋습니다. |