# localPDF API リファレンス

この文書は、実験データから PDF を計算する `localPDF`
本体について、利用者が直接使用する API を一覧化したものである。

構造モデルから S(Q) を計算する追加機能は本体 API
から分離し、`SQ_EXPERIMENTAL.md` に記載する。

## Config

### `Config(json_path=None)`

Web 版 config JSON を読み込む。

``` python
config = Config("config.json")
```

主な公開属性:

  属性           型              内容
  -------------- --------------- ---------------------
  `bg_factor`    `float`         background factor
  `atomList`     `List[int]`     原子番号
  `atomConc`     `List[float]`   組成
  `energy_keV`   `float`         X-ray energy
  `density`      `float`         density
  `pol`          `float`         polarization factor
  `recoil`       `float`         recoil factor
  `norm_min`     `float`         normalization Q min
  `norm_max`     `float`         normalization Q max
  `r_max`        `float`         r max
  `dr`           `float`         delta-r
  `r_cut`        `float`         cutoff distance

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

# LocalPDF

## 生成

### `LocalPDF(config=None, json_path=None)`

``` python
pdf = LocalPDF(config=config)
```

または、

``` python
pdf = LocalPDF(json_path="config.json")
```

### `config`

保持している `Config` を返す property。

### `pdf`

内部の計算コアを返す
property。通常利用では直接操作せず、デバッグ・内部調査用として扱う。

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

## 入力 API

### `load_xy(xy_path)`

実験データを読み込む。

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

入力は2列。

``` text
two-theta  intensity
```

### `load_bg_xy(bg_xy_path, factor=None)`

background を読み込む。

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

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

## 計算 API

### `run_all()`

標準計算一式を実行する。

Web 版計算コアの `All_run()` に対応する。

### `run_bft()`

r cutoff、back Fourier transform、再計算、Lorch 処理を実行する。

通常は、

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

の順で使用する。

### `run_sq()`

S(Q), i(Q) 関連の計算制御用メソッド。

現状の内部依存関係を理解したうえで使用する低レベル寄り API
として扱い、通常の標準処理では `run_all()` を使用する。

### `run_gr()`

補間後に G(r) FFT を実行する。

標準処理の一部分だけを再実行したい場合の制御 API。

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

## 個別計算 API

以下は通常の一括計算より低レベルの API。

### `calc_form()`

atomic form factor 計算。

### `calc_comp()`

Compton 成分計算。

### `calc_gr_fft()`

G(r) FFT 計算。

### `calc_gr_raw()`

raw G(r) 計算。

通常利用では `run_all()` / `run_bft()`
を優先し、計算過程を個別制御する必要がある場合に使用する。

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

## 結果取得 API

### `get_iq()`

``` python
q, iq = pdf.get_iq()
```

i(Q) を返す。

### `get_sq()`

``` python
q, sq = pdf.get_sq()
```

S(Q) を返す。

### `get_gr()`

``` python
r, gr = pdf.get_gr()
```

G(r) を返す。

### `get_gr_lorch()`

``` python
r, gr = pdf.get_gr_lorch()
```

Lorch 処理後の G(r) を返す。

### `get_ggr()`

``` python
r, ggr = pdf.get_ggr()
```

g(r) 系内部結果を返す。

### `get_ggr_lorch()`

``` python
r, ggr = pdf.get_ggr_lorch()
```

Lorch 処理後の g(r) 系結果を返す。

### `get_intensity_components()`

``` python
q, intensity, form_compton = pdf.get_intensity_components()
```

規格化強度と form factor + Compton の比較に使う。

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

## 強度処理確認 API

### `get_intensity_raw()`

入力した raw intensity。

### `get_intensity_bg()`

係数適用前 background。

### `get_intensity_bg_scaled()`

background factor 適用後 background。

### `get_intensity_subtracted()`

background subtraction 後、polarization correction 前。

### `get_intensity_corrected()`

background subtraction + polarization correction 後。

### `get_intensity_corrected_normalized()`

規格化後強度。

### `get_formfactor_components()`

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

`<f²>`、Compton、両者の合計を返す。

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

## 保存 API

### `save_iq(filename="iq.dat")`

i(Q) を2列ファイルとして保存。

### `save_sq(filename="sq.dat")`

S(Q) を2列ファイルとして保存。

### `save_gr(filename="gr.dat")`

G(r) を2列ファイルとして保存。

### `save_gr_lorch(filename="gr_lorch.dat")`

Lorch 処理後 G(r) を2列ファイルとして保存。

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

# LocalPDFPlot

### `LocalPDFPlot(local_pdf)`

``` python
view = LocalPDFPlot(local_pdf=pdf)
```

## 表示 API

  メソッド                 内容
  ------------------------ ------------------------------------
  `view_raw()`             raw intensity と background
  `view_sq()`              S(Q)/i(Q) 用 plot
  `view_iq_components()`   規格化強度と form factor + Compton
  `view_gr()`              G(r)
  `view_gr_lorch()`        Lorch G(r)
  `view_all()`             上記を grid 表示

注意: 現状の `view_sq()` は line
描画コードがコメントアウトされているため、S(Q)/i(Q)
の曲線は描画されない。

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

# 推奨 API と内部 API

通常利用で中心となる API:

``` text
Config
LocalPDF
LocalPDFPlot

LocalPDF.load_xy
LocalPDF.load_bg_xy
LocalPDF.run_all
LocalPDF.run_bft
LocalPDF.get_*
LocalPDF.save_*
```

必要時のみ使用する計算制御 API:

``` text
run_sq
run_gr
calc_form
calc_comp
calc_gr_fft
calc_gr_raw
```

内部実装調査用:

``` text
LocalPDF.pdf
Local_Calc_PDF_from_xy
webPDF.calc_pdf.Calc_PDF_from_xy
```