localPDF マニュアル

1. このプロジェクトの目的

webPDF は、Web ブラウザ上の画面から実験データ、バックグラウンド、計算条件を入力し、ボタン操作によって S(Q) や G(r) などを計算する PyScript ベースのアプリケーションである。

localPDF の基本目的は、この Web 画面を使わずに、ローカルの Python プログラムから API を呼び出して、Web 版と同じ計算コアを利用することである。

したがって、基本構造は次のように理解する。

Web 版

HTML / Web UI
    ↓
webPDF/main.py
    ↓
webPDF/calc_pdf.py
    ↓
PDF 計算


local 版

Python program
    ↓
LocalPDF API
    ↓
Local_Calc_PDF_from_xy
    ↓
webPDF/calc_pdf.py
    ↓
PDF 計算

localPDF は PDF 計算アルゴリズムを別に実装したものではない。Web 版の計算コアを再利用し、Web UI が担当していた入力・設定・実行制御・結果取得を Python API から行えるようにした層である。

本書では、この「実験データから PDF を計算する localPDF 本体」を扱う。構造モデルから S(Q) を計算する試験的な追加機能は本体とは分離し、別文書 SQ_EXPERIMENTAL.md に記載する。

2. ファイル構成と責務

localPDF 本体を理解するうえで重要なファイルは次のとおり。

webPDF/
├── main.py          Web UI と計算コアを接続する処理
└── calc_pdf.py      PDF 数値計算コア

localPDF/
├── config.py        Web 版 config JSON を Python オブジェクトとして保持
├── local_calc_pdf.py
│                    Web 版 calc_pdf.py をローカル CPython から使うブリッジ
├── local_pdf.py     利用者向けの中心 API
└── local_pdf_plot.py
                     Bokeh による可視化 API

利用者が通常直接扱うのは、原則として次の3クラスである。

Config
LocalPDF
LocalPDFPlot

Local_Calc_PDF_from_xy は内部ブリッジであり、通常の利用コードから直接操作する必要はない。

3. webPDF と localPDF の対応

Web 版では、HTML 上の入力欄やボタンを webPDF/main.py が受け取り、Calc_PDF_from_xy に値を設定して計算を実行する。

local 版では、この役割を Config と LocalPDF が担当する。

Web UI                     local Python
----------------------     ----------------------
config upload              Config
data file upload           LocalPDF.load_xy()
background upload          LocalPDF.load_bg_xy()
Calculation of S(Q)        LocalPDF の計算 API
Calculation of G(r)        LocalPDF の計算 API
Download data              LocalPDF.save_*()
Bokeh plot                 LocalPDFPlot

最も重要なのは、計算コアが共通である点である。

                         ┌─ Web UI / main.py
Calc_PDF_from_xy  ←──────┤
                         └─ LocalPDF / local_calc_pdf.py

4. Config

Config は Web 版でアップロードしていた JSON config をローカル Python 側で保持するためのデータクラスである。

from localPDF import Config

config = Config("SiO2_LabAgSource.json")

主な属性は次のとおり。

属性意味

bg_factor background factor atomList 原子番号リスト atomConc 原子組成 energy_keV X-ray energy [keV] density density pol polarization factor recoil recoil factor norm_min normalization Q range 下限 norm_max normalization Q range 上限 r_max r の最大値 dr Δr r_cut cutoff distance

JSON のキーは Web 版との互換性を意識している。

LocalPDF は計算開始前に _apply_config_to_calc() を呼び、これらを Web 版計算コアへ設定する。

5. LocalPDF

5.1 役割

LocalPDF は local 版の中心となる facade である。

主な責務は、

Config の保持
計算コアの生成
config 値の計算コアへの設定
実験データの読み込み
background の読み込み
計算実行
計算結果の取得
結果ファイルの保存

である。

内部では、

self._pdf = Local_Calc_PDF_from_xy()

を保持する。

5.2 初期化

推奨形は次である。

from localPDF import Config, LocalPDF

config = Config("config.json")
pdf = LocalPDF(config=config)

LocalPDF(json_path="config.json") として直接 JSON path を渡すこともできる。

6. 入力

6.1 実験データ

pdf.load_xy("data.dat")

2列データを numpy.loadtxt() で読み、

1列目 → two-theta
2列目 → intensity

として計算コアへ設定する。

6.2 background

pdf.load_bg_xy("background.dat", factor=1.0)

background も2列データとして読み込む。

factor を指定すると、計算に使用する background factor も同時に設定される。

background がない場合は load_bg_xy() を呼ばない。

7. 標準計算フロー

現在の example で採用されている標準的な計算は、

pdf.run_all()
pdf.run_bft()

である。

7.1 run_all()

run_all() は Web 版計算コアの All_run() を実行する。

内部の主要な流れは、

two-theta
   ↓
Q 変換
   ↓
異常分散項の取得
   ↓
background / polarization 補正
   ↓
Compton 計算
   ↓
atomic form factor
   ↓
規格化
   ↓
i(Q), S(Q)
   ↓
補間
   ↓
FFT
   ↓
G(r) 等

である。

7.2 run_bft()

pdf.run_bft()

は Web 版計算コアの BFT_smooth() を呼び出す。

コード上では、

Rcut_and_bFT()
UseSmoothBG()
CalcGrFFT()
CalcGrLorch()

が実行される。

したがって通常利用では、

pdf.run_all()
pdf.run_bft()

を一組として扱うのが最も分かりやすい。

8. 結果取得

計算後の代表的な取得 API は次のとおり。

q, iq = pdf.get_iq()
q, sq = pdf.get_sq()

r, gr = pdf.get_gr()
r, gr_lorch = pdf.get_gr_lorch()

r, ggr = pdf.get_ggr()
r, ggr_lorch = pdf.get_ggr_lorch()

強度補正過程も取得できる。

tt, raw = pdf.get_intensity_raw()
tt, bg = pdf.get_intensity_bg()
tt, bg_scaled = pdf.get_intensity_bg_scaled()
tt, subtracted = pdf.get_intensity_subtracted()
q, corrected = pdf.get_intensity_corrected()
q, normalized = pdf.get_intensity_corrected_normalized()

form factor / Compton 成分は、

q, f2sum, comp_total, total = pdf.get_formfactor_components()

で取得する。

9. ファイル保存

pdf.save_iq("iq.dat")
pdf.save_sq("sq.dat")
pdf.save_gr("gr.dat")
pdf.save_gr_lorch("gr_lorch.dat")

いずれも2列データとして保存される。

これは Web 版で download していた計算結果を、ローカル Python から直接ファイル化するための API と考えればよい。

10. LocalPDFPlot

LocalPDFPlot は計算ではなく表示を担当する。

from localPDF import LocalPDFPlot

view = LocalPDFPlot(local_pdf=pdf)
view.view_all()

主なメソッドは、

view_raw()
view_sq()
view_iq_components()
view_gr()
view_gr_lorch()
view_all()

である。

現状の view_sq() では S(Q)/i(Q) の line 描画部分がコメントアウトされているため、枠のみ生成される。この点は現在のコード状態として認識しておく必要がある。

11. local_calc_pdf.py

local_calc_pdf.py は Web 版計算コアをローカル CPython で利用するための互換ブリッジである。

主な処理は、

pyodide.http.open_url のローカル用 stub
js module の stub
資源ファイル探索
numpy.loadtxt / numpy.genfromtxt の path 解決
SciPy API の互換処理
webPDF.calc_pdf.Calc_PDF_from_xy の継承

である。

したがって、

LocalPDF
   ↓
Local_Calc_PDF_from_xy
   ↓ inheritance
webPDF.calc_pdf.Calc_PDF_from_xy

となる。

計算アルゴリズムそのものを local 側に複製しているわけではない。

12. 内部 API と利用者向け API の区別

通常利用では LocalPDF.pdf から内部の Calc_PDF_from_xy を直接操作しない。

例えば example にある、

print(pdf.pdf.nn_min)

はデバッグ・確認用途である。

基本的には、

pdf.load_xy(...)
pdf.run_all()
pdf.run_bft()
q, sq = pdf.get_sq()

のように LocalPDF の公開メソッドだけで操作する。

内部アルゴリズムを調査・変更するときに初めて、

LocalPDF.pdf
Local_Calc_PDF_from_xy
Calc_PDF_from_xy

へ降りる。

13. コードを読む順番

localPDF の基本機能を理解し直す場合は、

example/main_local.py
        ↓
local_pdf.py
        ↓
config.py
        ↓
local_calc_pdf.py
        ↓
webPDF/calc_pdf.py
        ↓
local_pdf_plot.py
        ↓
webPDF/main.py

の順が分かりやすい。

webPDF/main.py は Web UI、PyScript、Bokeh、download 処理まで含むため、最初から読むより、local 側 API の対応先を確認する目的で読む方がよい。

14. 最小限覚えること

localPDF 本体について、まず次だけ覚えておけば通常利用できる。

config = Config("config.json")
pdf = LocalPDF(config=config)

pdf.load_xy("data.dat")
pdf.load_bg_xy("background.dat", factor=1.0)  # 必要な場合のみ

pdf.run_all()
pdf.run_bft()

q, sq = pdf.get_sq()
r, gr = pdf.get_gr_lorch()

pdf.save_sq("sq.dat")
pdf.save_gr_lorch("gr_lorch.dat")

つまり、

Config
  ↓
LocalPDF
  ↓
load
  ↓
run_all
  ↓
run_bft
  ↓
get / save

が localPDF の基本利用モデルである。