qe2mcp - Quantum ESPRESSO to MCP JSON Converter

QE (Quantum ESPRESSO) の出力ファイル（例：AgAl-1.out）を読み込み、MCPサーバー用のJSON形式に変換するツールです。

機能

• QE出力ファイルのパース: Quantum ESPRESSO pw.x（v7.x）の vc-relax 計算出力を対応
• 単一・複数ファイル処理: 単一ファイルまたはバッチモードで複数ファイルを処理可能
• ワイルドカード対応: *.out などのグロブパターンで複数ファイルを指定可能
• 構造化データの抽出:
  • プログラム情報（バージョン、計算タイプ）
  • 計算パラメータ（カットオフ、交換相関汎関数など）
  • 初期構造と最終構造
  • イオンステップごとのエネルギー、力、磁気モーメント
  • タイミング情報
• 磁気モーメント情報:
  • 全磁気モーメント（3次元ベクトル）と絶対磁気モーメント
  • 各原子の磁化情報（3次元ベクトル、電荷あたりの磁化、位置、電荷）
• JSON形式での出力: MCPサーバーとの連携に適した形式

インストール

pip install -e .

使用方法

コマンドライン

単一ファイル処理

# 基本的な使用方法
python3 main.py AgAl-1.out

# 出力ファイルを指定する場合
python3 main.py AgAl-1.out -o output.json

# 詳細出力
python3 main.py AgAl-1.out -v

複数ファイル処理

# 複数ファイルを明示的に指定
python3 main.py AgAl-1.out CuSn-2.out

# ワイルドカードパターン
python3 main.py *.out

# 複数ファイルを出力ディレクトリに保存
python3 main.py *.out -o json_output/

# 複数ファイル処理（詳細出力）
python3 main.py AgAl-1.out CuSn-2.out -v

Pythonスクリプトでの使用

from parser import QEParser

# パーサーを作成
parser = QEParser()

# QE出力ファイルをパース
data = parser.parse('AgAl-1.out')

# JSONとして保存
parser.save_json('agal.json')

# JSONストリングとして取得
json_str = parser.to_json()

サーバー機能

HTTPSサーバーに置かれたJSONファイルをChatGPTが読めるようにするサーバーを提供しています。

使用方法

# デフォルトURL（提供URLを使用）
python3 server.py

# カスタムURL指定
python3 server.py --url https://example.com/json/

# ポート指定
python3 server.py --port 8000

# 外部からのアクセスを許可
python3 server.py --host 0.0.0.0 --port 8000

# 詳細出力モード
python3 server.py -v

API エンドポイント

サーバーが起動すると以下のエンドポイントが利用可能になります：

エンドポイント	説明
/	API インデックス・ヘルプ
/files	利用可能なJSONファイル一覧
/files/<filename>	指定したJSONファイルを取得
/all	すべてのJSONファイルを統合して取得
/stats	キャッシュの統計情報
/health	ヘルスチェック

サーバー起動例

# ローカルサーバー起動（ポート5000）
python3 server.py

# 出力:
# 🚀 Starting QE2MCP JSON Server
#   - URL: https://ip-163-220-177-91.compute.mdx1.jp/fDpyK7TbE5C1oj1ObA2H/msg3/
#   - Server: http://127.0.0.1:5000

cURL での使用例

# ファイル一覧取得
curl http://localhost:5000/files

# 特定のファイル取得
curl http://localhost:5000/files/AgAl-1.json

# すべてのJSONを取得
curl http://localhost:5000/all

# ヘルスチェック
curl http://localhost:5000/health

出力JSON構造

{
  "program": {
    "version": "7.5",
    "git_revision": "...",
    "calculation": "vc-relax",
    "completed": true
  },
  "input": {
    "nat": 6,
    "ntyp": 4,
    "nbnd": 88,
    "nelec": 74.0,
    "ecutwfc_ry": 65.0,
    "ecutrho_ry": 780.0,
    "xc": "PBESOL",
    "fft_grid": [50, 50, 64],
    "smooth_grid": [50, 50, 64]
  },
  "structure_initial": {
    "alat_bohr": 8.3461,
    "volume_bohr3": 737.849,
    "cell_parameters": [[...], [...], [...]],
    "atomic_positions": [...],
    "magnetization": {"x": 0.0, "y": 0.0, "z": 0.0},
    "abs_magnetization": 9.42,
    "atomic_magnetizations": {
      "1": {
        "position": [0.0, 0.0, 0.6346],
        "charge": 13.4698,
        "magnetization": {"x": 0.0, "y": 0.0, "z": -6.571554},
        "magnetization_per_charge": {"x": 0.0, "y": 0.0, "z": -0.487872}
      },
      ...
    }
  },
  "ionic_steps": [
    {
      "index": 0,
      "energy_ry": -1073.44271308,
      "forces": {
        "1": [0.001, 0.002, 0.003],
        ...
      },
      "total_force": 0.01234,
      "magnetization": {"x": 0.0, "y": 0.0, "z": 0.0},
      "abs_magnetization": 9.42,
      "atomic_magnetizations": {
        "1": {
          "position": [0.0, 0.0, 0.6346],
          "charge": 13.4698,
          "magnetization": {"x": 0.0, "y": 0.0, "z": -6.571554},
          "magnetization_per_charge": {"x": 0.0, "y": 0.0, "z": -0.487872}
        },
        ...
      }
    },
    ...
  ],
  "structure_final": {
    "cell_parameters": [[...], [...], [...]],
    "atomic_positions": [...],
    "magnetization": {"x": 0.0, "y": 0.0, "z": 0.0},
    "abs_magnetization": 8.28,
    "atomic_magnetizations": {
      "1": {
        "position": [0.0, 0.0, 0.6366],
        "charge": 13.3378,
        "magnetization": {"x": 0.0, "y": 0.0, "z": -3.704097},
        "magnetization_per_charge": {"x": 0.0, "y": 0.0, "z": -0.277715}
      },
      ...
    }
  },
  "timing": {
    "cpu_wall": "..."
  }
}

対応フォーマット

• Quantum ESPRESSO: v7.x
• 計算タイプ: vc-relax（体積と原子位置の構造最適化）
• ファイルフォーマット: テキスト形式の標準出力

サンプル実行

単一ファイル処理

テストデータ (AgAl-1.out) を使用:

python3 main.py AgAl-1.out -v

出力:

Processing 1 file(s)...

📖 Reading: AgAl-1.out
✓ JSON saved to AgAl-1.json
✅ Successfully parsed: AgAl-1.out
   - Program: 7.5
   - Atoms: 6
   - Ionic steps: 10
   - Completed: True

複数ファイル処理

複数ファイルをバッチ処理:

python3 main.py AgAl-1.out CuSn-2.out -v

出力ディレクトリに保存:

python3 main.py *.out -o json_output/

出力:

✓ JSON saved to json_output/AgAl-1.json
✓ AgAl-1.out → AgAl-1.json
✓ JSON saved to json_output/CuSn-2.json
✓ CuSn-2.out → CuSn-2.json

📊 Summary: 2/2 files processed successfully

構造

• parser.py - QEParserクラス: QE出力ファイルのパースロジック
• regex.py - 正規表現定義: ファイル解析用の各種パターン
• main.py - CLIスクリプト: コマンドラインインターフェース

ライセンス

MIT License

作成者

Mitsuaki Kawamura