Merge branch 'brucefan1983:master' into mini

Author: mushroomfire

doc/gpumd/input_files/basis_in.rst

@@ -12,6 +12,5 @@ To run one a simulation using the ``gpumd`` executable, one has to prepare at le
 
    run_in
    model_xyz
-   basis_in
    kpoints_in
    eigenvector_in

doc/gpumd/input_files/index.rst

@@ -13,15 +13,38 @@ File format
 The format of this file must be as follows:
 
 .. code::
+# high symmetry points
+k_points_x(0) k_points_y(0) k_points_z(0) name(0)
+k_points_x(1) k_points_y(1) k_points_z(1) name(1)
+...
 
- N_kpoints
- kx(0) ky(0) kz(0)
- kx(1) ky(1) kz(1)
- ...
- kx(N_kpoints-1) ky(N_kpoints-1) kz(N_kpoints-1)
+
+Example
+-------
+
+For example, the command::
+
+.. code::
+
+ 0 0 0 G
+ 0.5 0 0 M
+ 0.333 0.333 0 K
+ 0 0 0 G
  
-Here,
-* ``N_kpoints`` is the number of k points you want to consider.
-* The remaining lines give the k vectors (in units of 1/Å) you want to consider.
-* The user has to make sure that the k vectors are defined in the reciprocal space with respect to the unit cell chosen.
+or
+
+.. code::
 
+ 0 0 0 G
+ 0.5 0 0.5 X
+ 0.625 0.25 0.625 U
+          #Represents a breakpoint, marking the start of the second path.
+ 0.375 0.375 0.75 K
+ 0 0 0 G
+ 0.5 0.5 0.5 L
+ 0.5 0.25 0.75 W
+ 0.5 0 0.5 X
+
+Here,
+* The first three columns represent the coordinates of high symmetry points. The last column corresponds to names.
+* A blank line indicates a breakpoint or the initiation of a second path.

doc/gpumd/input_files/kpoints_in.rst

@@ -5,55 +5,80 @@
 :attr:`add_spring`
 ==================
 
-This keyword is used to add a spring between a ghost atom and the centroid of atoms in a selected group.
+This keyword adds spring interactions to selected atom groups at each step of a run.
+
+It supports three modes: :attr:`ghost_com`, :attr:`ghost_atom`, and :attr:`com_com`, which add spring forces between a ghost atom and the center of mass (COM) of a group, between ghost atoms and their corresponding atoms in a group, and between the COMs of two groups, respectively. The ghost atom(s) can be static or move at a constant velocity. Each mode supports two spring types: :attr:`couple` (a single radial spring) and :attr:`decouple` (three independent springs along the x, y, and z directions).
 
 Syntax
 ------
 
-This keyword is used in one of the following two ways::
+The complete syntax for the six combinations is::
 
-  add_spring ghost_com <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> couple <k_couple> <R0> <offset_x> <offset_y> <offset_z>  # usage 1
-  add_spring ghost_com <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> decouple <k_decouple_x> <k_decouple_y> <k_decouple_z> <offset_x> <offset_y> <offset_z>  # usage 2
+  add_spring ghost_com <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> couple <k_couple> <R0> <offset_x> <offset_y> <offset_z>
+  add_spring ghost_com <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> decouple <k_decouple_x> <k_decouple_y> <k_decouple_z> <offset_x> <offset_y> <offset_z>
+  add_spring ghost_atom <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> couple <k_couple> <R0> <offset_x> <offset_y> <offset_z>
+  add_spring ghost_atom <group_method> <group_id> <ghost_vx> <ghost_vy> <ghost_vz> decouple <k_decouple_x> <k_decouple_y> <k_decouple_z> <offset_x> <offset_y> <offset_z>
+  add_spring com_com <group_method> <group_id_1> <group_id_2> couple <k_couple> <R0>
+  add_spring com_com <group_method> <group_id_1> <group_id_2> decouple <k_decouple_x> <k_decouple_y> <k_decouple_z>
 
-The function of the coupled spring potential is given by the equation:
+The coupled spring potential is:
 
 .. math::
 
    U_{\mathrm{couple}} = \frac{1}{2} k_{\mathrm{couple}} (R - R_0)^2
-   
-where :math:`R` is the distance between the ghost atom and the centroid of the selected group. The function of the decoupled spring potential is given by the equation:
+
+where :math:`R` is the distance between the two points connected by the spring.
+
+The decoupled spring potential is:
 
 .. math::
 
-   U_{\mathrm{decouple}} = \frac{1}{2} k_{\mathrm{decouple},x} (x - x_{\mathrm{ghost}})^2 + \frac{1}{2} k_{\mathrm{decouple},y} (y - y_{\mathrm{ghost}})^2 + \frac{1}{2} k_{\mathrm{decouple},z} (z - z_{\mathrm{ghost}})^2
-   
-where :math:`(x_{\mathrm{ghost}}, y_{\mathrm{ghost}}, z_{\mathrm{ghost}})` is the position of the ghost atom and :math:`(x, y, z)` is the position of the centroid of the selected group.
+   U_{\mathrm{decouple}} = \frac{1}{2} k_{\mathrm{decouple},x} (x_2 - x_1)^2 + \frac{1}{2} k_{\mathrm{decouple},y} (y_2 - y_1)^2 + \frac{1}{2} k_{\mathrm{decouple},z} (z_2 - z_1)^2
 
-* Force is added to atoms in group :attr:`group_id` of group method :attr:`group_method`.
-* In the first usage, a spring is coupled to the ghost atom with spring constant :attr:`k_couple` and equilibrium distance :attr:`R0`.
-* In the second usage, a spring is decoupled from the ghost atom with spring constants :attr:`k_decouple_x`, :attr:`k_decouple_y`, and :attr:`k_decouple_z` in the x, y, and z directions, respectively.
-* The ghost atom starts at the position of the centroid of the selected group plus the offset vector (:attr:`offset_x`, :attr:`offset_y`, :attr:`offset_z`), and moves with velocity (:attr:`ghost_vx`, :attr:`ghost_vy`, :attr:`ghost_vz`).
+where :math:`(x_1, y_1, z_1)` and :math:`(x_2, y_2, z_2)` are the Cartesian coordinates of the two points connected by the spring.
+
+* In :attr:`ghost_com` mode, force is added to atoms in group :attr:`group_id` of group method :attr:`group_method` with mass-weighted distribution. The ghost is initially placed at the COM + (:attr:`offset_x`, :attr:`offset_y`, :attr:`offset_z`) and is displaced by (:attr:`ghost_vx`, :attr:`ghost_vy`, :attr:`ghost_vz`) at each step.
+* In :attr:`ghost_atom` mode, each atom in group :attr:`group_id` is attached to its own ghost anchor. The anchor is initially placed at the atom position + (:attr:`offset_x`, :attr:`offset_y`, :attr:`offset_z`) and is displaced by (:attr:`ghost_vx`, :attr:`ghost_vy`, :attr:`ghost_vz`) at each step. The input spring constant(s) (:attr:`k_couple` or :attr:`k_decouple_x`, :attr:`k_decouple_y`, :attr:`k_decouple_z`) represent the total stiffness of the entire group and are divided internally by the number of atoms in the group. Thus, each atom experiences a spring with an effective stiffness of :attr:`k / N_atoms`.
+* In :attr:`com_com` mode, a spring interaction is applied between the COM of group :attr:`group_id_1` and the COM of group :attr:`group_id_2` under the same :attr:`group_method`. Equal and opposite forces are applied to the two groups with mass-weighted distribution within each group.
+* In :attr:`couple` mode, :attr:`k_couple` must be positive and :attr:`R0` must be non-negative.
+* In :attr:`decouple` mode, :attr:`k_decouple_x`, :attr:`k_decouple_y`, and :attr:`k_decouple_z` must be non-negative.
+* In :attr:`com_com` mode, :attr:`group_id_1` and :attr:`group_id_2` must be different.
 * Force is in units of eV/Å, distance is in units of Å, velocity is in units of Å/step, and spring constant is in units of eV/Ų.
-* Spring forces are written to `spring_force_*.out`, where the asterisk is replaced by a zero-based index that increments with each invocation of the command. The meaning of each column in the file is::
+* Spring forces are written to the file :attr:`spring_force_*.out`, where the asterisk is replaced by a zero-based index that increments with each invocation of the command. The meaning of each column in the file is::
+
+   # step  mode  Fx  Fy  Fz  Ftotal  energy
+
+where :attr:`mode` is an integer flag: 0 = ghost_com, 1 = ghost_atom, 2 = com_com. In :attr:`com_com` mode, the reported :attr:`Fx`, :attr:`Fy`, and :attr:`Fz` correspond to the net spring force applied to :attr:`group_id_1`.
+
+Example 1 (ghost_com + couple)
+------------------------------
+
+Add a coupled spring with spring constant 10 eV/Ų and equilibrium distance 0 Šbetween a static ghost atom and the COM of atoms in group 2 defined by group method 0. The ghost atom is initially located at the COM::
+
+   add_spring ghost_com 0 2 0 0 0 couple 10 0 0 0 0
+
+Example 2 (ghost_com + decouple)
+--------------------------------
 
-  # step  call  mode  Fx  Fy  Fz  energy  spring_force
+Add a decoupled spring with spring constants 10 eV/Ų in the x direction and 0 eV/Ų in the y and z directions between a ghost atom moving at velocity (0.00005, 0, 0) Å/step and the COM of atoms in group 2 defined by group method 0. The ghost atom is initially located at the COM::
 
+   add_spring ghost_com 0 2 0.00005 0 0 decouple 10 0 0 0 0 0
 
-Example 1
----------
+Example 3 (ghost_atom + couple)
+-------------------------------
 
-Add a coupled spring with spring constant 10 eV/Ų and equilibrium distance 0 Šbetween a static ghost atom and the centroid of atoms in group 2 of group method 0. The ghost atom is initially in the same position as the centroid::
+Add a coupled spring between each atom in group 2 defined by group method 0 and its corresponding moving ghost anchor. Each anchor is initially placed at the corresponding atom position and moves at velocity (0.00005, 0, 0) Å/step::
 
-   add_spring    ghost_com 0 2 0 0 0 couple 10 0 0 0 0
+   add_spring ghost_atom 0 2 0.00005 0 0 couple 10 0 0 0 0
 
-Example 2
----------
+Example 4 (com_com + decouple)
+------------------------------
 
-Add a decoupled spring with spring constants 10 eV/Ų in the x direction and 0 eV/Ų in the y and z directions between a ghost atom moving with velocity (0.00005, 0, 0) Å/step and the centroid of atoms in group 2 of group method 0. The ghost atom is initially in the same position as the centroid::
+Add a decoupled Cartesian spring between the COM of group 1 and the COM of group 2 under the same group method 0::
 
-   add_spring    ghost_com 0 2 0.00005 0 0 decouple 10 0 0 0 0 0
+   add_spring com_com 0 1 2 decouple 10 0 0
 
 Note
 ----
 
-This keyword can be used multiple times during a run.
+This keyword can be used multiple times during a run.

doc/gpumd/input_parameters/add_spring.rst

@@ -17,19 +17,18 @@ To use this keyword, please make sure the following files have been preprared in
 
    * - Input filename
      - Brief description
-   * - ``basis.in``
-     - Define the mapping from the atom label to the basis label
    * - ``kpoints.in``
-     - Specify the :math:`\boldsymbol{k}`-points
+     - Specify the :math:`\boldsymbol{k}`-points along the high-symmetry paths
+
+
+To use this keyword, :attr:`replicate` keywords must write head in the :attr:`run.in` file.
 
 Syntax
 ------
 
 This keyword is used as follows::
 
-  compute_phonon <cutoff> <displacement>
-
-:attr:`cutoff` is the cutoff distance (in units of Å) for calculating the force constants.
+  compute_phonon <displacement>
 
 :attr:`displacement` is the displacement (in units of Å) for calculating the force constants using the finite-displacement method.
 
@@ -38,13 +37,14 @@ Example
 
 For example, the command::
 
-    compute_phonon 5.0 0.01
+    compute_phonon 0.01
 
-means that one wants to compute the phonon dispersion using a cutoff distance of 5 Å and a displacement of 0.01 Å.
+means that one wants to compute the phonon dispersion using a displacement of 0.01 Å.
 
 Caveats
 -------
 
+
 This keyword should occur after all the :attr:`potential` keywords.
 
 For two-body potentials, the cutoff distance for force constants can be the same as that for force evaluations.

doc/gpumd/input_parameters/compute_phonon.rst

@@ -11,7 +11,7 @@ This file contains the dynamical matrices :math:`D(\boldsymbol{k})` at different
 File format
 -----------
 
-The file contains :attr:`3 * N_basis * N_kpoints` rows and :attr:`6 * N_basis` columns, where :attr:`N_basis` is the number of basis atoms in the unit cell defined in the :ref:`basis.in input file <basis_in>` and :attr:`N_kpoints` is the number of :math:`\boldsymbol{k}`-points in the :ref:`kpoints.in input file <kpoints_in>`.
+The file contains :attr:`3 * N_basis * N_kpoints` rows and :attr:`6 * N_basis` columns, where :attr:`N_basis` is the number of basis atoms in the unit cell defined and :attr:`N_kpoints` is the number of :math:`\boldsymbol{k}`-points from :ref:`kpoints.in input file <kpoints_in>` created.
 
 Each consecutive :attr:`3 * N_basis` rows correspond to one :math:`\boldsymbol{k}`-point.
 For each :math:`\boldsymbol{k}`-point, the first :attr:`3*N_basis` columns correspond to the real part and the second :attr:`3*N_basis` columns correspond to the imaginary part.

doc/gpumd/output_files/D_out.rst

@@ -205,6 +205,16 @@ @article{CaoCaoZhu24
 doi = {10.1016/j.ijheatmasstransfer.2024.125359}
 }
 
+@article{CaoJuLiu26,
+title = {Temperature-stable thermal transport in graphene antidot lattices: {Phonon} scattering regulation},
+journal = {Chemical Physics Letters},
+pages = {142740},
+year = {2026},
+issn = {0009-2614},
+doi = {10.1016/j.cplett.2026.142740},
+author = {Bin Cao and Boqia Ju and Gang Liu and Ge Yao and Jiuyu Sun and Yongping Du}
+}
+
 @article{CaoLiuChen25,
 author = {Cao, Jian and Liu, Chang and Chen, Zian and Li, Haichao and Xu, Lina and Xiao, Hongping and Wang, Shun and He, Xiao and Fang, Guoyong},
 title = {Accelerated Discovery of Refractory High-Entropy Alloys via Interpretable Machine Learning},