9. Modifying & extending LIGGGHTS(R)-PUBLIC¶

9.1. Atom styles¶

atomスタイルを定義するクラスは、 AtomVecクラスから派生し、Atomクラスによって管理されます。 atomスタイルは、atomに関連付けられている属性を決定します。 既存のatomスタイルの1つが、atomを保存して通信するために必要なすべての属性を定義していない場合、新しいatomスタイルを作成できます。

Atom_vec_atomic.cppは、atomスタイルの簡単な例です。

ここでは、新しい派生クラスで定義するメソッドについて簡単に説明します。 詳細はatom_vec.hを参照してください。

Classes that define an atom style are derived from the AtomVec class and managed by the Atom class. The atom style determines what attributes are associated with an atom. A new atom style can be created if one of the existing atom styles does not define all the attributes you need to store and communicate with atoms.

Atom_vec_atomic.cpp is a simple example of an atom style.

Here is a brief description of methods you define in your new derived class. See atom_vec.h for details.

派生クラスのコンストラクタは、新しい atomスタイルを定義するときに設定する必要があるいくつかの変数の値を設定します。これらはatom_vec.hに 記録 されています。 新しいatom配列はatom.cppで定義されています。 「customize」という単語を検索すると、修正が必要な場所が見つかります。

The constructor of the derived class sets values for several variables that you must set when defining a new atom style, which are documented in atom_vec.h. New atom arrays are defined in atom.cpp. Search for the word “customize” and you will find locations you will need to modify.

LIGGGHTS（R）-PUBLICに 新しいペアのスタイル、fix、またはcomputeを追加することができます。 これらのクラスのコードでは、fix property / atomで定義されたatomごとのプロパティを使用できます。 Atomクラスには、このコンテキストで便利なfind_custom（）メソッドがあります。

New pair styles, fixes, or computes can be added to LIGGGHTS(R)-PUBLIC, as discussed below. The code for these classes can use the per-atom properties defined by fix property/atom. The Atom class has a find_custom() method that is useful in this context:

int index = atom->find_custom(char *name, int &flag);

fix property / atomコマンドで指定されたカスタム属性の「name」がチェックされ、存在し、そのindexが返されていることを確認します。 また、このメソッドは、整数か浮動小数点のどちらの属性であるかに応じて、flag = 0/1を設定します。 返されたindexを使用して、属性に関連付けられた値のベクトルにアクセスできます。

The “name” of a custom attribute, as specified in the fix property/atom command, is checked to verify that it exists and its index is returned. The method also sets flag = 0/1 depending on whether it is an integer or floating-point attribute. The vector of values associated with the attribute can then be accessed using the returned index as

int *ivector = atom->ivector[index];
double *dvector = atom->dvector[index];

Ivectorまたはdvectorは長 さのベクトルです。Nlocal =所有するatomの数で、個々のatomの属性を格納します。

Ivector or dvector are vectors of length Nlocal = # of owned atoms, which store the attributes of individual atoms.

9.2. Compute styles¶

温度と圧力テンソルのようなスカラー量と ベクトル量を計算するクラスと、運動エネルギーや中心対称パラメータのようなatomごとの量を計算するクラスは、 Computeクラスから派生します。 LIGGGHTS（R）-PUBLICに新しい計算を追加するための新しいスタイルを作成することができます。

Compute_temp.cppは、スカラー温度を計算する簡単な例です。 Compute_ke_atom.cppは、atomごとの運動エネルギーを計算する簡単な例です。

ここでは、新しい派生クラスで定義するメソッドについて簡単に説明します。 詳細については、compute.hを参照してください。

Classes that compute scalar and vector quantities like temperature and the pressure tensor, as well as classes that compute per-atom quantities like kinetic energy and the centro-symmetry parameter are derived from the Compute class. New styles can be created to add new calculations to LIGGGHTS(R)-PUBLIC.

Compute_temp.cpp is a simple example of computing a scalar temperature. Compute_ke_atom.cpp is a simple example of computing per-atom kinetic energy.

Here is a brief description of methods you define in your new derived class. See compute.h for details.

9.3. Dump styles¶

9.4. Dump custom output options¶

ファイルへのatomごとの情報をダンプ するクラ スは、Dumpクラスから派生します。 新しい量または新しい形式でダンプする為に、新しい派生dumpクラスを追加することができますが、dump_custom.cppファイルに含まれる DumpCustomクラスを変更する方が簡単です。

Dump_atom.cppは、派生ダンプクラスの簡単な例です。

ここでは、新しい派生クラスで定義するメソッドについて簡単に説明します。 詳細については、dump.hを参照してください。

Classes that dump per-atom info to files are derived from the Dump class. To dump new quantities or in a new format, a new derived dump class can be added, but it is typically simpler to modify the DumpCustom class contained in the dump_custom.cpp file.

Dump_atom.cpp is a simple example of a derived dump class.

Here is a brief description of methods you define in your new derived class. See dump.h for details.

DumpCustomで既にダンプできる atom情報のキーワードのリストについては、dumpコマンドとそのカスタムスタイルを参照してください。 ComputeクラスからAtom情報をダンプするオプションが含まれているので、新しい派生Computeクラスを追加することは、ダンプする新しい量を計算する1つの 方法です。

あるいは、dump customコマンドに新しいキーワードを追加することもできます。 dump_custom.cppで "customize"という単語を検索して、コードを追加する必要がある半角またはそれ以上の場所を確認します。

See the dump command and its custom style for a list of keywords for atom information that can already be dumped by DumpCustom. It includes options to dump per-atom info from Compute classes, so adding a new derived Compute class is one way to calculate new quantities to dump.

Alternatively, you can add new keywords to the dump custom command. Search for the word “customize” in dump_custom.cpp to see the half-dozen or so locations where code will need to be added.

9.5. Fix styles¶

LIGGGHTS（R）-PUBLICに おいて、「fix」は、システムのいくつかの特性を変更するタイムステッピング中に計算される任意の演算である。 基本的には、力の計算、隣接リストの作成、出力のほかにシミュレーション中に発生するすべてのことが「fix」です。 これには、時間積分（座標と速度の更新）、力の制約条件または境界条件（SHAKEまたは壁）、診断（拡散係数の計算） が含まれます。 新しいスタイルを作成して、LIGGGHTS（R）-PUBLICに新しいオプションを追加することができます。

Fix_setforce.cppは、 atomに所定の値を設定する簡単な例です。 LIGGGHTS（R）-PUBLICには既に数十種類のfixオプションがあります。 実装するものに似たテンプレートとして1つを選択します。

ここでは、新しい派生クラスで定義できる メソッドについて簡単に説明します。 詳細については、fix.hを参照してください。

In LIGGGHTS(R)-PUBLIC, a “fix” is any operation that is computed during timestepping that alters some property of the system. Essentially everything that happens during a simulation besides force computation, neighbor list construction, and output, is a “fix”. This includes time integration (update of coordinates and velocities), force constraints or boundary conditions (SHAKE or walls), and diagnostics (compute a diffusion coefficient). New styles can be created to add new options to LIGGGHTS(R)-PUBLIC.

Fix_setforce.cpp is a simple example of setting forces on atoms to prescribed values. There are dozens of fix options already in LIGGGHTS(R)-PUBLIC; choose one as a template that is similar to what you want to implement.

Here is a brief description of methods you can define in your new derived class. See fix.h for details.

典型的には、これらのメソッドのほんの一 部が特定のfixに対して定義されています。 setmaskは、タイムステップ中にfixがいつ呼び出されるかを決定するため、必須です。時間積分（nve、nvt、npt）を実行するfixでは、 initial_integrate（）およびfinal_integrate（）を実装して速度ベルレの更新を実行し ます。強制力はpost_force（）を実装するfixです。

診断を実行するfixは、通常、end_of_step（）を実装します。 end_of_step fixの場合、fix引数の1つは、fixを呼び出すタイミングを決定するために使用される変数 "nevery"でなければならず、fixのコンストラクターでこの変数を設定する必要があります。これは、慣例により、（ID、グループID、スタイルの後に）fixが 定義する最初の引数です。

fixがtimestepからtimestepまで持続する各atomの情報を格納する必要がある場合、 grow_arrays、copy_arrays、pack_exchange、およびunpack_exchange メソッドを実装することによって、atomがメモリを管理し、atomがプロセッサからプロセッサに移動する際に情報を 移行 できます。同様に、pack_restartおよびunpack_restartメソッドを実装して、リスタートファイル内 のfixに関する情報を格納することもできます。 rRESPAで積分器または力の制約のfixを有効にしたい場合（run_styleコマンドを参照）、initial_integrate、 post_force_integrate、およびfinal_integrate_respaメソッドを実装できま す。thermoメソッドは、fixに熱力学的出力として、量を出力、および/またはシステムのポテンシャルエネルギー に合計するため に、値を提供することを可能にする。

Typically, only a small fraction of these methods are defined for a particular fix. Setmask is mandatory, as it determines when the fix will be invoked during the timestep. Fixes that perform time integration (nve, nvt, npt) implement initial_integrate() and final_integrate() to perform velocity Verlet updates. Fixes that constrain forces implement post_force().

Fixes that perform diagnostics typically implement end_of_step(). For an end_of_step fix, one of your fix arguments must be the variable “nevery” which is used to determine when to call the fix and you must set this variable in the constructor of your fix. By convention, this is the first argument the fix defines (after the ID, group-ID, style).

If the fix needs to store information for each atom that persists from timestep to timestep, it can manage that memory and migrate the info with the atoms as they move from processors to processor by implementing the grow_arrays, copy_arrays, pack_exchange, and unpack_exchange methods. Similarly, the pack_restart and unpack_restart methods can be implemented to store information about the fix in restart files. If you wish an integrator or force constraint fix to work with rRESPA (see the run_style command), the initial_integrate, post_force_integrate, and final_integrate_respa methods can be implemented. The thermo method enables a fix to contribute values to thermodynamic output, as printed quantities and/or to be summed to the potential energy of the system.

9.6. Input script commands¶

LIGGGHTS（R）-PUBLIC入 力スクリプトに新しいコマンドを追加するには、「command」メソッドを持つ新しいクラスを追加します。 たとえば、create_atoms、read_data、velocity、およびrunコマンドは、すべてこの方法で実装されます。 そのようなコマンドがLIGGGHTS（R）-PUBLIC入力スクリプトで見つかると、LIGGGHTS（R）- PUBLICは対応する名前のクラスを作成し、そのクラスの "command"メソッドを呼び出し、入力スクリプトから引数を渡します。 commandメソッドは、LIGGGHTS（R）-PUBLICデータ構造上の任意の操作を実行できます。

新しいクラスで定義する必要がある単一のメソッドは次のとおりです。

New commands can be added to LIGGGHTS(R)-PUBLIC input scripts by adding new classes that have a “command” method. For example, the create_atoms, read_data, velocity, and run commands are all implemented in this fashion. When such a command is encountered in the LIGGGHTS(R)-PUBLIC input script, LIGGGHTS(R)-PUBLIC simply creates a class with the corresponding name, invokes the “command” method of the class, and passes it the arguments from the input script. The command method can perform whatever operations it wishes on LIGGGHTS(R)-PUBLIC data structures.

The single method your new class must define is as follows:

もちろん、新しいクラスは、必要に応じて 他のメソッドや変数を定義することができます。

Of course, the new class can define other methods and variables as needed.

9.7. Pairwise potentials¶

ペア相互作用を計算するクラスは、 ペアクラスから派生します。 LIGGGHTS（R）-PUBLICにおいて、ペア計算は、粒子が静的結合トポロジーなしで相互作用するEAMまたはTersoffなどの多体ポテンシャ ルを含む。 LIGGGHTS（R）-PUBLICに新しいペアポテンシャルを追加するための新しいスタイルを作成することができます。

pair.hのクラスメソッドについて簡 単に説明します：

Classes that compute pairwise interactions are derived from the Pair class. In LIGGGHTS(R)-PUBLIC, pairwise calculation include manybody potentials such as EAM or Tersoff where particles interact without a static bond topology. New styles can be created to add new pair potentials to LIGGGHTS(R)-PUBLIC.

Here is a brief description of the class methods in pair.h:

内/中/外ルーチンはオプションです。

The inner/middle/outer routines are optional.

9.8. Region styles¶

Geomeric regionを定義するクラスは、 Regionクラスから派生します。 領域は、LIGGGHTS（R）-PUBLICの他の場所で使用され、atomをグループ化し、atomを削除して空白を作成したり、指定された領域にatomを挿入した りする ために使用されます。LIGGGHTS（R）-PUBLICに新しい領域形状を追加するための新しいスタイルを作成でき ます。

Region_sphere.cppは球面領域の例です。

ここでは、新しい派生クラスで定義するメソッドについて簡単に説明します。 詳細については、region.hを参照してください。

Classes that define geometric regions are derived from the Region class. Regions are used elsewhere in LIGGGHTS(R)-PUBLIC to group atoms, delete atoms to create a void, insert atoms in a specified region, etc. New styles can be created to add new region shapes to LIGGGHTS(R)-PUBLIC.

Region_sphere.cpp is an example of a spherical region.

Here is a brief description of methods you define in your new derived class. See region.h for details.

9.9. Thermodynamic output options¶

熱力学的情報を計算して画面や ログファイルに出力するクラスが1つあります。 thermo.cppファイルを参照してください。

thermo.cppには、 "one"と "multi"という2つのスタイルが定義されています。また、熱力学的情報が出力されたときに、出力する量のキーワードを明示的にリストすることができる柔軟な 「custom」スタイルもあります。定義された量のリストについては、thermo_styleコマンドを参照してく ださい。

thermoスタイル（one、multiなど）はキーワードのリストです。したがって、新しいスタイルを追加するに は、キーワードの 新しいリストを定義するだけで済みます。 thermo.cppの "thermo style"を参照して "customize"という単語を検索して、コードを追加する必要がある2つの場所を確認します。

thermo.cppに新しいキーワードを追加して、出力用の新しい量を計算することもできます。 thermo.cppの "keyword"への参照で "customize"という単語を検索し、コードを追加する必要があるいくつかの場所を確認します。

thermo_style customコマンドでは、fix、compute、および変数によって計算された量の熱出力が既に許可されて います。したがって、thermoコマンドに新しいキーワードを追加するよりも、それらの構文のいずれかを使って望むも のを計算するほうが簡単です。

There is one class that computes and prints thermodynamic information to the screen and log file; see the file thermo.cpp.

There are two styles defined in thermo.cpp: “one” and “multi”. There is also a flexible “custom” style which allows the user to explicitly list keywords for quantities to print when thermodynamic info is output. See the thermo_style command for a list of defined quantities.

The thermo styles (one, multi, etc) are simply lists of keywords. Adding a new style thus only requires defining a new list of keywords. Search for the word “customize” with references to “thermo style” in thermo.cpp to see the two locations where code will need to be added.

New keywords can also be added to thermo.cpp to compute new quantities for output. Search for the word “customize” with references to “keyword” in thermo.cpp to see the several locations where code will need to be added.

Note that the thermo_style custom command already allows for thermo output of quantities calculated by fixes, computes, and variables. Thus, it may be simpler to compute what you wish via one of those constructs, than by adding a new keyword to the thermo command.

9.10. Variable options¶

変数情報を計算して LIGGGHTS（R）-PUBLICに格納するクラスが1つあります。 variable.cppファイルを参照してください。変数に関連付けられた値は、print、fix print、またはthermo_style customコマンドを使用して、画面に定期的に出力できます。equal-style variableは、以下の型の引数を含む複雑な方程式を計算できます。

thermo keywords = ke, vol, atoms, ... other variables = v_a, v_myvar, ... math functions = div(x,y), mult(x,y), add(x,y), ... group functions = mass(group), xcm(group,x), ... atom values = x**123**, y**3**, vx**34**, ... compute values = c_mytemp**0**, c_thermo_press**3**, ...

このページでは、 thermo_style customコマンド（変数でアクセス可能）のキーワードを追加しました。

1つまたは2つの引数の新しい数学関数を追加するには、Variable :: evaulate（）メソッドの1つのセクションを編集します。 「customize」という単語を検索して、適切な場所を探します。

新しいグループ関数を追加するには、Variable :: evaulate（）メソッドの1つのセクションを編集します。 「customize」という単語を検索して、適切な場所を探します。 Groupクラスにも新しいメソッドを追加する必要があります（group.cppファイルを参照）。

新しいatomベースのベクトルにアクセスするには、Variable :: evaulate（）メソッドの1つのセクションを編集します。 「customize」という単語を検索して、適切な場所を探します。

このページでは、計算された値に変数でアクセスできる新しいcomputeスタイルの追加について説明しました。

There is one class that computes and stores variable information in LIGGGHTS(R)-PUBLIC; see the file variable.cpp. The value associated with a variable can be periodically printed to the screen via the print, fix print, or thermo_style custom commands. Variables of style “equal” can compute complex equations that involve the following types of arguments:

thermo keywords = ke, vol, atoms, ... other variables = v_a, v_myvar, ... math functions = div(x,y), mult(x,y), add(x,y), ... group functions = mass(group), xcm(group,x), ... atom values = x**123**, y**3**, vx**34**, ... compute values = c_mytemp**0**, c_thermo_press**3**, ...

Adding keywords for the thermo_style custom command (which can then be accessed by variables) was discussed here on this page.

Adding a new math function of one or two arguments can be done by editing one section of the Variable::evaulate() method. Search for the word “customize” to find the appropriate location.

Adding a new group function can be done by editing one section of the Variable::evaulate() method. Search for the word “customize” to find the appropriate location. You may need to add a new method to the Group class as well (see the group.cpp file).

Accessing a new atom-based vector can be done by editing one section of the Variable::evaulate() method. Search for the word “customize” to find the appropriate location.

Adding new compute styles (whose calculated values can then be accessed by variables) was discussed here on this page.

9.11. Submitting new features for inclusion in LIGGGHTS(R)-PUBLIC¶

我々は、LIGGGHTS（R）- PUBLICに追加した新機能を、特に他のユーザーにとって興味深いと思う場合に提出す ることをお勧めします。それらが広く有用であれば、それらをLIGGGHTS（R）-PUBLICのコアファイルとして追加 することができます。

このドキュメントページのこれまでのセクションでは、LIGGGHTS（R）-PUBLICにさまざまな種類の新機能を 追加 する方法について説明しました。パッケージは、LIGGGHTS（R）-PUBLIC入力スクリプト内で新しい "スタイル"として呼び出される、1つ以上の新しいクラスファイルのコレクションです。正しく設計されていれば、これら の追加は通常、LIGGGHTS（R）- PUBLICの主要なコアを変更する必要はありません。それらは単なるアドオンファイルです。

ここでは、検討のためにユーザーパッケージ または単一ファイルを提出するために必要なことがあります。これらの手順を実行すると、あなたと私たちの両方の時間が節 約されます。例については、既存のパッケージファイルを参照してください。

• 提供するすべてのソースファイル は、LIGGGHTS（R）- PUBLICの最新バージョンでコンパイルする必要があります。
• ファイルをメインの LIGGGHTS（R）-PUBLICまたはその 標準パッケージに追加したい場合は、他のLIGGGHTS（R）-PUBLICソースファイルと互換性のあるスタイルで 記述する必要があります。これは、開発者がそれを理解し、うまく保守できるようにするためです。これは基本的に、 コード がデータ構造にアクセスし、その操作を実行し、エラーおよび警告メッセージのエラークラスの使用を含む、他の LIGGGHTS（R）-PUBLICソースファイルと同様にフォーマットされていることを意味します。
• あなたの新しいソースファイルは、 他のLIGGGHTS（R）- PUBLICソースファイルのように、LIGGGHTS（R）-PUBLICの著作権、GPLの通知、およびあなたの名前が 一番上にある必要があります。彼らは、LIGGGHTS（R）-PUBLIC名前空間内にあるクラスを作成する必要 があ ります。つまり、他のLIGGGHTS（R）-PUBLICファイルと同じ書式の書式と構文である必要はありませんが、 それはうまくいくでしょう。
• 最後に、LIGGGHTS（R）- PUBLICに追加する新しいコマ ンドまたはスタイルごとにドキュメントファイルを送信する必要があります。これは、単一ファイル機能の1つのファイルに なります。パッケージの場合、複数のファイルである可能性があります。これらはHTMLに変換する単純なテキスト ファイ ルです。同様のコマンドとスタイルのためには、lammps / docディレクトリ内の他の* .txtファイルと同じ形式でなければなりません。変換を行うために使用するtxt2htmlツールは、このサイトからダウンロードできるので、HTML変換を自分で実行 してドキュメントページを校正することができます。
  

ドキュメントとREADMEファイルを作成すると、ユーザーが新しい機能を試してみる可能性が高くなります。

We encourage users to submit new features that they add to LIGGGHTS(R)-PUBLIC, especially if you think the features will be of interest to other users. If they are broadly useful we may add them as core files to LIGGGHTS(R)-PUBLIC.

The previous sections of this doc page describe how to add new features of various kinds to LIGGGHTS(R)-PUBLIC. Packages are simply collections of one or more new class files which are invoked as a new “style” within a LIGGGHTS(R)-PUBLIC input script. If designed correctly, these additions typically do not require changes to the main core of LIGGGHTS(R)-PUBLIC; they are simply add-on files.

Here is what you need to do to submit a user package or single file for our consideration. Following these steps will save time for both you and us. See existing package files for examples.

• All source files you provide must compile with the most current version of LIGGGHTS(R)-PUBLIC.
• If you want your file(s) to be added to main LIGGGHTS(R)-PUBLIC or one of its standard packages, then it needs to be written in a style compatible with other LIGGGHTS(R)-PUBLIC source files. This is so the developers can understand it and hopefully maintain it. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LIGGGHTS(R)-PUBLIC source files, including the use of the error class for error and warning messages.
• Your new source files need to have the LIGGGHTS(R)-PUBLIC copyright, GPL notice, and your name at the top, like other LIGGGHTS(R)-PUBLIC source files. They need to create a class that is inside the LIGGGHTS(R)-PUBLIC namespace. I.e. they do not need to be in the same stylistic format and syntax as other LIGGGHTS(R)-PUBLIC files, though that would be nice.
• Finally, you must also send a documentation file for each new command or style you are adding to LIGGGHTS(R)-PUBLIC. This will be one file for a single-file feature. For a package, it might be several files. These are simple text files which we will convert to HTML. They must be in the same format as other *.txt files in the lammps/doc directory for similar commands and styles. The txt2html tool we use to do the conversion can be downloaded from this site, so you can perform the HTML conversion yourself to proofread your doc page.

Note that the more clear and self-explanatory you make your doc and README files, the more likely it is that users will try out your new feature.

(Foo) Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).