Merge pull request #669 from brucefan1983/doc

doc for add_force and add_efield

doc/gpumd/input_files/model_xyz.rst

@@ -48,7 +48,8 @@ Essentially any keyword is allowed, but we only read the following ones:
 
  * ``species:S:1`` atom type (*Mandatory*)
  * ``pos:R:3`` position vector (*Mandatory*)
- * ``mass:R:1`` mass (*Optional*: default mass values will be used when this is missing) 
+ * ``mass:R:1`` mass (*Optional*: default mass values will be used when this is missing)
+ * ``charge:R:1`` charge (*Optional*: default charge is zero) 
  * ``vel:R:3`` velocity vector (*Optional*)
  * ``group:I:number_of_grouping_methods`` grouping methods (*Optional*)
 
@@ -63,6 +64,7 @@ Units
 -----
 
 The mass should be given in units of the unified atomic mass unit (amu). 
+The charge is in units of e (proton charge).
 The cell dimensions and atom coordinates should be given in units of Ångstrom. 
 Velocities need to be specified in units of Å/fs.
 

doc/gpumd/input_parameters/add_efield.rst

@@ -0,0 +1,40 @@
+.. _kw_add_efield:
+.. index::
+ single: add_efield (keyword in run.in)
+
+:attr:`add_efield`
+==================
+
+This keyword is used to add force due to electric field on atoms in a selected group at each step during a run. The force equals to the product of the electric field and the charge of the atom as specified in :attr:`model.xyz` via :attr:`charge:R:1`.
+
+Syntax
+------
+
+This keyword is used in one of the following two ways::
+
+ add_efield <group_method> <group_id> <Ex> <Ey> <Ez> # usage 1
+ add_efield <group_method> <group_id> <add_efield_file> # usage 2
+
+* Electric field is applied to atoms in group :attr:`group_id` of group method :attr:`group_method`.
+* In the first usage, the constant electric field with components :attr:`Ex`, :attr:`Ey`, and :attr:`Ez` is applied to each selected atom.
+* In the second usage, a series of electric fields specified in the file :attr:`add_efield_file` will be periodically applied to each selected atom.
+* Electric field is in units of V/Å.
+
+Example 1
+---------
+
+Add a constant electric field of 0.1 V/Å in the x direction on atoms in group 1 of group method 2::
+
+ add_efield 2 1 0.1 0 0
+
+Example 2
+---------
+
+Add electric field on atoms in group 2 of group method 0, where the file :attr:`add_efield.txt` contains a number of rows of 3 values specifying a sequence of electric field vectors to be periodically applied during the run::
+
+ add_efield 0 2 add_efield.txt
+
+Note
+----
+
+This keyword can be used multiple times during a run.

doc/gpumd/input_parameters/add_force.rst

@@ -0,0 +1,40 @@
+.. _kw_add_force:
+.. index::
+ single: add_force (keyword in run.in)
+
+:attr:`add_force`
+=================
+
+This keyword is used to add force on atoms in a selected group at each step during a run.
+
+Syntax
+------
+
+This keyword is used in one of the following two ways::
+
+ add_force <group_method> <group_id> <Fx> <Fy> <Fz> # usage 1
+ add_force <group_method> <group_id> <add_force_file> # usage 2
+
+* Force is added to atoms in group :attr:`group_id` of group method :attr:`group_method`.
+* In the first usage, the constant force with components :attr:`Fx`, :attr:`Fy`, and :attr:`Fz` is added on each selected atom.
+* In the second usage, a series of forces specified in the file :attr:`add_force_file` will be periodically added on each selected atom.
+* Force is in units of eV/Å.
+
+Example 1
+---------
+
+Add a constant force of 0.1 eV/Å in the x direction on atoms in group 1 of group method 2::
+
+ add_force 2 1 0.1 0 0
+
+Example 2
+---------
+
+Add force on atoms in group 2 of group method 0, where the file :attr:`add_force.txt` contains a number of rows of 3 values specifying a sequence of force vectors to be periodically applied during the run::
+
+ add_force 0 2 add_force.txt
+
+Note
+----
+
+This keyword can be used multiple times during a run.

doc/gpumd/input_parameters/index.rst

@@ -35,6 +35,8 @@ Below you can find a listing of keywords for the ``run.in`` input file.
  plumed
  mc
  electron_stop
+ add_force
+ add_efield
 
 .. toctree::
  :maxdepth: 1