# localPDF マニュアル

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

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

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

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

``` text
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 本体を理解するうえで重要なファイルは次のとおり。

``` text
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クラスである。

``` python
Config
LocalPDF
LocalPDFPlot
```

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

------------------------------------------------------------------------

## 3. webPDF と localPDF の対応

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

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

``` text
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
```

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

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

------------------------------------------------------------------------

## 4. Config

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

``` 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 である。

主な責務は、

1.  `Config` の保持
2.  計算コアの生成
3.  config 値の計算コアへの設定
4.  実験データの読み込み
5.  background の読み込み
6.  計算実行
7.  計算結果の取得
8.  結果ファイルの保存

である。

内部では、

``` python
self._pdf = Local_Calc_PDF_from_xy()
```

を保持する。

### 5.2 初期化

推奨形は次である。

``` python
from localPDF import Config, LocalPDF

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

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

------------------------------------------------------------------------

## 6. 入力

### 6.1 実験データ

``` python
pdf.load_xy("data.dat")
```

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

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

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

### 6.2 background

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

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

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

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

------------------------------------------------------------------------

## 7. 標準計算フロー

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

``` python
pdf.run_all()
pdf.run_bft()
```

である。

### 7.1 run_all()

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

内部の主要な流れは、

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

である。

### 7.2 run_bft()

``` python
pdf.run_bft()
```

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

コード上では、

``` text
Rcut_and_bFT()
UseSmoothBG()
CalcGrFFT()
CalcGrLorch()
```

が実行される。

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

``` python
pdf.run_all()
pdf.run_bft()
```

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

------------------------------------------------------------------------

## 8. 結果取得

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

``` python
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()
```

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

``` python
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 成分は、

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

で取得する。

------------------------------------------------------------------------

## 9. ファイル保存

``` python
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` は計算ではなく表示を担当する。

``` python
from localPDF import LocalPDFPlot

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

主なメソッドは、

``` text
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` の継承

である。

したがって、

``` text
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 にある、

``` python
print(pdf.pdf.nn_min)
```

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

基本的には、

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

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

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

``` text
LocalPDF.pdf
Local_Calc_PDF_from_xy
Calc_PDF_from_xy
```

へ降りる。

------------------------------------------------------------------------

## 13. コードを読む順番

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

``` text
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 本体について、まず次だけ覚えておけば通常利用できる。

``` python
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")
```

つまり、

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

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