kskimlab

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

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 설치 방법을 사용한다.

python -m pip install "kskimlab[arpes]"

python은 사용할 환경의 Python이어야 한다. Igor 연동에는 Igor에서 선택한 환경에 패키지를 설치해야 한다. 예를 들어 D:/IgorEnv/.venv 환경이 이미 있다면 Igor를 종료한 뒤 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를 복사하지 않는다.

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

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

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 경로를 지정한다.

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

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

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 설치

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 설치 안내를 따른다.

Igor에서 분석

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

// 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에서 재사용

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(...)로 저장하면 다른 환경에서 후속 분석하기 쉽다.

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 튜토리얼에 모델 계약과 설정을 설명했다.

새 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를 별도로 제외해야 한다.

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 지원은 별도의 명시적 정책을 요구한다.

개발과 배포

# 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 공식 안내를 따른다. 같은 파일 이름은 덮어쓸 수 없으므로 게시 후 수정할 때는 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 라이선스로 배포한다. 저작권 표기는 Copyright (c) 2026 Yoonseok Oh이다. 전체 라이선스는 소스의 LICENSE와 설치된 패키지의 배포 메타데이터에 포함된다. 외부 의존성은 각 프로젝트의 라이선스를 따른다.