.. index:: contents, directive; contents

==================
パラメータサーベイの実行方法
==================

.. contents:: 目次
    :depth: 2

``pyemsol`` では，多数ケースの計算時に計算条件を更新することができます。

変更できる計算条件は，以下の通りです。

- 材料特性の更新 :paramdef:`16_1_3D_Element_Properties(16.1)`
- 時間関数の更新 :paramdef:`18_Time_Function(18)`

.. note:: 
    ``pyemsol`` のインストール方法，基本情報については， :doc:`/handbook/run/runPython` を参照してください。


-----------------
``pyemsol`` の実行手順（簡単に）
-----------------
``pyemsol`` をPythonスクリプトで実行するには，以下の関数を順番に呼び出します。

.. code-block:: python
    :caption: Python code

    import pyemsol
    
    # 初期化
    pyemsol.initialize(json_data, current_directory)
    # 計算条件の更新
    for i in range(num_case):
        # 計算条件の更新
        # update Time_Function
        # json_data["18_Time_Function"] = new_time_function
        pyemsol.update_Time_Function(json_data)
        # 計算実行, 計算結果の取得
        output = pyemsol.solve()

    # 計算終了
    pyemsol.finalize()

``pyemsol.initialize`` を使用して初期化し， ``pyemsol.solve`` を複数回実行することができます。
``pyemsol.finalize`` で終了します。

``pyemsol.solve`` を複数回実行できるようになったことで，計算条件を変更して，複数回計算を行うことができます。

----------------
材料特性の更新
----------------
材料特性の更新は，以下のように，設計領域に指定したいプロパティに，:paramdef:`is_DESIGN_DOMAIN(16.1)` を指定します。

``"is_DESIGN_DOMAIN" : 1`` と指定されたプロパティは，次に示す反復計算手順内で材料物性を変更することが可能です。


.. code-block:: json
    :caption: JSON format from 2024.11

    "16_Material_Properties" : 
    {
        "EXTEND_TOTAL_for_COIL" : I,
        "16_1_3D_Element_Properties" : 
        [
            {
                "MAT_ID" : I,
                "POTENTIAL" : I,
                "ElectricProperty" : 
                {
                    "conductivity" : 
                    {
                        "comment" : "SIGMA_XYZ for anisotropic, or isotropic SIGMA if not defined.",
                        "SIGMA" : E
                    }
                },
                "MagneticProperty" : 
                {
                    "comment" : "MU_XYZ for anisotropic, or isotropic MU if not defined.",
                    "MU" : E,
                    "BH_CURVE_ID" : I
                },
                "is_DESIGN_DOMAIN" : 1
            }
        ]
    }


``pyemsol.update_properties_in_design_domain`` を用いて、設計領域に指定したプロパティの材料特性を更新できます。ここでは、この方法を説明します。

``pyemsol.update_properties_in_design_domain`` を用いて，設計領域に指定したプロパティの材料特性を更新する方法は，以下のように行います。

.. code-block:: python
    :caption: Python code

        import pyemsol

        # 計算条件の初期化
        # json_data は input.json のデータ
        # current_directory は input.json のあるディレクトリ
        pyemsol.initialize(json_data, current_directory)

        # 材料特性の更新
        # default permeability = 1.0, update to 5.0
        permeability = 5.0
        matData = json_data["16_Material_Properties"]
        data3D = matData["16_1_3D_Element_Properties"]
        for element in data3D:
            if element["MAT_ID"] == 1:
                element["MagneticProperty"]["MU"] = permeability
                break

        # 計算条件の更新
        pyemsol.update_properties_in_design_domain(new_material_properties)
        # 計算実行, 計算結果の取得
        output = pyemsol.solve()

        # 計算終了
        pyemsol.finalize() 


*input.json* 内の ``16_Material_Properties`` の ``16_1_3D_Element_Properties`` 内の ``is_DESIGN_DOMAIN`` を ``1`` に指定したプロパティの材料特性を更新することができます。

材料特性として，比透磁率 ``MU`` を更新する例を示しましたが，その他の材料特性も同様に更新することができます。
``MagneticProperty`` 自体を更新することも可能です。

.. code-block:: python
    :caption: Python code

        import pyemsol

        # 計算条件の初期化
        # json_data は input.json のデータ
        # current_directory は input.json のあるディレクトリ
        pyemsol.initialize(json_data, current_directory)

        # Initialize variables to hold MagneticProperty values
        magnetic_property_mat_id_10 = None
        data3D = matData["16_1_3D_Element_Properties"]
        for element in data3D:
            if element["MAT_ID"] == 10:
                magnetic_property_mat_id_10 = element["MagneticProperty"]
                break

        # 材料特性の更新
        matData = json_data["16_Material_Properties"]
        data3D = matData["16_1_3D_Element_Properties"]
        for element in data3D:
            if element["MAT_ID"] == 1:
                element["MagneticProperty"] = magnetic_property_mat_id_10
                break

        # 計算条件の更新
        pyemsol.update_properties_in_design_domain(new_material_properties)
        # 計算実行, 計算結果の取得
        output = pyemsol.solve()

        # 計算終了
        pyemsol.finalize()

プロパティに割り当てる材料を空気や鉄などへ変更する感度解析に利用できます。

サンプルコードは， :ref:`update_properties_in_design_domain` を参照してください。


----------------
時間関数の更新
----------------
時間関数の更新は，例えばモータ解析において，電流―トルク特性を計算する場合に使用できます。
時間関数は， :paramdef:`18_Time_Function(18)` にて指定します。

ここでは， :paramdef:`交流表示(18.3)` を用いた例を示します。

以下に示す時間関数 :paramdef:`18_Time_Function(18)` が 電気回路 :paramdef:`NETWORK(17.9)` に接続されているものとします。

.. code-block:: json
    :caption: JSON format from 2024.11

        "18_Time_Function": 
        [
            {
                "TIME_ID": I,
                "OPTION": 2,
                "AMPLITUDE": 1.0,
                "TCYCLE": 0.02,
                "PHASE": 0.0
            }
        ]

電流位相は 0.0 degで固定とし，電流振幅を変更する場合は，以下のように ``pyemsol.update_Time_Function`` を用いて，時間関数の振幅を更新します。

.. code-block:: python
    :caption: Python code

        import pyemsol

        # 計算条件の初期化
        # json_data は input.json のデータ
        # current_directory は input.json のあるディレクトリ
        pyemsol.initialize(json_data, current_directory)

        # 時間関数の更新
        # 三相交流は，TIME_ID=1,2,3として定義されているとする。
        for current in current_rms:
            # 交流表示の時間関数の振幅を変更
            time_function = json_data["18_Time_Function"]
            for function in time_function:
                if function["TIME_ID"] == 1 or function["TIME_ID"] == 2 or function["TIME_ID"] == 3:
                    function["AMPLITUDE"] = current

            # 計算条件の更新
            pyemsol.update_Time_Function(json_data)
            # 計算実行, 計算結果の取得
            output = pyemsol.solve()
            # 計算結果の処理


        # 計算終了
        pyemsol.finalize()

``pyemsol.update_Time_Function`` の引数には， *input.json* のデータを指定してください。JSONデータに ``18_Time_Function`` キーが含まれている必要があるためです。

電流位相を更新する場合は， ``PHASE`` を変更します。

サンプルコードは， :ref:`update_Time_Function` を参照してください。