Metadata-Version: 2.4
Name: kskimlab
Version: 0.1.0
Summary: ARPES and tight-binding workflows with optional Igor Pro integration
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=2.0
Provides-Extra: arpes
Requires-Dist: erlab==3.23.2; extra == "arpes"
Requires-Dist: xarray>=2025.11.0; extra == "arpes"
Requires-Dist: scipy<2,>=1.15; extra == "arpes"
Requires-Dist: joblib<2,>=1.5.3; extra == "arpes"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# kskimlab

Igor Pro에서 취득한 ARPES 데이터를 Python으로 분석하고 결과를 Igor Wave로 돌려주는 패키지다. Fermi 보정, k-space 변환, 대칭 분석, hv scan 및 tight-binding 계산을 제공한다. 개별 Python 스크립트나 소스 폴더 경로 등록 없이 설치된 패키지를 호출한다.

```igorpro
Python execute = "import kskimlab; kskimlab.apply_fermi_correction_to_data('root:sample', 'root:sample_k', 'root:gold')"
```

## 설치

Python 3.11 이상이 필요하다. Igor 연동은 Igor Pro 10 내부 Python에서 실행한다. 일반 Python/Jupyter에서는 Igor 없이 배열 기반 분석과 tight-binding 계산을 사용할 수 있다.

PyPI에 게시된 릴리스는 아래 명령으로 설치할 수 있다. 설치하는 사용자는 Git, GitHub 계정, SSH 키가 필요 없다. 아직 게시하지 않은 버전을 시험할 때는 로컬 wheel 설치 방법을 사용한다.

```powershell
python -m pip install "kskimlab[arpes]"
```

`python`은 사용할 환경의 Python이어야 한다. Igor 연동에는 Igor에서 선택한 환경에 패키지를 설치해야 한다. 예를 들어 `D:/IgorEnv/.venv` 환경이 이미 있다면 Igor를 종료한 뒤 PowerShell에서 실행한다.

```powershell
& "D:/IgorEnv/.venv/Scripts/python.exe" -m pip install --upgrade "kskimlab[arpes]"
& "D:/IgorEnv/.venv/Scripts/python.exe" -I -c "import kskimlab; print(kskimlab.__version__); print(kskimlab.__file__)"
```

출력 경로가 해당 환경의 `Lib/site-packages/kskimlab/` 아래인지 확인한다. 기존 작업 소스 경로가 나오면 이전 `.pth` 또는 editable 설치가 연결되어 있는지 확인한다.

환경을 처음 만드는 경우, 기존 `D:/IgorEnv` 폴더를 준비하고 Igor의 Python Settings에서 지원되는 기본 Python을 선택한다. Python Console을 열기 전에 Igor 명령창에서 다음을 실행한 뒤 Igor를 종료하고 위 설치 명령을 실행한다. 다른 PC의 `.venv`를 복사하지 않는다.

```igorpro
NewPath/O/Q kskimlabEnv, "D:IgorEnv:"
PythonEnv/P=kskimlabEnv venv = ".venv"
```

설치 후 Igor를 다시 열어 Python 시작 전에 환경을 선택한다.

```igorpro
NewPath/O/Q kskimlabEnv, "D:IgorEnv:"
PythonEnv/P=kskimlabEnv activate = ".venv"
Python execute = "import kskimlab; print(kskimlab.__version__); print(kskimlab.__file__)"
```

`D:/IgorEnv/.venv/share/kskimlab/igor/`의 `arpes_bridge.ipf`와 `tight_binding.ipf`를 필요한 실험에서 열고 컴파일한다. pip으로 설치를 마쳤다면 IPF의 `Install()`을 다시 실행하지 않는다. 환경 선택은 분석 함수 호출마다 반복할 필요가 없으며, 이미 Python이 시작된 상태에서 환경을 바꾸려면 Igor를 재시작한다.

### Igor Pro에서 로컬 wheel 설치

배포받은 `arpes_bridge.ipf`를 Igor에 열고 컴파일한다. Python Console을 열기 **전에**, 이미 존재하는 환경 폴더와 wheel 경로를 지정한다.

```igorpro
Install("D:/IgorEnv", packageSource="D:/Downloads/kskimlab-0.1.0-py3-none-any.whl")
```

`D:/IgorEnv/.venv`를 생성 또는 재사용하여 `[arpes]` 의존성과 패키지를 설치한다. 의존성 다운로드에는 인터넷 연결이 필요하다. 설치 후 Igor를 재시작한다. 새 실험에서 환경이 선택되지 않았다면 Python 시작 전에 다음을 실행한다.

```igorpro
NewPath/O/Q kskimlabEnv, "D:IgorEnv:"
PythonEnv/P=kskimlabEnv activate = ".venv"
Python execute = "import kskimlab; print(kskimlab.__version__)"
```

설치 도우미는 Windows용이다. 일반 Python에 설치하는 것만으로 Igor의 별도 환경에도 설치되지는 않는다. 업데이트는 같은 `Install` 명령에 새 wheel을 지정하고 재시작한다. 설치한 Python 환경의 `share/kskimlab/igor/`에도 두 IPF가 포함된다.

### 일반 Python에서 로컬 wheel 설치

```powershell
python -m pip install "D:/Downloads/kskimlab-0.1.0-py3-none-any.whl[arpes]"
```

Tight-binding만 필요하면 `[arpes]`를 생략한다. 기본 의존성은 NumPy이며 ERLab은 사용 시에만 import된다. `igorpro`는 pip 의존성이 아니라 Igor가 제공하는 모듈이다. 로컬 wheel과 extras 설치 구문은 [pip 설치 안내](https://pip.pypa.io/en/stable/user_guide/#installing-from-wheels)를 따른다.

## Igor에서 분석

아래 명령은 각각 한 줄로 실행할 수 있다. 출력 Wave가 이미 있으면 기존 동작대로 덮어쓰므로 보존할 데이터에는 다른 출력 이름을 사용한다.

```igorpro
// External Gold correction and k-space conversion.
Python execute = "import kskimlab; kskimlab.apply_fermi_correction_to_data('root:sample', 'root:sample_k', 'root:gold')"

// Self-Fermi correction and k-space conversion.
Python execute = "import kskimlab; kskimlab.apply_fermi_correction_to_data('root:sample', 'root:sample_k')"

// Batch conversion with a shared Gold reference.
Python execute = "import kskimlab; kskimlab.convert_data_folder_with_gold('root:gold', 'root:data', 'root:converted')"

// Photon-energy scan.
Python execute = "import kskimlab; kskimlab.process_hv_scan('root:hvscan', 'converted')"

// Symmetry inspection.
Python execute = "import kskimlab; kskimlab.check_symmetry_only('root:sample')"

// SSRL batch conversion grouped by deflector angle and temperature.
Python execute = "import kskimlab; kskimlab.convert_ssrl_data_by_theta_y('root:golds', 'root:data', 'root:converted')"
```

기존 IPF 함수 `CorrectFermiEdge`, `CorrectFermiEdgeQuick`, `CheckSymmetry3D`, `ConvertDataFolderWithGold`, `ConvertSSRLDataByDeflector`, `ConvertHvScanToKz`도 그대로 사용할 수 있다. Wave note 복사는 이제 Python 패키지가 처리하므로 별도의 사용자 정의 IPF note 함수는 필요 없다.

ALS/SSRL은 Wave note로 자동 판별한다. 기존 2D/3D Gold, self-Fermi, hv scan의 계산식·축 규약·피팅 설정은 유지한다. 패키지는 호출할 때마다 자동 reload하지 않으므로 업데이트 후 Python/Igor를 재시작한다.

## Python에서 재사용

```python
import kskimlab

# Inside Igor's Python: raw acquisition Wave -> canonical DataArray.
data = kskimlab.load_raw_igor_wave_as_da("root:sample")
gold = kskimlab.load_raw_igor_wave_as_da("root:gold")
converted = kskimlab.correct_and_convert_to_kspace(data, gold)
kskimlab.save_da_to_igor_wave(converted, "root:sample_k")
```

`correct_and_convert_to_kspace(data, gold_data=None)`는 Igor를 호출하지 않고 `xarray.DataArray`를 받아 결과를 반환한다. Igor 밖에서는 같은 규약의 배열을 직접 제공한다. 입력은 `(eV, alpha)` 또는 `(eV, alpha, beta)` 차원과 기존 어댑터의 축 부호, `hv`·`xi`·`beta` 좌표, `sample_temp`·`hv` 속성을 가져야 한다. 원시 데이터용 loader를 이미 변환된 k-E Wave에 적용하면 안 된다. 결과를 `DataArray`로 유지하거나 `converted.to_netcdf(...)`로 저장하면 다른 환경에서 후속 분석하기 쉽다.

```python
import kskimlab
from kskimlab import tight_binding

# Disable mirroring unless the full eigensystem obeys the assumed symmetry.
tight_binding.KX_SYMMETRIC = False
tight_binding.KY_SYMMETRIC = False
result = kskimlab.calculate_tight_binding(2, "Graphene", precision_level=20)
energies = result.eigenvalues
```

Igor에서는 `tight_binding.ipf`를 열고 `TightBinding(2, "Graphene")`를 실행하면 계산 결과와 band plot을 얻는다. [Tight-binding 튜토리얼](TIGHT_BINDING_TUTORIAL.md)에 모델 계약과 설정을 설명했다.

## 새 Hamiltonian과 빔라인

배포판에는 `Graphene`과 `sample_model`만 포함된다. 로컬의 `WS2_Bulk_wSOC` 모델은 wheel과 소스 배포판에서 제외한다. 내장 모델은 `kskimlab/hamiltonians/`에 있다. 개인 모델은 설치된 패키지를 수정하지 말고 별도 폴더에 둔다. `sample_model.py`를 복사하여 `build_hamiltonian(kx, ky, kz)`만 공개한다.

제외 규칙은 `build_support.py`와 `MANIFEST.in`에 있다. 로컬·editable 설치에서는 WS₂ 모델을 계속 사용할 수 있다. 이 규칙은 GitHub 업로드에는 적용되지 않으므로, 소스를 공개할 때는 WS₂ 원본과 호환 모듈 및 `WS2.ipf`를 별도로 제외해야 한다.

```igorpro
Python execute = "import kskimlab; kskimlab.add_model_directory('D:/MyModels')"
TightBinding(2, "MyModel")
```

등록은 Python 세션마다 한 번 필요하다. 동일 이름이 여러 폴더에 있으면 오류로 처리하며, 현재 작업 폴더를 자동 검색하지 않는다. 모델 파일은 Python 코드를 실행하므로 신뢰하는 폴더만 등록한다. Python에서는 등록 대신 `calculate_tight_binding(2, build_hamiltonian)`처럼 함수를 직접 넘겨도 된다.

새 빔라인은 `kskimlab.arpes_igor_io.BeamlineAdapter` 규약을 구현하고 `kskimlab.register_beamline_adapter(adapter)`로 등록한다. 원시 축 해석과 Wave-note 판별은 어댑터에 두고 계산·대칭 모듈과 분리한다. hv scan 지원은 별도의 명시적 정책을 요구한다.

## 개발과 배포

```powershell
# Run from the source checkout.
python -m pip install -e ".[arpes,dev]"
python -m unittest discover -s tests -v
python -m build
```

`dist/`에 wheel과 소스 배포판이 생성된다. 사용자는 설치된 패키지와 IPF를 사용하며 개별 Python 스크립트를 받을 필요가 없다. 공개 업로드 전에는 배포 권한과 라이선스, PyPI 프로젝트 이름, 실제 archive 내용을 확인한다. TestPyPI도 공개 서버이므로 비공개 데이터나 모델을 업로드하지 않는다.

배포 파일을 새 폴더에 만들고 `twine check`로 메타데이터와 README를 검사한 뒤, 작업 소스와 연결되지 않은 새 환경에서 wheel을 설치해 테스트한다. 이 프로젝트의 `dist/`에는 업로드 대상이 아닌 ZIP도 있을 수 있으므로 `twine upload dist/*`를 사용하지 말고 검증한 `.whl`과 `.tar.gz` 두 파일을 명시한다. 업로드 방법은 [PyPI 공식 안내](https://docs.pypi.org/publishing/publishing-to-pypi/)를 따른다. 같은 파일 이름은 덮어쓸 수 없으므로 게시 후 수정할 때는 `pyproject.toml`과 `kskimlab/__init__.py`의 버전을 함께 올리고 다시 빌드한다.

`pyproject.toml`이 설치 의존성의 기준이다. ARPES는 기존 API 사용을 보존하기 위해 ERLab 3.23.2로 고정했다. `requirements.txt`는 이전 전체 환경의 스냅샷으로 남겨 두며 일반 설치에서는 사용하지 않는다. 패키지에 새 의존성이 생기면 `pyproject.toml`도 업데이트한다.

실제 구현은 `kskimlab/` 아래에 있다. 최상위 `arpes_bridge.py`, `arpes_igor_io.py`, `arpes_symmetry.py`, `ssrl_deflector_batch.py`, `tight_binding.py`, `hamiltonian.py`는 예전 import를 위한 호환 모듈이다. 전역 설정 변경도 동일한 패키지 모듈에 반영된다. 코드 수정은 `kskimlab/` 내부에서 한다. `Install("D:/igor_python")`은 로컬 프로젝트의 **일반 설치**이며 개발용 editable 설치는 아니다.

단위 테스트는 mock Igor API와 합성 배열을 사용한다. 실제 Igor UI, 실험 데이터 및 새 환경의 전체 의존성 설치 검증은 별도로 수행해야 한다.

## 라이선스

kskimlab은 [MIT 라이선스](https://opensource.org/license/mit)로 배포한다. 저작권 표기는 `Copyright (c) 2026 Yoonseok Oh`이다. 전체 라이선스는 소스의 `LICENSE`와 설치된 패키지의 배포 메타데이터에 포함된다. 외부 의존성은 각 프로젝트의 라이선스를 따른다.
