:tocdepth: 1

===============================================
--graphオプション使ったNETWORK要素のグラフ出力
===============================================

.. index::
	single: --graphオプション 

.. role:: red
.. role:: blue

[|today| 更新]

| emyコマンドは，**--graph** オプションを指定することで，NETWORK要素のグラフを **dotファイル** として出力します．
| **dotファイル** のファイル名は，出力ファイル名 + ".dot"となります． 
| emsファイルを読み込み，それから **dotファイル** を出力することもできます．

.. _graphdata:

NETWORK要素のグラフデータ
============================

| NETWORK要素は互いに接続されており，この接続の関係をグラフデータ( **dotファイル** )として出力することができます． 
| グラフデータは

* **ノード**
* **エッジ** （両端の **ノード** を結んだもの）

| で構成され，NETWORK要素は **エッジ** に該当します（ **ノード** ではありません）
| 例えば，(a)図に示すR + CPS回路の場合，(b)図に示すのがグラフデータです．
| ●が **ノード** で，FEM, R, CPSの各NETWORK要素は， **エッジ** 上にあります．

.. image:: png/networkgraph1.png
	:align: center

| 実際のグラフデータでは，回路を認識しやすくするため

* FEMシリーズ要素は :red:`赤色`
* CPSおよびVPSの電源要素は :blue:`青色`
* 要素名_IDという形式で要素の識別番号を含めた名称で表示
* 一部の要素を除いて矢印で方向を表す

| として処理されます． 
| 例えば，(c)図は，

.. csv-table:: NETWORK回路
	:header: NETWORK要素, ID, 説明
	:widths: 2, 1, 5 

	FEM, 1, 有限要素法領域内のソース
	R, 2, 抵抗
	CPS, 3, 定電流源

のNETWORK要素のグラフデータを示したものです．

.. image:: png/networkgraph2.png
	:align: center

グラフデータに含まれないNETWORK要素
============================================================

| 以下に列記するNETWORK要素は，**回路に接続されない要素** のため， 
| **グラフデータには含まれません** （無視されます）． 

.. csv-table:: グラフデータの含まれないNETWORK要素
	:header: NETWORK要素, 説明
	:widths: 2, 5 

	:ref:`table`, "電流vs電圧のテーブルの定義"
	:ref:`setv`, "NETWORK要素の初期印加電圧"
	:ref:`seti`, "NETWORK要素の初期電流"

方向を含まないNETWORK要素
============================================================

| 基本的に，NETWORK要素は方向を持っています．
| 例えば，CPS要素は，矢印の根元から先端に向かう方向を正の電流値とします（c図参照）．
| これに対し，下記の **方向があまり意味のないNETWORK要素は方向を表示しません** （c図のR要素参照）．

.. csv-table:: 方向を表示しないNETWORK要素
	:header: NETWORK要素, 説明
	:widths: 2, 5 

	:ref:`r`, "抵抗要素"
	:ref:`l`, "インダクタンス要素"
	:ref:`m`, "相互インダクタンス要素"
	:ref:`vr`, "可変抵抗要素"
	:ref:`switch`, "スイッチ要素"

相互インダクタンス要素を含むケース
============================================================

| NETWORK要素は基本的に **ノード** ではなく， **エッジ** に定義されますが，
| 相互インダクタンスは，1組のインダクタンスの間の要素となるため，
| 相互インダクタンス要素を含むケースのみ，インダクタンスの中央に別途 **ノード** を定義します．
| (d)図に相互インダクタンスが無いケース，(e)図に相互インダクタンスがあるケースを示します．
| (e)図より，相互インダクタンスがあるケースでは，1組のインダクタンス中央に定義されたが **ノード** を結ぶ **エッジ** に相互インダクタンスが定義されることが分かります（インダクタンスは2本のエッジに分割される）．

.. image:: png/networkgraph3.png
	:align: center

| ちなみに，グラフデータにおける **ノード** は，色々な画像を使えるので便利なのですが，
| NETWORK要素を **ノード** ではなく **エッジ** に定義するのは，(e)図から明らかなように，
| **ノード** に定義すると，レイアウトが崩れて，かえって識別しにくくなってしまうためです．

グラフデータのレイアウトについて
============================================================

| グラフデータは，各 **ノード** の接続状況を示すためのデータであるため，
| 画面描画した際に， **ノード** がどの位置に配置（レイアウト）されるかは任意です．
| **dotファイル** には，レイアウトを指定する項目があり，実際に幾つかレイアウトの種類はありますが，
| NETWORK要素のような回路を描画するのに適したレイアウトは残念ながらありません．
| **EMY** では，エッジの長さを設定出来る **fdp** をレイアウトに採用しています．
| グラフデータのNETWORK要素が潰れて見えない場合などは， **dotファイル** の下記の項目の数値を変更して調整して下さい．
| （但し，レイアウトも変更されます）

.. csv-table:: エッジの長さに関する設定項目 
	:header: 項目, 既定値, 説明
	:widths: 2, 1, 5 

	graph[K], 1, "（エッジの）ばね定数"
	edge[len], 1, "（エッジの）長さ"

.. code-block:: none

	graph network {

		// graph define
		graph[
			layout = fdp,
			K = 1        // Kの項
		];

		... // 省略

		// edge define
		edge [
			len = 1      // lenの項
			labelfloat = true
		];

グラフデータの描画ソフト
============================================================

| **dotファイル** を描画するには，https://www.graphviz.org/ を使うのが最も簡単です．
| 但し，グラフデータを描画することはできても，**ノード** を移動させることはできません．
| **dotファイル** はグラフデータ用の汎用フォーマットなので，色々なソフトで読み込むことができます．
| しかし，**ノード** の接続のみデータとして使用し，それ以外は無視する処理などを行っているソフトもあり，そのようなソフトではNETWORK要素の接続状況を描画させるのには向いていません．
