3. Input Script¶

3.1. LIGGGHTS(R)-PUBLIC input script¶

LIGGGHTS（R）-PUBLIC は、入力スクリプト（テキストファイル）からコマンドを一度に1行ずつ読み込むことで実行されます。 入力スクリプトが終了すると、LIGGGHTS（R）-PUBLICが終了します。 各コマンドは、LIGGGHTS（R）-PUBLICに何らかのアクションを実行させます。 内部変数を設定したり、ファイルを読み込んだり、シミュレーションを実行することができます。 ほとんどのコマンドにはデフォルト設定があります。つまり、デフォルトを変更する場合は、コマンドを使用するだけです。

多くの場合、入力スクリプト内のコマンドの順序は重要ではありません。 ただし、次の規則が適用されます。

（1）LIGGGHTS（R）-PUBLICは入力スクリプト全体を読んでいないので、すべての設定でシミュレーション を実行します。 むしろ、入力スクリプトは一度に1行ずつ読み込まれ、各コマンドは読み込まれると有効になります。 したがって、この一連のコマンドは次のとおりです。

LIGGGHTS(R)-PUBLIC executes by reading commands from a input script (text file), one line at a time. When the input script ends, LIGGGHTS(R)-PUBLIC exits. Each command causes LIGGGHTS(R)-PUBLIC to take some action. It may set an internal variable, read in a file, or run a simulation. Most commands have default settings, which means you only need to use the command if you wish to change the default.

In many cases, the ordering of commands in an input script is not important. However the following rules apply:

(1) LIGGGHTS(R)-PUBLIC does not read your entire input script and then perform a simulation with all the settings. Rather, the input script is read one line at a time and each command takes effect when it is read. Thus this sequence of commands:

timestep 0.5
run      100
run      100

does something different than this sequence:

run      100
timestep 0.5
run      100

最初のケースでは、指定されたタイムス テップ（0.5 fmsec）が100回のタイムステップの2回のシミュレーションに使用されます。 2番目のケースでは、最初の100ステップシミュレーションではデフォルトのタイムステップ（1.0 fmsec）が使用され、2番目のタイムスタンプでは0.5 fmsecのタイムステップが使用されます。

（2）一部のコマンドは、他のコマンドに従う場合にのみ有効です。たとえば、atomが定義され、groupコマンドが グルー プに属しているatomを定義するまで、atomグループの温度を設定することはできません。

（3）コマンドBは、コマンドAで設定できる値を使用することがあります。これは、コマンドAが入力スクリプト内でコマ ンドBより先になければならないことを意味します。たとえば、read_dataコマンドは、シミュレーションボックス を設定し、atomをプロセッサに割り当てることによってシステムを初期化します。デフォルト値が望ましくない場合は、 processorとboundaryコマンドをread_dataの前に使用して、LIGGGHTS（R）- PUBLICにプロセッサをシ ミュレーションボックスにマップする方法を伝える必要があります。

多くの入力スクリプトエラーはLIGGGHTS（R）-PUBLICによって検出され、ERRORまたはWARNING メッセージが出力されます。このセクションでは、エラーの意味について詳しく説明します。各コマンドのドキュメントに は、コマンドの使用方法に関する制限事項が記載されています。

In the first case, the specified timestep (0.5 fmsec) is used for two simulations of 100 timesteps each. In the 2nd case, the default timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5 fmsec timestep is used for the 2nd one.

(2) Some commands are only valid when they follow other commands. For example you cannot set the temperature of a group of atoms until atoms have been defined and a group command is used to define which atoms belong to the group.

(3) Sometimes command B will use values that can be set by command A. This means command A must precede command B in the input script if it is to have the desired effect. For example, the read_data command initializes the system by setting up the simulation box and assigning atoms to processors. If default values are not desired, the processors and boundary commands need to be used before read_data to tell LIGGGHTS(R)-PUBLIC how to map processors to the simulation box.

Many input script errors are detected by LIGGGHTS(R)-PUBLIC and an ERROR or WARNING message is printed. This section gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used.

3.2. Parsing rules¶

入力スクリプトの各空白でない行はコマン ドとして扱われます。 LIGGGHTS（R）-PUBLICコマンドは大文字と小文字を区別します。コマンド名は、指定されたコマンド引数と同様に小文字です。ファイル名やユーザーが選択した ID文字列には、大文字を使用できます。

入力スクリプトの各行がLIGGGHTS（R）-PUBLICによってどのように解析されるかを以下に示します。

（1）行の最後の出力可能な文字が "＆"（囲まれた引用符なし）の場合、コマンドは次の行に続くとみなされます。 "＆"文字と改行を削除することによって、次の行が前の行に連結されます。これにより、2つ以上の行にわたって長いコマンドを続けることができます。

（2）最初の "＃"文字以降の文字はすべてコメントとして扱われ、破棄されます。 （6）の例外を参照してください。末尾の "＆"文字の後のコメントは、コマンドが次の行に続くのを防ぎます。また、複数行のコマンドの場合、1つの先頭の「＃」がコマンド全体をコメントアウトします。

（3）テキスト文字列に置き換えられた変数を示す$文字が繰り返し検索されます。 （6）の例外を参照してください。

$の後に中括弧が続く場合、変数名は中括弧の中のテキストです。 $に続く中括弧がない場合、変数名は$の直後の1文字です。したがって、$ {myTemp}と$ xは変数名 "myTemp"と "x"を参照します。

$に括弧が続く場合、括弧内のテキストは「即時」変数として扱われ、equal-style variableとして評価されます。これは、 変数名に代入することなく、入力スクリプトで数値式を使用する方法です。たとえば、次の3つの入力スクリプト行がありま す。

Each non-blank line in the input script is treated as a command. LIGGGHTS(R)-PUBLIC commands are case sensitive. Command names are lower-case, as are specified command arguments. Upper case letters may be used in file names or user-chosen ID strings.

Here is how each line in the input script is parsed by LIGGGHTS(R)-PUBLIC:

(1) If the last printable character on the line is a “&” character (with no surrounding quotes), the command is assumed to continue on the next line. The next line is concatenated to the previous line by removing the “&” character and newline. This allows long commands to be continued across two or more lines.

(2) All characters from the first “#” character onward are treated as comment and discarded. See an exception in (6). Note that a comment after a trailing “&” character will prevent the command from continuing on the next line. Also note that for multi-line commands a single leading “#” will comment out the entire command.

(3) The line is searched repeatedly for $ characters, which indicate variables that are replaced with a text string. See an exception in (6).

If the $ is followed by curly brackets, then the variable name is the text inside the curly brackets. If no curly brackets follow the $, then the variable name is the single character immediately following the $. Thus ${myTemp} and $x refer to variable names “myTemp” and “x”.

If the $ is followed by parenthesis, then the text inside the parenthesis is treated as an “immediate” variable and evaluated as an equal-style variable. This is a way to use numeric formulas in an input script without having to assign them to variable names. For example, these 3 input script lines:

variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete

can be replaced by

region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

一時変数Xを定義（または破棄）する必要 はありません。

変数の中のかっこまたは即時形式には、他の変数の代わりにネストになった$文字を含めることはできません。 したがって、これを行うことはできません：

so that you do not have to define (or discard) a temporary variable X.

Note that neither the curly-bracket or immediate form of variables can contain nested $ characters for other variables to substitute for. Thus you cannot do this:

variable        a equal 2
variable        b2 equal 4
print           "B2 = ${b$a}"

また、即時変数に対して$（$ x-1.0）を指定することはできませんが、後者はequal-style variableの 有効な構文なので$（v_x-1.0）を使用できます。

文字列を変数に代入して評価する方法と、入力スクリプトコマンドで文字列を使用する方法の詳細については、 variableコマンドを参照してください。

（4）行は空白（タブ、スペース）で区切られた "単語"に分割されます。 単語には、文字、数字、アンダースコア、句読点などが含まれることに注意してください。

（5）最初の単語はコマンド名です。 行のすべての連続した単語は引数です。

（6）空白を含むテキストを単一の引数として扱う場合は、二重引用符または一重引用符で囲むことができます。 例えば

Nor can you specify this $($x-1.0) for an immediate variable, but you could use $(v_x-1.0), since the latter is valid syntax for an equal-style variable.

See the variable command for more details of how strings are assigned to variables and evaluated, and how they can be used in input script commands.

(4) The line is broken into “words” separated by whitespace (tabs, spaces). Note that words can thus contain letters, digits, underscores, or punctuation characters.

(5) The first word is the command name. All successive words in the line are arguments.

(6) If you want text with spaces to be treated as a single argument, it can be enclosed in either double or single quotes. E.g.

print "Volume = $v"
print 'Volume = $v'
if "$*steps* > 1000" then quit

引用符は、単一の引数が内部的に格納され ているときに削除されます。 例については、dump modify format または print または if コマンドを参照してください。例えば、引用符の間にある "＃"または "$"は、（2）のコメントインジケータとして扱われることも、（3）の変数として代用されることもありません。

The quotes are removed when the single argument is stored internally. See the dump modify format or print or if commands for examples. A “#” or “$” character that is between quotes will not be treated as a comment indicator in (2) or substituted for as a variable in (3).

3.3. Input script structure¶

このセクションでは、典型的な LIGGGHTS（R）-PUBLIC入力スクリプトの構造について説明します。 LIGGGHTS（R）-PUBLICディストリビューションの "examples"ディレクトリには、多くのサンプル入力スクリプトが含まれています。 対応する問題はSection_exampleで議論され、LIGGGHTS（R）-PUBLIC WWWサイトでアニメ化されます。

LIGGGHTS（R）-PUBLIC入力スクリプトには、通常4つの部分があります。

1. 初期化
2. atom/粒子の定義と挿入
3. 設定
4. シミュレーションを実行する

最後の2つの部分は、必要な回数だけ繰り 返すことができます。 すなわち、シミュレーションを実行し、いくつかの設定を変更し、さらに動作させるなどである.4つの部分のそれぞれについて、より詳細に説明する。 ほとんどのコマンドは、デフォルト以外の値が必要な場合にのみ使用する必要があることに注意してください。

atomまたは粒子がファイルから作成ま たは 読み込まれる前に定義する必要があるパラメータを設定します。

関連するコマンドは、unit、dimension、newton、processors、boundary、 atom_style、atom_modifyです。

force-fieldパラメーターが読み込まれるファイルに現れた場合、これらのコマンドは、使用されている力の forceフィールドの種類（pair_style、bond_style、fix wall / gran）をLIGGGHTS（R）-PUBLICに伝えます。

granular壁は、通常、メッシュを使用する必要があります。 詳細については、fix mesh/surfaceを参照してください。

LIGGGHTS（R）-PUBLICに はatomを定義する3つの方法があります。 read_dataまたはread_restartコマンドを使用して、データまたはリスタートファイルからそれらを読み込みます。 あるいは、lattice、region、create_box、create_atomsの各コマンドを使って格子上 にatomを作成します。

しかし、granular粒子を挿入する最も一般的な方法は、fix / insert*コマンドのうちの1つを使用することです：fix / insert / pack、 "fix insert / stream" stream.html、fix / insert / rate / region

これらの挿入コマンドを使用する前に、粒子テンプレートを使用して粒子ディストリビューション（fix / particulateistribution / discrete）を構築します。 球形の粒子の場合、そのような粒子のテンプレートは、fix / particletemplate / sphereを使用して定義される。

　3.設定

atomが定義されると、シミュレーショ ンパ ラメータ、出力オプションなど、さまざまな設定を指定できます。

材料パラメータと力のフィールド係数 は、これらのコマンドによって設定されます。fix property / global、または pair_coeff、bond_coeff。

これらのコマンドによって、さまざまなシ ミュレーションパラメータが設定されます：neighbor、neigh_modify、group、 timestep、region、reset_timestep、run_style、

fixでは、さまざまな境界条件、時間積 分、診断オプションが適用されます。 fixコマンドには多くの味があります。

さまざまな計算を、compute、 compute_modify、およびvariableコマンドを使用してシミュレーション中に実行するように指定することができます。

出力オプションは、thermo、 dump、およびrestartコマンドによって設定されます。

 4.シミュレーションを実行 する

runコマンドを使用してシミュレーショ ンが実行されます。

This section describes the structure of a typical LIGGGHTS(R)-PUBLIC input script. The “examples” directory in the LIGGGHTS(R)-PUBLIC distribution contains many sample input scripts; the corresponding problems are discussed in Section_example, and animated on the LIGGGHTS(R)-PUBLIC WWW Site.

A LIGGGHTS(R)-PUBLIC input script typically has 4 parts:

1. Initialization
2. Atom/particle definition and insertion
3. Settings
4. Run a simulation

The last 2 parts can be repeated as many times as desired. I.e. run a simulation, change some settings, run some more, etc. Each of the 4 parts is now described in more detail. Remember that almost all the commands need only be used if a non-default value is desired.

1. Initialization

Set parameters that need to be defined before atoms/particles are created or read-in from a file.

The relevant commands are units, dimension, newton, processors, boundary, atom_style, atom_modify.

If force-field parameters appear in the files that will be read, these commands tell LIGGGHTS(R)-PUBLIC what kinds of force fields are being used: pair_style, bond_style, fix wall/gran .

Granular walls typically require meshes to be used. See fix mesh/surface for details.

2. Atom/particle definition and insertion

There are 3 ways to define atoms in LIGGGHTS(R)-PUBLIC. Read them in from a data or restart file via the read_data or read_restart commands. Or create atoms on a lattice using these commands: lattice, region, create_box, create_atoms.

However, the most common way to insert granular particles is to use one of the fix insert/* commands: fix insert/pack, “fix insert/stream”stream.html, fix insert/rate/region

Before these insertion commands can be used, particle distributions (fix particledistribution/discrete) are built up using particle templates. For spherical particles, such particle templates are defined using fix particletemplate/sphere.

3. Settings

Once atoms are defined, a variety of settings can be specified: simulation parameters, output options, etc.

Material parameters and force field coefficients are set by these commands fix property/global, or pair_coeff, bond_coeff.

Various simulation parameters are set by these commands: neighbor, neigh_modify, group, timestep, region, reset_timestep, run_style,

Fixes impose a variety of boundary conditions, time integration, and diagnostic options. The fix command comes in many flavors.

Various computations can be specified for execution during a simulation using the compute, compute_modify, and variable commands.

Output options are set by the thermo, dump, and restart commands.

4. Run a simulation

A simulation is run using the run command.

3.4. An example input script¶

これは、LIGGGHTS（R）- PUBLICシミュレーションの入力スクリプト例を示しています。

This shows an example input script for a LIGGGHTS(R)-PUBLIC simulation.

#Contact model example
atom_style   granular
atom_modify  map array
boundary     m m m
newton       off
communicate   single vel yes
units        si
region       reg block -0.05 0.05 -0.05 0.05 0. 0.15 units box
create_box   1 reg
neighbor     0.002 bin
neigh_modify delay 0
#Material properties required for pair style
fix          m1 all property/global youngsModulus peratomtype 5.e6
fix          m2 all property/global poissonsRatio peratomtype 0.45
fix          m3 all property/global coefficientRestitution peratomtypepair 1 0.95
fix          m4 all property/global coefficientFriction peratomtypepair 1 0.05
pair_style   gran model hertz tangential history
pair_coeff    * *
timestep     0.00001
fix          gravi all gravity 9.81 vector 0.0 0.0 -1.0
fix          zwalls1 all wall/gran model hertz tangential history primitive type 1 zplane 0.0
fix          zwalls2 all wall/gran model hertz tangential history primitive type 1 zplane 0.15
fix          cylwalls all wall/gran model hertz tangential history primitive type 1 zcylinder 0.05 0. 0.
#region of insertion
region       bc cylinder z 0. 0. 0.045 0.00 0.15 units box
#particle distributions
fix          pts1 all particletemplate/sphere 12345787 1 density constant 2500 radius constant 0.0025
fix          pdd1 all particledistribution/discrete 17903  1 pts1 1.0
fix          ins all insert/pack seed 123457 distributiontemplate pdd1 vel constant 0. 0. -0.5 &
             insert_every once overlapcheck yes all_in yes particles_in_region 1800 region bc
#apply nve integration to all particles
fix          integr all nve/sphere
#output settings, include total thermal energy
compute         rke all erotate/sphere
thermo_style    custom step atoms ke c_rke vol
thermo          1000
thermo_modify   lost ignore norm no
compute_modify  thermo_temp dynamic yes
dump            dmp all custom 800 post/dump*.newModels id type x y z ix iy iz vx vy vz fx fy fz omegax omegay omegaz radius
#insert particles and run
run             5000