===========
PySIMPLE 編
===========

本章では ChatGPT を例に、PySIMPLE による最適化コードの自動生成手順を紹介します。
まずは新しい ChatGPT のチャットを開始します。

.. _pysimple-stage-a:

Stage A: PySIMPLE Documentation の理解
=======================================

1. ファイルアップロードボタンをクリックして ``pysimple-llm.txt`` をアップロード
2. 以下のプロンプトを送信

**プロンプトテンプレート [STEP A-PySIMPLE]**

.. code-block:: text

   このPySIMPLE documentationを読んで理解してください。特に以下の点に注意して学習してください：

   1. PySIMPLEの基本構文（Set, Element, Parameter, Variable, Problem）
   2. 基本例題（配合問題、DEAモデル）の理解
   3. Vectorized Constraint Syntax（ベクトル化制約構文）とDeclarative Style
   4. Conditions（条件式）の正しい使い方 — 条件の保存ルール、&/|による結合、多次元条件、条件に変数を使えない制約
   5. Complex Conditions with Filtered Sets — Native Python + PySIMPLE の Three-Phase Pattern
   6. Condition関数の使い方
   7. Setクラスの詳細（メソッド含む）
   8. Sum()関数の正しい使用方法
   9. 結果の集約方法（.val属性、dict(x.val.items())、タプルキー）

   理解できたら「PySIMPLE documentationを理解しました。次の段階に進んでください」と返答してください。

**期待される応答例**

.. code-block:: text

   PySIMPLE documentationを理解しました。次の段階に進んでください。

   主要なポイントを確認：
   - Set, Element, Parameter, Variable, Problemの基本構文
   - 配合問題・DEAモデルによる基本的なモデル構築パターン
   - Vectorized Constraint Syntaxでループを避ける宣言的記述
   - Conditions: 条件は先に変数に保存、&/|で結合（括弧必須）、変数は条件に使えない
   - Complex Conditions: Native Pythonでフィルタ → Set作成 → ベクトル化制約のThree-Phase Pattern
   - Condition関数による明示的な条件指定
   - Setクラスのメソッド（__contains__, __iter__, __call__）
   - Sum()関数は Sum(expression, index) の形式
   - 結果はdict(variable.val.items())で集約、キーは常にタプル

   準備完了です。

.. raw:: latex

   \newpage

.. _pysimple-stage-b:

Stage B: 問題から数式への変換
==============================

.. note::
   Stage B はツール共通です。Excel アドイン編でもこの Stage B を使用します。

**プロンプトテンプレート [STEP B]**

.. code-block:: text

   以下の最適化問題を数学的な最適化モデルに変換してください。
   必ず以下の手順に従って、段階的に整理してください：

   {問題内容を具体的に記述}

   **手順1: 問題の要素を特定**
   - 何を決定する必要があるか？（決定変数）
   - 何を最大化/最小化するか？（目的関数）
   - どのような制限があるか？（制約条件）
   - どのようなデータが与えられているか？（パラメータ）

   **手順2: 数式で表現**
   以下の形式で整理してください：

   **集合・添字:**
   - I = {具体的な要素を列挙}: （集合の説明）
   - i ∈ I: （添字の説明）

   **パラメータ（与えられた定数）:**
   - c_i = [具体的な値]: （パラメータの意味と単位）

   **決定変数（求めたい値）:**
   - x_i ≥ 0: （変数の意味と単位）

   **目的関数（最大化/最小化したい式）:**
   - maximize/minimize ∑_{i∈I} c_i × x_i

   **制約条件（満たすべき条件）:**
   - 制約1（名前）: ∑_{i∈I} a_{ij} × x_i ≤ b_j （制約の意味）

   **手順3: 数式の確認**
   - 決定変数の定義域は適切か？
   - 目的関数は問題の目標を正しく表現しているか？
   - 制約条件は問題の制限を全て含んでいるか？
   - 添字の範囲は明確ですか？

   この形式で整理が完了したら「数式モデルが完成しました。次の段階に進んでください」と返答してください。

**期待される応答例**

.. code-block:: text

   数式モデルが完成しました。次の段階に進んでください。

   **集合・添字:**
   - P = {A, B, C}: 製品の集合
   - p ∈ P: 製品の添字

   **パラメータ（与えられた定数）:**
   - profit_p = [A:1000, B:1500, C:1200]: 製品pの利益（円/個）
   - material1_p = [A:2, B:3, C:1]: 製品pの材料1使用量（kg/個）
   - material2_p = [A:1, B:2, C:3]: 製品pの材料2使用量（kg/個）
   - labor_p = [A:1, B:1.5, C:2]: 製品pの労働時間（時間/個）
   - capacity_material1 = 100: 材料1の利用可能量（kg）
   - capacity_material2 = 120: 材料2の利用可能量（kg）
   - capacity_labor = 80: 労働時間の利用可能量（時間）

   **決定変数（求めたい値）:**
   - x_p ≥ 0: 製品pの生産量（個）

   **目的関数（最大化/最小化したい式）:**
   - maximize ∑_{p∈P} profit_p × x_p

   **制約条件（満たすべき条件）:**
   - 材料1制約: ∑_{p∈P} material1_p × x_p ≤ capacity_material1
   - 材料2制約: ∑_{p∈P} material2_p × x_p ≤ capacity_material2
   - 労働時間制約: ∑_{p∈P} labor_p × x_p ≤ capacity_labor
   - 非負制約: x_p ≥ 0 for all p ∈ P

.. raw:: latex

   \newpage

Stage C: 数式から PySIMPLE コードへの変換
==========================================

挑戦レベル
-----------

**プロンプトテンプレート [STEP C1-PySIMPLE]**

.. code-block:: text

   上記で定義した数式をPySIMPLEコードに変換してください。

   重要な要求：
   - 必ずVectorized Constraint Syntaxを使用（for文のループは使わない）
   - 例: `problem += Sum(usage[i,j] * x[i], i) <= capacity[j]`
   - documentationの「Declarative Style」セクションの例に従う
   - 条件式が必要な場合はdocumentationの「Conditions」セクションに従う
   - 複雑な条件がある場合はThree-Phase Pattern（Native Pythonでフィルタリング → Set作成 → Vectorized制約）を使う
   - 結果出力は dict(x.val.items()) パターンを使い、タプルキーを適切に処理する
   - PySIMPLEを使用して完全で信頼性の高いPythonコードを作成
   - 必要な要素をすべて含める：集合と添字定義、変数定義、制約条件の追加、目的関数の設定、解の出力
   - 実行可能なコードのみを出力
   - ```python ブロック内に記述

   もし理解や実装が困難な場合は「Vectorized Constraint Syntaxの実装が困難です」と返答してください。

.. raw:: latex

   \newpage

安全レベル
-----------

**プロンプトテンプレート [STEP C2-PySIMPLE] (Vectorized Syntaxが困難な場合)**

.. code-block:: text

   上記で定義した数式をPySIMPLEコードに変換してください。

   基本要求：
   - 従来のループベースの方法を使用
   - for文を使った明示的なループでの制約記述
   - Sum()関数の基本的な使用
   - 確実に動作することを最優先
   - 条件式が必要な場合はdocumentationの「Conditions」セクションに従う（条件は先に変数に保存、&/|は括弧で囲む）
   - 結果出力は dict(x.val.items()) パターンを使い、タプルキーを適切に処理する

   参考パターン：

   <code>

      # 基本パターン
      for i_, in I:
          problem += usage[i_] * x[i_] <= capacity
   </code>

   PySIMPLEを使用して完全で信頼性の高いPythonコードを作成してください。

.. raw:: latex

   \newpage

Stage D: 結果の集約と出力
==========================

Stage C で生成されたコードが正常に動作した後、結果の集約・出力を行うコードを生成します。

**プロンプトテンプレート [STEP D-PySIMPLE]**

.. code-block:: text

   求解結果を集約・出力するコードを追加してください。
   pysimple-documentationの「Aggregating Results」セクションに従って、以下の要件を満たしてください：

   1. まず problem.result.errorCode == 0 でエラーチェックを行う
   2. 決定変数の結果は dict(x.val.items()) で辞書に変換する
   3. 辞書のキーは常にタプル形式であることに注意する（1次元でも ('A',) のようなタプル）
   4. 以下の集約を行う：
      - 各変数の最適値の一覧表示
      - 合計値、平均値、最大値、最小値の統計計算
      - 目的関数値の表示
   5. 必要に応じてCSV形式での出力コードも生成する

   参考パターン：

   <code>
   if problem.result.errorCode == 0:
       results = dict(x.val.items())
       for key, value in results.items():
           print(f"{key}: {value}")
       total = sum(results.values())
       print(f"合計: {total}")
   else:
       print("求解に失敗しました")
   </code>

.. raw:: latex

   \newpage

失敗時プロンプトテンプレート
=============================

.. code-block:: text

   以下のエラーが発生しました：

   <message>
   [エラーメッセージをここに貼り付け]
   </message>

   pysimple-documentationを参考に、以下の点をチェックして修正してください：
   1. Sum()関数の使用方法は正しいか
   2. Parameter値のアクセス方法は正しいか
   3. Vectorized Constraint Syntax（ベクトル化制約構文）の構文は適切か
   4. 変数定義に問題はないか
   5. Conditions（条件式）の使い方は正しいか（条件の保存、&/|の括弧、変数を条件に使っていないか）
   6. Setの作成方法は正しいか（valueパラメータの形式、dimの指定）
   7. 結果の集約で dict(x.val.items()) を使っているか、タプルキーを正しく処理しているか

   修正版のコードを提示してください。

.. raw:: latex

   \newpage

.. _pysimple-best-practices:

ベストプラクティス
===================

.. _pysimple-common-guidelines:

共通ガイドライン
-----------------

.. note::
   以下のガイドラインは PySIMPLE・Excel アドインの両方に共通です。

1. **段階的なアプローチ**: 一度に全てを要求せず、(a)理解 → (b)数式化 → (c)コード化/設定生成 → (d)結果確認の順で進める
2. **数式の明確化**: 問題をまず数学的に正確に表現することで、コード化/設定生成の成功率を向上
3. **具体的なデータ**: 抽象的でなく具体的な数値データを提示する
4. **エラー対応**: エラーメッセージを正確にコピーして修正を依頼

PySIMPLE 固有ガイドライン
--------------------------

1. **段階的フォールバック**: 高度な構文（Vectorized Constraint Syntax）から基本構文（ループベース）まで、LLM の能力に応じた選択肢を提供
2. **条件式の注意点**: 同じ条件を複数箇所で使う場合は先に変数に保存する。条件に変数は使えない
3. **複雑な条件は Three-Phase Pattern**: Native Python でフィルタリング → PySIMPLE Set 作成 → ベクトル化制約
4. **結果集約は dict 変換が基本**: ``dict(x.val.items())`` で dict に変換してから Python で処理

.. important::
   この4段階プロセスにより、LLM の理解度と能力に応じて、確実に PySIMPLE コードを生成できます。