Tutorial

入力ファイルの文法

チュートリアルを始める前に、Mjolnirが受け取る入力ファイルの文法についてお話しておきます。

Mjolnirの入力ファイルは独自の形式ではありません。TOMLという設定ファイル記述用言語を採用しています。いくつかのプロジェクトに既に採用されており、多くのフィードバックと共に成長してきました。 TOMLは、言語仕様をシンプルに小さくまとめ、人間にとっても読みやすい設定ファイルを書けるようにすることを目標に設計されています。

以下にそのレポジトリがあります。READMEで文法が詳しく記述されているので、詳しく知りたい方は参照して下さい。

https://github.com/toml-lang/toml

おおまかに説明しておくと、例えばTOMLのファイルは以下のようになります。

[fruits] # this is a comment.
number = 3
what   = ["apple", "banana", "peach"]

最初の[fruits]がテーブル名で、その下にあるfoo = barが変数の名前とその値を決めています。

TOMLファイルは全体が名前と値を結びつけるテーブルとして構成されています。そしてその値には以下の型が存在します。

型	例	備考
文字列（Unicode）	`"foobar"`	改行する場合、`"""`を使う
整数（符号あり64bit）	`-100_000`	アンダースコア（`_`）を区切り文字に使って良い
浮動小数点数（倍精度）	`3.142_592_653_589`	小数点（`.`）、指数表記（`e`）、あるいはその両方を用いる
真偽値	`true`または`false`
日時	`1979-05-27 07:32:00Z`
配列	`[1, 2, 3, 4, 5]`	末尾にコンマを入れてもよい。要素の間での改行は自由
テーブル	`{num = 42, name = "foo"}`（1行で書く場合）	末尾にコンマを入れてもよい

そう、テーブルも一つの型です。これはどういうことかというと、テーブルの中でテーブルを定義することも、テーブルの配列を作ることもできるということです。

[[sweets]] # [[...]]はテーブルの配列を意味します。
name   = "cookie"
number = 12

[[sweets]] # なので同じ名前のテーブルが複数あって構いません。
name   = "cake"
number = 1

[[foods.fishes]] # foodsというテーブルのfishesという要素がテーブルの配列であることを意味します。
name   = "tuna"
type   = "canned"
number = 3

[[foods.fishes]] # そういうことですね。
name   = "cod"
type   = "dried"
number = 1

短いテーブルは1行で書くこともできて、その場合以下のようになります。上の例だとこちらの方がわかりやすいかもしれません。

[foods]
fishes = [
{name = "tuna", type = "canned", number = 3},
{name = "cod",  type = "dried",  number = 1},
]

上の例を見てお分かりの通り、配列は最後の要素の後にもコンマがあって構いません（誤植じゃないですよ！）。この特徴はスクリプトを使って自動で生成するときに便利です。

TOMLの文法のよりしっかりした解説はTOMLのレポジトリに譲るとして、チュートリアルを始めることにしましょう。

チュートリアル

（製作途中）

リファレンス

Mjolnirの入力ファイルには、大きく分けて5種類のテーブルがあります。

general

全体に関することを決めるテーブルです。例えば、計算精度、出力ファイル名などです。以下の値が必要です。

[general]
precision     = "double"    # "double" または "single"。それぞれ、倍精度、単精度浮動小数点を使います。
boundary      = "Unlimited" # "Unlimited" または "PeriodicCuboid"。境界なし、または直方体の境界を使います。
output_prefix = "result"    # 出力ファイルの名前を決めます。実際に出力されるのはこれに拡張子が付いたものです。
output_path   = "./"        # 出力する場所です。POSIXを仮定しています。

simulator

行うシミュレーションの種類を決めます。

[simulator]
type       = "Molecular Dynamics"
scheme     = "Newtonian"
delta_t    = 0.1
total_step = 50_000
save_step  = 100

Molecular Dynamics

通常のMDシミュレーションです。schemeで使うダイナミクスを、delta_tで時間刻みを、total_stepで合計何ステップシミュレーションするかを、save_stepで何ステップごとにスナップショットを書き出すかを選びます。この時、合計ステップは大きくなりがちなので、アンダースコア（_）を挟むと見やすくなります。

ダイナミクスによっては、追加のパラメータが必要です。例えば、UnderdampedLangevinはseedとそれぞれの粒子に対するgammaの値を要求します。詳細は、それぞれのページを見て下さい（製作途中）。

Steepest Descent

最急降下法を使ってエネルギー最小化を行います。

[simulator]
type       = "Steepest Descent"
delta      = 0.0001
threshold  = 1.0e-7
step_limit = 100_000
save_step  = 100

各粒子にかかる力のdelta倍を粒子の位置に加算し、粒子が動いた距離の最大値がthresholdを下回るまでそれを続けます。下回らないままstep_limitに達した場合、そこで終了します。

Simulated Annealing

焼きなまし法を実行します。主にエネルギーの最小化が目的です。

[simulator]
type       = "Simulated Annealing"
scheme     = "Underdamped Langevin"
total_step = 50_000
save_step  = 100
parameter  = [
# gammas for langevin
]
schedule   = "linear"
T_begin    = 300.0
T_end      = 100.0
each_step  = 100

基本的にMolecular Dynamicsの場合と同じですが、温度管理スケジュールを記載する点が異なります。 scheduleは温度管理の関数を、T_beginは開始時点の温度、T_endは終了時点で到達する温度、each_stepは温度更新のタイミングを決めます。

焼きなまし法では、温度管理をダイナミクスに委ねるため、Newtonianなどの熱浴を持たない手法を用いることはできません。

ファイルを分割する

[[simulator]]テーブルは長くなることがあるので、ファイルを分割したいというのは自然な考えでしょう。その場合、file_nameを定義して、そこにファイルの場所を与えて下さい。

[simulator]
file_name = "input/example-simulator.toml"

file_nameが定義されていると、他のフィールドは無視されます。注意して下さい。

また、ファイルの内容はこの[simulator]の中身として扱われるので、input/example-simulator.tomlの中で[simulator]を定義する必要はありません。それぞれの値を直接書き込んで下さい。

# input/example-simulator.toml
type       = "Molecular Dynamics"
scheme     = "Underdamped Langevin"
seed       = 2374
delta_t    = 0.1
total_step = 50_000
save_step  = 100
parameters = [
{index = 0, gamma = 8.342399e-3},
# ...
]

systems

初期状態や、熱浴が使う参照温度、参照圧力などを決めます。

[[systems]]
attributes = {temperature = 300.0}
boundary = {lower = [0.0, 0.0, 0.0], upper = [32.0, 32.0, 32.0]}
particles = [
{mass = 1.0, position = [ 1.000, 1.000, 1.000], velocity = [ 0.5101, 0.7734, -2.0929]},
]

attribute

attributes = {temperature = 300.0, ionic_strength = 0.1}

attributeには系が持つパラメータ、参照温度などを必要なだけ入力します。値は浮動小数点数です。現在使われているのは、

temperature
- Langevin積分器が使います。
ionic_strength
- DebyeHuckel力場が使います。

です。

boundary

boundary = {} # Unlimitedの場合
boundary = {lower = [0.0, 0.0, 0.0], upper = [32.0, 32.0, 32.0]} # cuboidの場合

境界条件を決めます。境界はどこにあっても構いません（原点中心であるとか、原点から始まるというような制限はありません）。境界がない場合、テーブルは空で構いません。境界がある場合、矩形のそれぞれの座標で小さい方の端に位置している点と、大きい方の端に位置している点を指定します。

particles

particles = [
{mass = 1.0, position = [ 1.000, 1.000, 1.000], velocity = [ 0.5101, 0.7734, -2.0929]},
]

粒子の質量、位置、速度を決めます。

NOTE: 現在、粒子の名称の導入を検討中です。

ファイルを分割する

[[systems]]テーブルは長くなりがちなので、ファイルを分割したいというのは自然な考えでしょう。その場合、file_nameを定義して、そこにファイルの場所を与えて下さい。

[[systems]]
file_name = "input/example-system.toml"

file_nameが定義されていると、他のフィールドは無視されます。注意して下さい。

また、ファイルの内容はこの[[systems]]の中身として扱われるので、input/example-system.tomlの中で[[systems]]を定義する必要はありません。それぞれの値を直接書き込んで下さい。

# input/example-system.toml
attributes = {temperature = 300.0}
boundary = {lower = [0.0, 0.0, 0.0], upper = [32.0, 32.0, 32.0]}
particles = [
{mass = 1.0, position = [ 1.000, 1.000, 1.000], velocity = [ 0.5101, 0.7734, -2.0929]},
]

forcefields

力場のパラメータを決めます。

Mjolnirでは、複数の相互作用（[[local]]など）を一つの力場（[[forcefield]]）として定義すると、それらの総和が力場として適用されます。なので、結合長、結合角、二面角、分子間力にそれぞれ相互作用を導入したい場合、そのそれぞれを定義して下さい。

local

特定の粒子の組にだけ適用される相互作用を、MjolnirではLocalInteractionと呼びます。代表的なものは、結合長、結合角、二面角などがあります。また、native-contact もこれに含みます。

これはforcefieldsのArray of Tables要素として与えられます。まず、相互作用の種類をinteractionで決めます。次に、関数の形をpotentialで決めます。topologyは、後述するglobal相互作用に関連してきます。最後に、関数が取るパラメータを必要な数だけ与えます。結合長ポテンシャルなら2つの粒子間に働くので粒子のインデックスを2つ、調和振動子ポテンシャルなら自然長v0とバネ定数kをそれぞれ与えます。

[[forcefields.local]]
interaction = "BondLength"
potential   = "Harmonic"
topology    = "bond"
parameters  = [
{indices = [0, 1], v0 = 1.0, k = 100.0},
]

local相互作用では、以下の組み合わせを利用可能です。

Interaction	Potential	参考文献等
BondLength	Harmonic	汎用
	Gaussian	汎用(2,3等)
	Go1012Contact	1,2,3
BondAngle	Harmonic	汎用
	FlexibleLocalAngle	4
DihedralAngle	Harmonic	汎用
	Gaussian	汎用(2,3等)
	ClementiDihedral	1
	FlexibleLocalDihedral	4

それぞれどのようなパラメータを指定するかは、個々のページを参照して下さい（製作途中）。

global

適用された粒子の全ての組み合わせにかかる相互作用を、MjolnirではGlobalInteractionと呼びます（他ではnon-localとも呼ばれています）。代表的なものは、分子間力、静電相互作用などです。

localと同様に、相互作用の種類とポテンシャルを定め、他のパラメータを与えていきます。

[[forcefields.global]]
interaction = "Distance"
potential   = "LennardJones"
ignored_chain       = "Nothing"
ignored_connections = {bond = 3, contact = 1}
spatial_partition   = {type = "CellList", margin = 1.0}
parameters = [
{index = 0, sigma = 1.0, epsilon = 0.5},
]

ignored_chainは、相互作用を無視するパターンを決めます。Nothingだと何も無視されません。つまり全ての粒子間に相互作用があります。もしSelfなら、bondで繋がっている粒子の間には相互作用がありません。bondで繋がっている粒子とは、localの要素の中でtopology = "bond"と指定されている相互作用の組だけで辿れる範囲のことを指します。通常、これは一つの分子鎖に相当します。Othersだと逆に、他の分子鎖を無視するので、その分子鎖の中にしか相互作用はかかりません。

`ignored_chain`	相互作用が適用される粒子
`ignored_chain = "Nothing"`	パラメータが定義されているもの全て
`ignored_chain = "Self"`	`topology = "bond"`で繋がっていない組
`ignored_chain = "Others"`	`topology = "bond"`で繋がっている組

分子間力、静電相互作用などは、結合長ポテンシャルなどが既に働いているところは例外的に適用しない、というケースが存在します。そのような場合のため、ignored_connectionsという値があります。これが定義されていると、topologyの種類ごとに、それをN個辿って見つかる組を無視します。例えば、結合長相互作用を3回まで辿って見つかる組（"bond"をエッジとしたグラフ上での距離が3以下の粒子）を全て無視したいとすれば、この値は

ignored_connections = {bond = 3}

のようになります。

MjolnirにはTopology用のファイルは存在せず、local相互作用からTopologyを作成するので、bondとして扱いたい[[local]]相互作用でtopology = "bond"としておくのを忘れないようにしましょう。

spatial_partitionは、セルリストなどによる空間分割のためのパラメータです。何か理由がない限り、CellListで構いません。marginは、ベルレリストのマージンで、計算結果には影響しませんが、計算速度に影響します。適宜調節して下さい。

global相互作用では、以下の組み合わせを利用可能です。

Interaction	Potential	参考文献等
Distance	ExcludedVolume	1,2,3等
	LennardJones	汎用
	DebyeHuckel	汎用

それぞれどのようなパラメータを指定するかは、個々のページを参照して下さい（製作途中）。

external

粒子間に働く力でなく、外力として加わるポテンシャルを、、MjolnirではExternalInteractionと呼びます。代表的なものは、壁ポテンシャルや、粒子を空間中にバネで固定するポテンシャルなどです。

[[forcefields.external]]
interaction = "Distance"
shape       = {name = "AxisAlignedPlane", axis = "+Z", position =  1.0, margin = 0.5}
potential   = "LennardJonesWall"
parameters = [
{index = 0, group = 0, hydrophobicity = 1.0},
]

ここでは、「形状」に対する距離に対するポテンシャルを適用します。この形状として、現在軸に沿った平面が利用可能です。

ファイルを分割する

[[forcefields]]テーブルは長くなりがちなので、ファイルを分割したいというのは自然な考えでしょう。その場合、他と同様file_nameを定義して、そこにファイルの場所を与えて下さい。

[[forcefields]]
file_name = "input/example-forcefield.toml"

file_nameが定義されていると、他のフィールドは無視されます。注意して下さい。

また、ファイルの内容はこの[[forcefields]]の中身として扱われるので、input/example-forcefield.tomlの中で[[forcefields]]を定義する必要はありません。[[local]]、[[global]]、[[external]]をそれぞれ直接定義して下さい。

# [[forcefields]]として読み込まれるファイルでは、[[forcefields.local]] とする必要はありません。
[[local]]
# ...
[[local]]
# ...
[[global]]
# ...

parameters

物理定数の値を決めます。力場に沿った値を選んで下さい。

kB   = 1.986231313e-3  # Boltzmann constant
NA   = 6.0221417930e23 # Avogadro constant
e    = 1.0             # elementary charge
"ε0" = 8.854187817e-12 # permittivity of vaccum

単位変換などについては導入を検討中です。現時点では、入力ファイル中で整合性を取るようにしてください。

参考文献

Clementi, C., Nymeyer, H., Onuchic, J., 2000. Journal of Molecular Biology
Li, W., Terakawa, T., Wang, W., Takada, S., 2012. Proceedings of the National Academy of Sciences
Li, W., Wang, W., Takada, S., 2014. Proceedings of the National Academy of Sciences
Terakawa, T., Takada, S., 2011. Biophysical Journal

Navigation Menu

Uh oh!

Tutorial

目次

入力ファイルの文法

チュートリアル

リファレンス

general

simulator

Molecular Dynamics

Steepest Descent

Simulated Annealing

ファイルを分割する

systems

attribute

boundary

particles

ファイルを分割する

forcefields

local

global

external

ファイルを分割する

parameters

参考文献

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally