localPDF / RustPDF Python I/F 対応マニュアル

1. 対象

この文書は、実験 X 線散乱データを PDF へ変換する Python I/F について、 localPDF.LocalPDF と rust_pdf.RustPDF の対応だけをまとめる。

数値実装を同一化する文書ではない。同じ物理操作・同じ物理量だけ公開名を揃える。

2. 共通利用形

localPDF:

from localPDF import Config
from localPDF import LocalPDF

config = Config("config.json")
pdf = LocalPDF(config=config)
pdf.load_xy("data.dat")
pdf.run_all()
pdf.run_bft()

RustPDF:

from rust_pdf import Config
from rust_pdf import RustPDF

config = Config("config.json")
pdf = RustPDF(config=config)
pdf.load_xy("data.dat")
pdf.run_all()

Rust は pipeline 一回で bFT/Lorch まで生成するため、 localPDF の run_bft() に相当する別計算を追加しない。

3. 共通 getter

get_iq()         raw i(Q)
get_sq()         S(Q) = i(Q) + 1
get_gr()         reduced PDF G(r)
get_gr_lorch()   Lorch G(r)
get_ggr()        pair distribution g(r)
get_ggr_lorch()  Lorch g(r)

get_gr() を g(r) の意味にはしない。 webPDF の _Gr が G(r)、_ggr が g(r) であることを基準にする。

4. Config

localPDF の Config は webPDF JSON を Python object 化する。

RustPDF の Config はそれに加えて Rust optimizer の parameter tree を保持する。 Rust の fit-enabled scalar:

{
  "value": 0.55,
  "constraint": {
    "min": 0.4,
    "max": 0.8
  }
}

を平坦化しない。

この差は Rust optimizer を利用するために必要な差であり、同じ物理 parameter の property 名は可能な範囲で揃える。

5. Rust 固有 optimizer

localPDF に対応機能がないため、optimizer は RustPDF 固有 API とする。

pdf.optimize()
pdf.run_all()

または

pdf.quick_optimize()
pdf.run_all()

通常 optimize と quick optimize の差は Rust optimize.rs に由来する。

通常 optimize:

bounded parameter なし: 現在値から LM 1回。
bounded parameter あり: Halton 512 sample → 上位5点 → 各点から LM → 最良結果。

quick optimize:

Halton search なし。
現在値から LM 1回。

どちらも最適化済み parameters を返す。高レベル RustPDF はその parameter tree を自身の Config に反映する。

6. low-level Rust I/F

高レベル I/F と独立して以下を維持する。

version()
run()
optimize()
quick_optimize()
to_gr()
to_tr()
to_rdf()
to_nr()

run_result(), optimize_result(), quick_optimize_result() も残す。

したがって利用者は、状態を持つ RustPDF を使うことも、従来どおり関数を直接呼ぶこともできる。

7. 変更しないもの

この I/F 整理では以下の意味を変更しない。

Rust pipeline::run()
Rust optimize::run()
Rust optimize::quick_run()
ZDST/FFT の数値処理
webPDF の物理量定義
localPDF の現在の run_all() / run_bft() 内部手順

8. Python package 内部構成

共通 I/F は package root から公開するが、実装責務は分離する。

__init__.py -> re-export
api.py      -> low-level Rust binding wrapper
config.py   -> Config
result.py   -> result object / derived physical quantities
pdf.py      -> stateful RustPDF

この分割は公開 I/F の変更ではない。

9. 手動 API の対応

参照 main_local.py と同じ呼び出し順:

pdf.load_xy(xy_file)
if bg_file is not None:
    pdf.load_bg_xy(bg_file, factor=bg_factor)

pdf.run_all()
pdf.run_bft()

を RustPDF でも使用できる。

Rust の run_bft() は数値処理を再実行しない。 Rust pipeline は run_all() で BFT/Lorch まで生成済みだからである。

10. RustPDF 自動版

旧 low-level API:

opt = rust_pdf.optimize(config, tth, intensity, bg_tth, bg_intensity)
out = rust_pdf.run(opt["parameters"], tth, intensity, bg_tth, bg_intensity)

に対応する高レベル自動 API:

pdf.run_auto()

quick 版:

pdf.run_auto(quick=True)

自動版は optimizer と PDF pipeline の既存処理を順番に呼ぶ。

11. I/F 共通化の最終原則

共通化はメソッド名ではなく、機能・処理・物理的意味で判定する。

localPDF

pdf.run_all()
pdf.run_bft()

run_all() は raw PDF までの複数段階をまとめた実処理。 run_bft() は BFT_smooth() という後段の実処理。

RustPDF

pdf.run()

Rust native run() に対応する通常 pipeline。 Rust pipeline 内で raw/BFT/Lorch まで計算する。

Rust には localPDF run_bft() と同じ独立した後段処理がないため、 RustPDF に run_bft() は設けない。

optimizer は通常 pipeline とは分離する。

pdf.optimize()
pdf.run()

または、

pdf.quick_optimize()
pdf.run()

run_auto() は設けない。

共通化するもの

get_gr() の G(r)、get_ggr() の g(r) など、物理的意味が一致する結果 I/F は共通化する。

名前だけ同じで処理意味が異なる API は共通化しない。

サンプルファイルの最終構成

サンプルは2本だけとする。

main_rust_manual.py
main_rust_auto.py

main_rust_manual.py は通常 pipeline を明示的に pdf.run() する手動版。

main_rust_auto.py は parameter optimization を行う自動版であり、オリジナル Rust API の意味を保って、

pdf.optimize()
pdf.run()

と明示的に実行する。

run_auto() のような独自 API は使用しない。