# tktransport マニュアル

## 1. 役割

`tktransport` は、単一等方放物線band（SPB）とpower-law scattering modelに基づき、carrier density、conductivity、mobility、Seebeck係数、Lorenz数、電子熱伝導率、power factor、ZT、Hall係数等を計算する独立パッケージです。

## 2. 推奨import

```python
from tktransport import (
    SingleParabolicBand,
    ScatteringModel,
    eta_grid,
    calculate_transport_sweep,
    calculate_hall_sweep,
)
```

## 3. 単一点計算

```python
from tktransport import SingleParabolicBand, ScatteringModel

band = SingleParabolicBand(
    effective_mass=0.30,
    band_edge_ev=0.0,
)
scattering = ScatteringModel(
    charge_sign=-1,          # electron
    scattering_factor=0.5,
    mean_free_path=10e-9,    # m
)

result = band.calculate_transport_properties(
    eta=0.0,
    temperature=300.0,
    scattering=scattering,
    lattice_thermal_conductivity=1.5,
)
print(result.as_dict())
```

## 4. 符号規約

- electron: `charge_sign=-1`
- hole: `charge_sign=+1`

carrier reduced chemical potential `eta` は、

- electron: `(EF - EC) / kBT`
- hole: `(EV - EF) / kBT`

です。Seebeck係数とHall係数の符号は `charge_sign` によって決まります。

## 5. 単位

結果field名に単位が含まれます。

| 量 | field | 単位 |
|---|---|---|
| carrier density | `carrier_density_cm3` | cm^-3 |
| conductivity | `conductivity_s_cm` | S/cm |
| mobility | `mobility_cm2_v_s` | cm^2/(V s) |
| relaxation time | `average_relaxation_time_fs` | fs |
| Seebeck | `seebeck_uv_k` | µV/K |
| thermal conductivity | `*_w_m_k` | W/(m K) |
| Lorenz number | `lorenz_number_w_ohm_k2` | W Ω/K^2 |
| power factor | `power_factor_w_m_k2`, `power_factor_uw_cm_k2` | W/(m K^2), µW/(cm K^2) |

`mean_free_path` はm、`effective_mass` は自由電子質量単位です。

## 6. eta sweep

```python
from tktransport import eta_grid, calculate_transport_sweep

etas = eta_grid(-8.0, 8.0, 321)
sweep = calculate_transport_sweep(
    band,
    scattering,
    temperature=300.0,
    eta_values=etas,
    lattice_thermal_conductivity=1.5,
)

best = sweep.eta[sweep.zt.argmax()]
```

Hall sweep:

```python
from tktransport import calculate_hall_sweep

hall = calculate_hall_sweep(band, scattering, 300.0, etas)
```

## 7. Fermi levelとの変換

```python
eta = band.eta_from_fermi_level(
    fermi_level_ev=0.10,
    temperature=300.0,
    charge_sign=-1,
)
ef = band.fermi_level_from_eta(eta, 300.0, charge_sign=-1)
```

absolute Fermi levelを使う計算には `calculate_transport_from_fermi_level()` と `calculate_hall_from_fermi_level()` があります。

## 8. scattering model

実装はmean-free-path normalizationを使うpower lawです。`relaxation_time(E)` は非正のenergyで `None` を返します。

Hall計算では `scattering_factor > -0.25` が必要です。これ以下では該当Fermi integralがband edgeで発散するため `ValueError` になります。

## 9. 近似式と厳密計算

`SingleParabolicBand` には、非縮退・縮退近似のSeebeck、近似Lorenz数、Fermi energy等の補助methodがあります。適用範囲外で近似式を主結果として使わず、通常はFermi integralを使う `calculate_transport_properties()` を優先してください。

## 10. 数値・物理上の制約

- 温度、effective massは正でなければなりません。
- lattice thermal conductivityは非負です。
- SPB、等方、有効質量近似、単一carrier、指定scattering lawを仮定します。
- 多band、bipolar conduction、energy-dependent band nonparabolicity、grain boundary、localization等は自動的には含まれません。
- 計算値と実験Hall densityの比較ではHall factorを区別してください。

## 11. CLI

`tktransport.cli` は計算・sweep・Excel/plot出力用の関数を含みます。正確な引数は次で確認してください。

```bash
python -m tktransport --help
# または
python -m tktransport.cli --help
```

## 12. 依存関係

- `numpy`, `scipy`
- CLI Excel出力: `openpyxl`
- plot: `matplotlib`

## 13. 生成AI向けコード生成ルール

1. electron/holeの `charge_sign` を必ず明示する。
2. `eta` をeVと誤認しない。無次元量である。
3. field名に埋め込まれた単位を維持し、無断でSI/CGS変換しない。
4. conductivityがS/cmであることを確認して実験値と比較する。
5. Hall densityとtrue carrier densityをHall factorなしに同一視しない。
6. `scattering_factor <= -0.25` でHall計算を行わない。
7. SPBモデルの仮定を超える多carrier fitを、このpackageだけで実装済みと仮定しない。
8. sweepでは各array fieldが同じeta gridに対応することを維持する。