Metadata-Version: 2.4
Name: emout
Version: 2.23.0
Summary: Emses output manager
Author-email: Nkzono99 <j-nakazono@stu.kobe-u.ac.jp>
Maintainer-email: Nkzono99 <j-nakazono@stu.kobe-u.ac.jp>
License: MIT
Project-URL: Repository, https://github.com/Nkzono99/emout.git
Keywords: Visualization,Simulation,EMSES
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: h5py
Requires-Dist: f90nml
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: scikit-image
Requires-Dist: pyvista
Requires-Dist: tomli; python_version < "3.11"
Requires-Dist: mpiemses3d-tools
Requires-Dist: psutil
Requires-Dist: dask; python_version >= "3.10"
Requires-Dist: distributed; python_version >= "3.10"
Requires-Dist: cryptography; python_version >= "3.10"
Provides-Extra: pyvista
Provides-Extra: distributed
Requires-Dist: psutil; extra == "distributed"
Requires-Dist: dask; python_version >= "3.10" and extra == "distributed"
Requires-Dist: distributed; python_version >= "3.10" and extra == "distributed"
Requires-Dist: cryptography; python_version >= "3.10" and extra == "distributed"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

Lang: [日本語](README.md) | [English](README.en.md)

# emout

[![PyPI version](https://img.shields.io/pypi/v/emout.svg)](https://pypi.org/project/emout/)
[![Python](https://img.shields.io/pypi/pyversions/emout.svg)](https://pypi.org/project/emout/)
[![Docs](https://github.com/Nkzono99/emout/actions/workflows/docs.yaml/badge.svg)](https://nkzono99.github.io/emout/)
[![CodeQL](https://github.com/Nkzono99/emout/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Nkzono99/emout/actions/workflows/codeql-analysis.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**[EMSES](https://github.com/Nkzono99/MPIEMSES3D) シミュレーション出力の解析・可視化 Python ライブラリ**

emout でできること:

- `.h5` グリッド出力と `plasma.inp` / `plasma.toml` を 1 行で読み込めるファサード
- データの次元に応じて最適な表示を自動選択する 1D / 2D / 3D プロット
- `!!key dx=...,to_c=...` ヘッダーから自動生成される EMSES ⇄ SI 単位変換（30 種以上の物理量に対応）
- EMSES の finbound 境界形状を Python オブジェクトとして操作できる API

---

- **ドキュメント:** [ユーザーガイド (日本語/English)](https://nkzono99.github.io/emout/guide/quickstart.ja.html) | [API リファレンス](https://nkzono99.github.io/emout/api/emout.html)
- **ノートブック例:** [月面帯電シミュレーション結果の可視化](https://nbviewer.org/github/Nkzono99/examples/blob/main/examples/emout/example.ipynb)
- **Agent plugins:** [emout Context](https://github.com/Nkzono99/emout/blob/main/plugins/emout-context/README.md) — Codex / Claude Code 標準の plugin marketplace で導入し、repo 外でも可視化 script 作成・改善、単位変換、トラブルシュートを agent に相談できます（[導入手順](https://github.com/Nkzono99/emout/blob/main/plugins/README.md)）

---

## インストール

```bash
pip install emout

# PyVista による 3D 可視化も標準インストールに含まれます

# インストール済み version と PyPI の更新確認
emout version --check-update
```

---

## Agent plugins

emout の `emout Context` plugin は、シミュレーション出力ディレクトリや別 repo で Codex / Claude Code を起動したときにも、emout の軸順序・単位変換・可視化・トラブルシュートの文脈を使えるようにします。

```bash
codex plugin marketplace add Nkzono99/emout \
  --ref main \
  --sparse .agents/plugins \
  --sparse plugins/emout-context
codex plugin add emout-context@emout
```

Claude Code では次のように導入します。

```bash
claude plugin marketplace add Nkzono99/emout \
  --sparse .claude-plugin plugins/emout-context
claude plugin install emout-context@emout
```

emout CLI をインストール済みなら、Claude Code 用は `emout claude install-plugin`、Codex 用は `emout codex install-plugin` でも導入できます。詳しい導入・更新手順は [plugin 導入手順](https://github.com/Nkzono99/emout/blob/main/plugins/README.md) を参照してください。

---

## クイックスタート

```python
import emout

data = emout.Emout("output_dir")

# 最終ステップの電位を xz 平面（y=ny/2）でプロット — これだけで SI 単位付きカラーマップ
data.phisp[-1, :, data.inp.ny // 2, :].plot()
```

変数名は EMSES のファイル名から自動解決されます:

```python
data.phisp          # 電位 (GridDataSeries — 時系列)
data.nd1p           # 種1 数密度
data.j1x            # 種1 電流密度 x成分
data.j1xy           # j1x + j1y 自動結合 → 2D ベクトル
data.j1xyz          # 3D ベクトル
data.icur, data.ocur, data.pbody  # テキスト診断出力 (.val_si で SI 変換)
```

スライスの軸順序は `(t, z, y, x)` です。

解析・描画で元の系列と座標を保持するためのオプション:

```python
data.phisp.time_series(32, 32, 10, skip_overlap=True)  # 再開点の重複を除外
data.phisp[:].mean(axis="x", keep_metadata=True)[-1].plot()  # yz 平均断面
data.phisp[-1, ::2, ::2, ::2].plot(coordinates="grid", levels=[0.0])
```

従来の既定動作も維持します。詳しくは [クイックスタート](docs/source/guide/quickstart.ja.md) と
[プロットガイド](docs/source/guide/plotting.ja.md) を参照してください。

周期電場の境界補間と、VTK の値・座標配置を修正するオプションも利用できます:

```python
data = emout.Emout("output_dir", electric_relocation="periodic")
data.phisp[-1].to_vtk("phisp.vti", ordering="vtk", coordinates="grid")
```

穴表面の描画には `consistent=True`、平面の場の着色には `resolution="grid"` を使います。
軌跡の透明度・領域・目盛・カメラの調整は [PyVista ガイド](docs/source/guide/pyvista.ja.md)、
共有ライブラリの診断は [バックトレースガイド](docs/source/guide/backtrace.ja.md) を参照してください。

---

## 機能ガイド

各機能の詳しい使い方はユーザーガイドを参照してください。

| 機能 | できること | ガイド |
| --- | --- | --- |
| **プロット** | `plot()` / `cmap()` / `contour()` で 1D/2D プロット | [→ プロット](https://nkzono99.github.io/emout/guide/plotting.ja.html) |
| **アニメーション** | `gifplot()` で GIF/HTML 生成、複数パネルレイアウト | [→ アニメーション](https://nkzono99.github.io/emout/guide/animation.ja.html) |
| **パラメータ** | `data.inp.nx`, `data.toml.species[0].wp` | [→ パラメータ](https://nkzono99.github.io/emout/guide/inp.ja.html) |
| **単位変換** | `data.unit.v.reverse(1.0)`, `data.phisp[-1].val_si` | [→ 単位変換](https://nkzono99.github.io/emout/guide/units.ja.html) |
| **ベクトルデータ** | `.components["z"]` で成分を指定、`VectorData` / `ComponentValues` で場と集計値を扱う | [→ クイックスタート](https://nkzono99.github.io/emout/guide/quickstart.ja.html) |
| **境界メッシュ** | `data.boundaries.mesh()`, `plot_surfaces` へのオーバーレイ | [→ 境界メッシュ](https://nkzono99.github.io/emout/guide/boundaries.ja.html) |
| **バックトレース** | `data.trace.forward(...)`, `data.backtrace.get_probabilities(...)` | [→ バックトレース](https://nkzono99.github.io/emout/guide/backtrace.ja.html) |
| **3D (PyVista)** | `plot3d(mode="box"/"stream"/"quiver")` | [→ PyVista 可視化](https://nkzono99.github.io/emout/guide/pyvista.ja.html) |

---

## 代表的な使い方

### プロット

```python
data.phisp[-1, 100, :, :].plot()                       # 2D カラーマップ
data.phisp[-1, 100, :, :].contour()                     # 等高線
data.nd1p[-1, 100, :, :].plot(norm="log", vmin=1e-3)    # 対数スケール
data.j1xy[-1, 100, :, :].plot()                          # ストリームライン
data.phisp[-1, :, 32, 32].plot()                         # 1D プロファイル
```

### アニメーション

```python
data.phisp[:, 100, :, :].gifplot()                                  # Jupyter インライン
data.phisp[:, 100, :, :].gifplot(action="save", filename="out.gif") # GIF 保存
```

### 単位変換

```python
data.unit.v.trans(1.0)       # SI → EMSES
data.phisp[-1].val_si        # 全 3D 配列を SI [V] で取得
```

### 境界メッシュ

```python
data.boundaries[0].mesh()                   # 個別境界の MeshSurface3D
data.phisp[-1].plot_surfaces(               # フィールド上にオーバーレイ
    ax=ax, surfaces=data.boundaries,
)
```

### 粒子データ

```python
p4 = data.p4                               # 種4
p4.vx[0].val_si.to_series().hist(bins=200)  # 速度分布
```

<details>
<summary>追加出力の結合 / 入出力パスの分離</summary>

```python
# 継続出力の結合
data = emout.Emout("output_dir", ad="auto")

# 入力ファイルと出力ディレクトリを分離
data = emout.Emout(input_path="/path/to/plasma.toml", output_directory="output_dir")
```

</details>

<details>
<summary>実験的機能（ポアソン方程式 / バックトレース）</summary>

```python
# ポアソン方程式
from emout.utils import poisson
phi = poisson(rho, dx=dx, btypes=btypes, epsilon_0=cn.epsilon_0)

# バックトレース（要 vdist-solver-fortran）
result = data.backtrace.get_probabilities(x, y, z, vx, vy, vz, ispec=0)
result.vxvz.plot()
```

`data.trace` と `data.backtrace` は `use_electric_field=False` / `use_magnetic_field=False` で電場・磁場を個別に無効化できます（要 `vdist-solver-fortran >= 1.7.0`、既定は両方 `True`）。

</details>

---

## コントリビュート

バグ報告・機能提案・PR を歓迎します。

- **バグ / 質問:** [GitHub Issues](https://github.com/Nkzono99/emout/issues) に再現手順を添えて投稿してください
- **PR:** `main` から作業ブランチを切り、`pytest -q` がグリーンの状態で送ってください
- **ドキュメント:** `README.md`（日本語）と `README.en.md`（英語）は対応する形で維持されています。片方を更新したらもう片方にも反映してください

開発環境のセットアップやディレクトリ構成は [AGENTS.md](AGENTS.md) にまとまっています。

---

## ライセンス

[MIT License](LICENSE)

## リンク

- [ユーザーガイド（日本語）](https://nkzono99.github.io/emout/guide/quickstart.ja.html) | [User Guide (English)](https://nkzono99.github.io/emout/guide/quickstart.html)
- [API リファレンス](https://nkzono99.github.io/emout/api/emout.html)
- [EMSES (MPIEMSES3D)](https://github.com/Nkzono99/MPIEMSES3D)
- [サンプルノートブック](https://nbviewer.org/github/Nkzono99/examples/blob/main/examples/emout/example.ipynb)
