:tocdepth: 1

==================================
EMY(EMsolution Yaml)フォーマット
==================================

.. index::
	single: EMYフォーマット 

[|today| 更新]

.. only:: html or singlehtml
.. raw:: html

	<div id="show-hide-switch-1" title="表示/非表示切り替え">EMYフォーマットとは</div>
	<div id="show-hide-target-1">

| EMSolutionの入力ファイル(inputファイル)を作成するための，新しいフォーマット形式です．

| **必要な設定項目のみ** を記載すれば， **emyコマンド** を使って，inputファイルを生成することができます． 
| EMYファイルに記載されていない設定項目は，**既定値** が代入されます．

| 設定項目は，**タグ** と呼ばれる指標でグループ分けされています．
| さらに，各設定項目は，ハンドブックのNameと同じ名称の **ラベル** で指定して
| 値を設定します．

| 例えば，ハンドブックの
|    1. 実行制御
| のPOST_PROCESSINGという項目は，
| control **タグ** と，POST_PROCESSING **ラベル** を使って

.. code-block:: none

	control:
	  POST_PROCESSING: 1

| という具合に設定します．

| **タグ** (小文字)は，グループ分けされた設定項目の指標で， **ラベル** (大文字)は，それぞれの設定項目を示します．
| 値を設定するのは **ラベル** です．
| 両者の判別するには，**タグは小文字** で， **ラベルは大文字** であることを覚えておくと便利です．

| **タグでグループ分けされた各データを設定する順番は任意** です．
| 従来のinputファイルのように，最初にリリース番号，実行制御から始まって，移動の定義，B-Hカーブで終わるような制限はありません．

| EMYフォーマットは， **YAMLフォーマット** をより使いやすくするために考案されました．

.. only:: html or singlehtml
.. raw:: html

	</div><!-- show-hide-target-1 -->

.. only:: html or singlehtml
.. raw:: html

	<div id="show-hide-switch-2" title="表示/非表示切り替え">YAMLフォーマットとは</div>
	<div id="show-hide-target-2">

| 構造的(階層的)なデータを記載するための汎用的なフォーマットです．
| C++/C#/Pythonなどの各種プログラミング言語で幅広く使われています．

| XMLやjsonなどの他の汎用フォーマットに比べて，人にとってより分かりやすい（階層構造をインデントで表す，etc.,）特長を持っています．

| emyコマンドを使うと，YAMLファイルも同時に生成されます．
| これは， **EMYファイルはユーザが手作業で作成** する用途なのに対し， **YAMLファイルはユーザがプログラミングで加工･修正して生成** する用途を想定しているためです．
| もちろん，EMYファイルをプログラミングで生成しても，YAMLファイルを手作業で作成してもかまいません．

.. only:: html or singlehtml
.. raw:: html

	</div><!-- show-hide-target-2 -->

.. only:: html or singlehtml
.. raw:: html

	<div id="show-hide-switch-3" title="表示/非表示切り替え">emyコマンドとは</div>
	<div id="show-hide-target-3">

| EMYファイルを読み込んで，YAMLファイル，inputファイルを生成します．
| YAMLファイル，inputファイルを読み込むこともできます．

.. csv-table::
	:header: 読込み, YAMLファイル, inputファイル
	:widths: 1, 1, 1

 	EMYファイル, ○, ○
	YAMLファイル, "", ○
	inputファイル, "", ○

| inputファイルを読み込んで，inputファイルを生成することに何の意味があるのでしょうか？
| その答えは，異なるinputファイルを同じフォーマットで出力することです．

| 例えば，A1, A2という2つのinputファイルがあるとします．
| この2つのinputファイルを，文字列として比較すると，同じデータでも異なったデータだと判定されてしまう問題が生じます．
| emyコマンドで，A1, A2のinputファイルから，A1_1, A2_1という具合にinputファイルを生成し，A1_1, A2_1ファイルを比較すれば，文字列として比較しても問題は生じにくくなります．

.. only:: html or singlehtml
.. raw:: html

	</div><!-- show-hide-target-3 -->

.. only:: html or singlehtml
.. raw:: html

	<div id="show-hide-switch-4" title="表示/非表示切り替え">ネストしたタグ</div>
	<div id="show-hide-target-4">

| 一部のタグは，特定のタグの下層にあります．
| 例えば，境界条件を表す **bcタグ** の下層に，
| **far** , **dirichlet** , **neumann** , **zeroaline** タグがあります．
| これらの階層によるタグを分別するために，下層にあるタグを，何階層目にあるかを使って呼ぶことにします．
| つまり, 上記の **far** ～ **zeroaline** タグは，第2タグと呼ぶことにします．
| **bc** タグも第1タグと呼ぶべきですが，冗長になるため，第1階層目のタグは，そのままのタグ名を使うことにします．

.. only:: html or singlehtml
.. raw:: html

	</div><!-- show-hide-target-4 -->

emyコマンドの使い方
====================

| EMYファイル，YAMLファイル，inputファイルは，拡張子で(自動的に)識別されます．
| emyコマンドは，読み込んだファイルの拡張子で，ファイルの種類を判別します．
| 拡張子を省略したファイル名の場合，
|    1) emy  2) yml  3) ems
| の順番で，拡張子を補完して該当するファイルを読み込みを試行します．

.. csv-table:: ファイル形式と拡張子
	:header: ファイル, 拡張子
	:widths: 2, 2

 	EMYファイル, emy
	YAMLファイル, yml
	inputファイル, ems

emyコマンドは各種オプションを持っています．

.. csv-table:: emyコマンドのオプション
	:header: オプション, 説明
	:widths: 1, 4

	-d, 読込み/出力ファイルのディレクトリ
	-i, 読込みファイル名
	-o, 出力ファイル名
	--import, :doc:`元になる .emsファイルの読み込み <import>`
	--config, :doc:`configファイルの読み込み <config>`
	--graph, :ref:`graphdata` の出力
	-c, inputファイル読み込み時のコメントの上書き
	--version, バージョン表示
	-h, ヘルプ表示

最も簡単な使い方
------------------

コマンドの引数が1つの場合は，それを読込ファイルとして認識して処理します．

.. code-block:: none

	emy 読込みファイル名


| 例えば，input.emyというEMYファイルからinput.emsファイルを生成するには，
| 下記のコマンドを実行すれば良いです．

.. code-block:: none

	emy input.emy 

| input1.emyというEMYファイルからinput2.emsファイルというように
| 名称を変更したinputファイルを生成するには，

.. code-block:: none

	emy -i input1.emy -o input2.ems

| とコマンドを実行して下さい．

| EMYファイルからNETWORK要素のグラフデータを出力するには，

.. code-block:: none

	emy -i input1.emy --graph

| とコマンドを実行すれば，**dotファイル** が生成されます．

