git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@12435 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/Section_accelerate.html

@@ -11,6 +11,8 @@ Section</A>
 
 <HR>
 
+<P>NOTE: USER-CUDA: no newton setting needed?
+</P>
 <H3>5. Accelerating LAMMPS performance 
 </H3>
 <P>This section describes various methods for improving LAMMPS
@@ -44,12 +46,12 @@ on different hardware platforms.
 understand how it currently performs and where the bottlenecks are.
 </P>
 <P>The best way to do this is run the your system (actual number of
-atoms) for a modest number of timesteps (say 100, or a few 100 at
+atoms) for a modest number of timesteps (say 100 steps) on several
-most) on several different processor counts, including a single
+different processor counts, including a single processor if possible.
-processor if possible.  Do this for an equilibrium version of your
+Do this for an equilibrium version of your system, so that the
-system, so that the 100-step timings are representative of a much
+100-step timings are representative of a much longer run.  There is
-longer run.  There is typically no need to run for 1000s or timesteps
+typically no need to run for 1000s of timesteps to get accurate
-to get accurate timings; you can simply extrapolate from short runs.
+timings; you can simply extrapolate from short runs.
 </P>
 <P>For the set of runs, look at the timing data printed to the screen and
 log file at the end of each LAMMPS run.  <A HREF = "Section_start.html#start_8">This
@@ -244,6 +246,13 @@ Technologies).  It contains a handful of pair styles whose compute()
 methods were rewritten in C++ templated form to reduce the overhead
 due to if tests and other conditional code.
 </P>
+<P>Here is a quick overview of how to use the OPT package:
+</P>
+<UL><LI>include the OPT package and build LAMMPS
+<LI>use OPT pair styles in your input script 
+</UL>
+<P>Details follow.
+</P>
 <P><B>Required hardware/software:</B>
 </P>
 <P>None.
@@ -255,8 +264,8 @@ due to if tests and other conditional code.
 <PRE>make yes-opt
 make machine 
 </PRE>
-<P>No additional compile/link flags are needed in your lo-level
+<P>No additional compile/link flags are needed in your machine
-src/MAKE/Makefile.machine.
+Makefile in src/MAKE.
 </P>
 <P><B>Running with the OPT package:</B>
 </P>
@@ -296,6 +305,16 @@ nearly all bonded styles (bond, angle, dihedral, improper), several
 Kspace styles, and a few fix styles.  The package currently
 uses the OpenMP interface for multi-threading.
 </P>
+<P>Here is a quick overview of how to use the USER-OMP package:
+</P>
+<UL><LI>specify the -fopenmp flag for compiling and linking in your machine Makefile
+<LI>include the USER-OMP package and build LAMMPS
+<LI>specify how many threads per MPI task to run with via an environment variable or the package omp command
+<LI>enable the USER-OMP package via the "-sf omp" command-line switch, or the package omp commmand
+<LI>use USER-OMP styles in your input script 
+</UL>
+<P>Details follow.
+</P>
 <P><B>Required hardware/software:</B>
 </P>
 <P>Your compiler must support the OpenMP interface.  You should have one
@@ -362,8 +381,7 @@ style in your input script:
 <PRE>pair_style lj/cut/omp 2.5
 fix nve/omp 
 </PRE>
-<P><
+<P>Or you can run with the "-sf omp" <A HREF = "Section_start.html#start_7">command-line
-Or you can run with the "-sf omp" <A HREF = "Section_start.html#start_7">command-line
 switch</A>, which will automatically append
 "omp" to styles that support it.
 </P>
@@ -393,7 +411,7 @@ benchmark runs for a specific simulation running on a specific
 machine, paying attention to guidelines discussed in the next
 sub-section.
 </P>
-<P>A description of the multi-threading strategy used in the UESR-OMP
+<P>A description of the multi-threading strategy used in the USER-OMP
 package and some performance examples are <A HREF = "http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1">presented
 here</A>
 </P>
@@ -502,6 +520,19 @@ NVIDIA support as well as more general OpenCL support, so that the
 same functionality can eventually be supported on a variety of GPU
 hardware. 
 </UL>
+<P>Here is a quick overview of how to use the GPU package:
+</P>
+<UL><LI>build the library in lib/gpu for your GPU hardware (CUDA_ARCH) with desired precision (CUDA_PREC)
+<LI>include the GPU package and build LAMMPS
+<LI>decide how many MPI tasks per GPU to run with, i.e. set MPI tasks/node via mpirun
+<LI>specify how many GPUs per node to use (default = 1) via the package gpu command
+<LI>enable the GPU package via the "-sf gpu" command-line switch, or the package gpu commmand
+<LI>use the newton command to turn off Newton's law for pairwise interactions
+<LI>use the package gpu command to enable neighbor list building on the GPU if desired
+<LI>use GPU pair styles and kspace styles in your input script 
+</UL>
+<P>Details follow.
+</P>
 <P><B>Required hardware/software:</B>
 </P>
 <P>To use this package, you currently need to have an NVIDIA GPU and
@@ -714,10 +745,20 @@ transparently.
 <LI>The package only supports use of a single MPI task, running on a
 single CPU (core), assigned to each GPU. 
 </UL>
+<P>Here is a quick overview of how to use the USER-CUDA package:
+</P>
+<UL><LI>build the library in lib/cuda for your GPU hardware (arch with desired precision (precision)
+<LI>include the USER-CUDA package and build LAMMPS
+<LI>use the mpirun command to specify 1 MPI task per GPU (on each node)
+<LI>specify how many GPUs per node to use (default = 1) via the package cuda command
+<LI>enable the USER-CUDA package via the "-c on" command-line switch
+<LI>use USER-CUDA styles in your input script 
+</UL>
+<P>Details follow.
+</P>
 <P><B>Required hardware/software:</B>
 </P>
-<P>To use this package, you need to have an NVIDIA GPU and
+<P>To use this package, you need to have one or more NVIDIA GPUs and install the NVIDIA Cuda software on your system:
-install the NVIDIA Cuda software on your system:
 </P>
 <P>Your NVIDIA GPU needs to support Compute Capability 1.3. This list may
 help you to find out the Compute Capability of your card:
@@ -1260,6 +1301,24 @@ suffix to "omp" so that styles from the USER-OMP package will be used
 if available, after first testing if a style from the USER-INTEL
 package is available.
 </P>
+<P>Here is a quick overview of how to use the USER-INTEL package
+for CPU acceleration:
+</P>
+<UL><LI>specify these CCFLAGS in your machine Makefile: -fopenmp, -DLAMMPS_MEMALIGN=64, and -restrict, -xHost
+<LI>specify -fopenmp with LINKFLAGS in your machine Makefile
+<LI>include the USER-INTEL package and (optionally) USER-OMP package and build LAMMP
+<LI>if also using the USER-OMP package, specify how many threads per MPI task to run with via an environment variable or the package omp command
+<LI>use USER-INTEL styles in your input script 
+</UL>
+<P>Running with the USER-INTEL package to offload to the Intel(R) Xeon Phi(TM)
+is the same except for these additional steps:
+</P>
+<UL><LI>add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in your Machine makefile
+<LI>add the flag -offload to the LINKFLAGS in your Machine makefile
+<LI>the package intel command can be used to adjust threads per coprocessor 
+</UL>
+<P>Details follow.
+</P>
 <P><B>Required hardware/software:</B>
 </P>
 <P>To use the offload option, you must have one or more Intel(R) Xeon

doc/Section_accelerate.txt

@@ -8,6 +8,8 @@ Section"_Section_howto.html :c
 
 :line
 
+NOTE: USER-CUDA: no newton setting needed?
+
 5. Accelerating LAMMPS performance :h3
 
 This section describes various methods for improving LAMMPS
@@ -40,12 +42,12 @@ Before trying to make your simulation run faster, you should
 understand how it currently performs and where the bottlenecks are.
 
 The best way to do this is run the your system (actual number of
-atoms) for a modest number of timesteps (say 100, or a few 100 at
+atoms) for a modest number of timesteps (say 100 steps) on several
-most) on several different processor counts, including a single
+different processor counts, including a single processor if possible.
-processor if possible.  Do this for an equilibrium version of your
+Do this for an equilibrium version of your system, so that the
-system, so that the 100-step timings are representative of a much
+100-step timings are representative of a much longer run.  There is
-longer run.  There is typically no need to run for 1000s or timesteps
+typically no need to run for 1000s of timesteps to get accurate
-to get accurate timings; you can simply extrapolate from short runs.
+timings; you can simply extrapolate from short runs.
 
 For the set of runs, look at the timing data printed to the screen and
 log file at the end of each LAMMPS run.  "This
@@ -238,6 +240,13 @@ Technologies).  It contains a handful of pair styles whose compute()
 methods were rewritten in C++ templated form to reduce the overhead
 due to if tests and other conditional code.
 
+Here is a quick overview of how to use the OPT package:
+
+include the OPT package and build LAMMPS
+use OPT pair styles in your input script :ul
+
+Details follow.
+
 [Required hardware/software:]
 
 None.
@@ -249,8 +258,8 @@ Include the package and build LAMMPS.
 make yes-opt
 make machine :pre
 
-No additional compile/link flags are needed in your lo-level
+No additional compile/link flags are needed in your machine
-src/MAKE/Makefile.machine.
+Makefile in src/MAKE.
 
 [Running with the OPT package:]
 
@@ -290,6 +299,16 @@ nearly all bonded styles (bond, angle, dihedral, improper), several
 Kspace styles, and a few fix styles.  The package currently
 uses the OpenMP interface for multi-threading.
 
+Here is a quick overview of how to use the USER-OMP package:
+
+specify the -fopenmp flag for compiling and linking in your machine Makefile
+include the USER-OMP package and build LAMMPS
+specify how many threads per MPI task to run with via an environment variable or the package omp command
+enable the USER-OMP package via the "-sf omp" command-line switch, or the package omp commmand
+use USER-OMP styles in your input script :ul
+
+Details follow.
+
 [Required hardware/software:]
 
 Your compiler must support the OpenMP interface.  You should have one
@@ -355,7 +374,7 @@ style in your input script:
 
 pair_style lj/cut/omp 2.5
 fix nve/omp :pre
-<
+
 Or you can run with the "-sf omp" "command-line
 switch"_Section_start.html#start_7, which will automatically append
 "omp" to styles that support it.
@@ -386,7 +405,7 @@ benchmark runs for a specific simulation running on a specific
 machine, paying attention to guidelines discussed in the next
 sub-section.
 
-A description of the multi-threading strategy used in the UESR-OMP
+A description of the multi-threading strategy used in the USER-OMP
 package and some performance examples are "presented
 here"_http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1
 
@@ -495,6 +514,19 @@ NVIDIA support as well as more general OpenCL support, so that the
 same functionality can eventually be supported on a variety of GPU
 hardware. :l,ule
 
+Here is a quick overview of how to use the GPU package:
+
+build the library in lib/gpu for your GPU hardware (CUDA_ARCH) with desired precision (CUDA_PREC)
+include the GPU package and build LAMMPS
+decide how many MPI tasks per GPU to run with, i.e. set MPI tasks/node via mpirun
+specify how many GPUs per node to use (default = 1) via the package gpu command
+enable the GPU package via the "-sf gpu" command-line switch, or the package gpu commmand
+use the newton command to turn off Newton's law for pairwise interactions
+use the package gpu command to enable neighbor list building on the GPU if desired
+use GPU pair styles and kspace styles in your input script :ul
+
+Details follow.
+
 [Required hardware/software:]
 
 To use this package, you currently need to have an NVIDIA GPU and
@@ -707,10 +739,20 @@ Neighbor lists are constructed on the GPU. :l
 The package only supports use of a single MPI task, running on a
 single CPU (core), assigned to each GPU. :l,ule
 
+Here is a quick overview of how to use the USER-CUDA package:
+
+build the library in lib/cuda for your GPU hardware (arch with desired precision (precision)
+include the USER-CUDA package and build LAMMPS
+use the mpirun command to specify 1 MPI task per GPU (on each node)
+specify how many GPUs per node to use (default = 1) via the package cuda command
+enable the USER-CUDA package via the "-c on" command-line switch
+use USER-CUDA styles in your input script :ul
+
+Details follow.
+
 [Required hardware/software:]
 
-To use this package, you need to have an NVIDIA GPU and
+To use this package, you need to have one or more NVIDIA GPUs and install the NVIDIA Cuda software on your system:
-install the NVIDIA Cuda software on your system:
 
 Your NVIDIA GPU needs to support Compute Capability 1.3. This list may
 help you to find out the Compute Capability of your card:
@@ -1253,6 +1295,24 @@ suffix to "omp" so that styles from the USER-OMP package will be used
 if available, after first testing if a style from the USER-INTEL
 package is available.
 
+Here is a quick overview of how to use the USER-INTEL package
+for CPU acceleration:
+
+specify these CCFLAGS in your machine Makefile: -fopenmp, -DLAMMPS_MEMALIGN=64, and -restrict, -xHost
+specify -fopenmp with LINKFLAGS in your machine Makefile
+include the USER-INTEL package and (optionally) USER-OMP package and build LAMMP
+if also using the USER-OMP package, specify how many threads per MPI task to run with via an environment variable or the package omp command
+use USER-INTEL styles in your input script :ul
+
+Running with the USER-INTEL package to offload to the Intel(R) Xeon Phi(TM)
+is the same except for these additional steps:
+
+add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in your Machine makefile
+add the flag -offload to the LINKFLAGS in your Machine makefile
+the package intel command can be used to adjust threads per coprocessor :ul
+
+Details follow.
+
 [Required hardware/software:]
 
 To use the offload option, you must have one or more Intel(R) Xeon

doc/Section_commands.html

@@ -406,12 +406,13 @@ g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 <TR ALIGN="center"><TD ><A HREF = "fix_msst.html">msst</A></TD><TD ><A HREF = "fix_neb.html">neb</A></TD><TD ><A HREF = "fix_nh.html">nph (o)</A></TD><TD ><A HREF = "fix_nphug.html">nphug (o)</A></TD><TD ><A HREF = "fix_nph_asphere.html">nph/asphere (o)</A></TD><TD ><A HREF = "fix_nph_sphere.html">nph/sphere (o)</A></TD><TD ><A HREF = "fix_nh.html">npt (co)</A></TD><TD ><A HREF = "fix_npt_asphere.html">npt/asphere (o)</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_npt_sphere.html">npt/sphere (o)</A></TD><TD ><A HREF = "fix_nve.html">nve (cko)</A></TD><TD ><A HREF = "fix_nve_asphere.html">nve/asphere</A></TD><TD ><A HREF = "fix_nve_asphere_noforce.html">nve/asphere/noforce</A></TD><TD ><A HREF = "fix_nve_body.html">nve/body</A></TD><TD ><A HREF = "fix_nve_limit.html">nve/limit</A></TD><TD ><A HREF = "fix_nve_line.html">nve/line</A></TD><TD ><A HREF = "fix_nve_noforce.html">nve/noforce</A></TD></TR>
 <TR ALIGN="center"><TD ><A HREF = "fix_nve_sphere.html">nve/sphere (o)</A></TD><TD ><A HREF = "fix_nve_tri.html">nve/tri</A></TD><TD ><A HREF = "fix_nh.html">nvt (co)</A></TD><TD ><A HREF = "fix_nvt_asphere.html">nvt/asphere (o)</A></TD><TD ><A HREF = "fix_nvt_sllod.html">nvt/sllod (o)</A></TD><TD ><A HREF = "fix_nvt_sphere.html">nvt/sphere (o)</A></TD><TD ><A HREF = "fix_oneway.html">oneway</A></TD><TD ><A HREF = "fix_orient_fcc.html">orient/fcc</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_planeforce.html">planeforce</A></TD><TD ><A HREF = "fix_poems.html">poems</A></TD><TD ><A HREF = "fix_pour.html">pour</A></TD><TD ><A HREF = "fix_press_berendsen.html">press/berendsen</A></TD><TD ><A HREF = "fix_print.html">print</A></TD><TD ><A HREF = "fix_property_atom.html">property/atom</A></TD><TD ><A HREF = "fix_qeq_comb.html">qeq/comb (o)</A></TD><TD ><A HREF = "fix_reax_bonds.html">reax/bonds</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_planeforce.html">planeforce</A></TD><TD ><A HREF = "fix_poems.html">poems</A></TD><TD ><A HREF = "fix_pour.html">pour</A></TD><TD ><A HREF = "fix_press_berendsen.html">press/berendsen</A></TD><TD ><A HREF = "fix_print.html">print</A></TD><TD ><A HREF = "fix_property_atom.html">property/atom</A></TD><TD ><A HREF = "fix_qeq.html">qeq</A></TD><TD ><A HREF = "fix_qeq_comb.html">qeq/comb (o)</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_recenter.html">recenter</A></TD><TD ><A HREF = "fix_restrain.html">restrain</A></TD><TD ><A HREF = "fix_rigid.html">rigid (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nph (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/npt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nve (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nvt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small (o)</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_reax_bonds.html">reax/bonds</A></TD><TD ><A HREF = "fix_recenter.html">recenter</A></TD><TD ><A HREF = "fix_restrain.html">restrain</A></TD><TD ><A HREF = "fix_rigid.html">rigid (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nph (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/npt (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nve (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/nvt (o)</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_rigid.html">rigid/small/nph</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/npt</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nve</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nvt</A></TD><TD ><A HREF = "fix_setforce.html">setforce (c)</A></TD><TD ><A HREF = "fix_shake.html">shake (c)</A></TD><TD ><A HREF = "fix_spring.html">spring</A></TD><TD ><A HREF = "fix_spring_rg.html">spring/rg</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_rigid.html">rigid/small (o)</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nph</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/npt</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nve</A></TD><TD ><A HREF = "fix_rigid.html">rigid/small/nvt</A></TD><TD ><A HREF = "fix_setforce.html">setforce (c)</A></TD><TD ><A HREF = "fix_shake.html">shake (c)</A></TD><TD ><A HREF = "fix_spring.html">spring</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_spring_self.html">spring/self</A></TD><TD ><A HREF = "fix_srd.html">srd</A></TD><TD ><A HREF = "fix_store_force.html">store/force</A></TD><TD ><A HREF = "fix_store_state.html">store/state</A></TD><TD ><A HREF = "fix_temp_berendsen.html">temp/berendsen (c)</A></TD><TD ><A HREF = "fix_temp_csvr.html">temp/csvr</A></TD><TD ><A HREF = "fix_temp_rescale.html">temp/rescale (c)</A></TD><TD ><A HREF = "fix_thermal_conductivity.html">thermal/conductivity</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_spring_rg.html">spring/rg</A></TD><TD ><A HREF = "fix_spring_self.html">spring/self</A></TD><TD ><A HREF = "fix_srd.html">srd</A></TD><TD ><A HREF = "fix_store_force.html">store/force</A></TD><TD ><A HREF = "fix_store_state.html">store/state</A></TD><TD ><A HREF = "fix_temp_berendsen.html">temp/berendsen (c)</A></TD><TD ><A HREF = "fix_temp_csvr.html">temp/csvr</A></TD><TD ><A HREF = "fix_temp_rescale.html">temp/rescale (c)</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_tmd.html">tmd</A></TD><TD ><A HREF = "fix_ttm.html">ttm</A></TD><TD ><A HREF = "fix_tune_kspace.html">tune/kspace</A></TD><TD ><A HREF = "fix_vector.html">vector</A></TD><TD ><A HREF = "fix_viscosity.html">viscosity</A></TD><TD ><A HREF = "fix_viscous.html">viscous (c)</A></TD><TD ><A HREF = "fix_wall.html">wall/colloid</A></TD><TD ><A HREF = "fix_wall_gran.html">wall/gran</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_thermal_conductivity.html">thermal/conductivity</A></TD><TD ><A HREF = "fix_tmd.html">tmd</A></TD><TD ><A HREF = "fix_ttm.html">ttm</A></TD><TD ><A HREF = "fix_tune_kspace.html">tune/kspace</A></TD><TD ><A HREF = "fix_vector.html">vector</A></TD><TD ><A HREF = "fix_viscosity.html">viscosity</A></TD><TD ><A HREF = "fix_viscous.html">viscous (c)</A></TD><TD ><A HREF = "fix_wall.html">wall/colloid</A></TD></TR>
-<TR ALIGN="center"><TD ><A HREF = "fix_wall.html">wall/harmonic</A></TD><TD ><A HREF = "fix_wall.html">wall/lj1043</A></TD><TD ><A HREF = "fix_wall.html">wall/lj126</A></TD><TD ><A HREF = "fix_wall.html">wall/lj93</A></TD><TD ><A HREF = "fix_wall_piston.html">wall/piston</A></TD><TD ><A HREF = "fix_wall_reflect.html">wall/reflect</A></TD><TD ><A HREF = "fix_wall_region.html">wall/region</A></TD><TD ><A HREF = "fix_wall_srd.html">wall/srd</A> 
+<TR ALIGN="center"><TD ><A HREF = "fix_wall_gran.html">wall/gran</A></TD><TD ><A HREF = "fix_wall.html">wall/harmonic</A></TD><TD ><A HREF = "fix_wall.html">wall/lj1043</A></TD><TD ><A HREF = "fix_wall.html">wall/lj126</A></TD><TD ><A HREF = "fix_wall.html">wall/lj93</A></TD><TD ><A HREF = "fix_wall_piston.html">wall/piston</A></TD><TD ><A HREF = "fix_wall_reflect.html">wall/reflect</A></TD><TD ><A HREF = "fix_wall_region.html">wall/region</A></TD></TR>
+<TR ALIGN="center"><TD ><A HREF = "fix_wall_srd.html">wall/srd</A> 
 </TD></TR></TABLE></DIV>
 
 <P>These are additional fix styles in USER packages, which can be used if

doc/Section_commands.txt

@@ -527,6 +527,7 @@ g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
 "press/berendsen"_fix_press_berendsen.html,
 "print"_fix_print.html,
 "property/atom"_fix_property_atom.html,
+"qeq"_fix_qeq.html,
 "qeq/comb (o)"_fix_qeq_comb.html,
 "reax/bonds"_fix_reax_bonds.html,
 "recenter"_fix_recenter.html,

doc/fix_qeq.html

@@ -0,0 +1,182 @@
+<HTML>
+<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A> 
+</CENTER>
+
+
+
+
+
+
+<HR>
+
+<H3>fix qeq/point command 
+</H3>
+<H3>fix qeq/shielded command 
+</H3>
+<H3>fix qeq/slater command 
+</H3>
+<H3>fix qeq/dynamic command 
+</H3>
+<P><B>Syntax:</B>
+</P>
+<PRE>fix ID group-ID style Nevery cutoff tolerance maxiter params 
+</PRE>
+<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
+<LI>style = <I>qeq/point</I> or <I>qeq/shielded</I> or <I>qeq/slater</I> or <I>qeq/dynamic</I>
+<LI>Nevery = perform charge equilibration every this many steps
+<LI>cutoff = global cutoff for charge-charge interactions (distance unit)
+<LI>tolerance = precision to which charges will be equilibrated
+<LI>maxiter = maximum iterations to perform charge equilibration
+<LI>params = a filename 
+</UL>
+<P><B>Examples:</B>
+</P>
+<PRE>fix 1 all qeq/point 1 10 1.0e-6 200 param.qeq1
+fix 1 qeq qeq/shielded 1 8 1.0e-6 100 param.qeq2
+fix 1 all qeq/slater 5 10 1.0e-6 100 params
+fix 1 qeq qeq/dynamic 1 12 1.0e-3 100 my_qeq 
+</PRE>
+<P><B>Description:</B>
+</P>
+<P>Perform the charge equilibration (QEq) method as described in <A HREF = "#Rappe">(Rappe
+and Goddard)</A> and formulated in <A HREF = "#Nakano">(Nakano)</A> (also 
+known as the matrix inversion method)
+and in <A HREF = "#Rick">(Rick and Stuart)</A> (also known as the extended 
+Lagrangian method) based on the electronegativity equilization principle.  
+These fixes can be used with any potential in LAMMPS, so long as it defines and
+uses charges on each atom and that QEq parameters are provided.
+</P>
+<P>IMPORTANT NOTE: The <A HREF = "fix_qeq_comb.html">fix qeq/comb</A>
+command should be used to perform charge equliibration with the <A HREF = "pair_comb.html">COMB
+potential</A>.  The <A HREF = "fix_qeq_reax.html">fix qeq/reax</A>
+command can be used to perform charge equilibration with the <A HREF = "pair_reax_c.html">ReaxFF force
+field</A>, although fix qeq/shielded yields exact same 
+results as fix qeq/reax if <I>Nevery</I>, cutoff</I>, and <I>tolerance</I> are the same.
+</P>
+<P>The QEq method minimizes the electrostatic energy of the system (or 
+equalizes the derivative of energy with respect to charge of all the 
+atoms) by adjusting the partial charge on individual atoms based on 
+interactions with their neighbors within <I>cutoff</I>.
+It reqires some parameters for each atom type provided in a file 
+specified by <I>params</I>.  First line of the file should be the unit 
+style of these parameters.  These
+fixes support real, metal, si, cgs, and electron units.  Using lj, 
+micro, and nano units will result in an error.
+Each of the following lines should be formatted as follows:
+</P>
+<PRE>itype chi eta gamma zeta qcore 
+</PRE>
+<P>where <I>itype</I> is the atom type from 1 to Ntypes, <I>chi</I> denotes the
+electronegativity in energy units, <I>eta</I> denotes the self-Coulomb
+potential in energy units, <I>gamma</I> denotes the shielded Coulomb 
+constant defined by <A HREF = "#vanDuin">ReaxFF force field</A> in distance units, 
+<I>zeta</I> denotes the Slater type orbital exponent defined by the 
+<A HREF = "#Streitz">Streitz-Mintmire</A> potential (not yet available in LAMMPS) 
+in reverse distance units, and <I>qcore</I> denotes the charge of the 
+nucleus defined by the Streitz-Mintmire potential in charge units.
+</P>
+<P>The <I>qeq/point</I> style describes partial charges on atoms as point charges.
+Interaction between a pair of charged particles is 1/r, which is the simplest
+description of the interaction between charges.  Only <I>chi</I> and <I>eta</I> 
+parameters in the <I>params</I> file are used.  Note that Coulomb catastrophe 
+can occur if repulsion between the pair of charged particles is too weak.
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+</P>
+<P>The <I>qeq/shielded</I> style describes partial charges on atoms also as point 
+charges, but uses a shielded Coulomb potential to describe
+the interaction between a pair of charged particles.  Interaction through 
+the shielded Coulomb is given by equation (13) of the 
+<A HREF = "#vanDuin">ReaxFF force field</A> paper.  The shielding accounts for charge overlap 
+between charged particles at small separation.  This style is the same as 
+<A HREF = "fix_qeq_reax.html">fix qeq/reax</A>, and can be used with 
+<A HREF = "pair_reax_c.html">pair_style reax/c</A>.  Only <I>chi</I>, <I>eta</I>, and <I>gamma</I> parameters 
+in the <I>params</I> file are used.
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+</P>
+<P>The <I>qeq/slater</I> style describes partial charges on atoms as spherical 
+charge densities centered around atoms via the Slater 1<I>s</I> orbital, so that 
+the interaction between a pair of charged particles is the product of two 
+Slater 1<I>s</I> orbitals.  The expression for the Slater 1<I>s</I> orbital is given under
+equation (6) of the <A HREF = "#Streitz">Streitz-Mintmire</A> paper.  <I>chi</I>, <I>eta</I>, <I>zeta</I>, 
+and <I>qcore</I> parameters in the <I>params</I> file are used. 
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+</P>
+<P>The <I>qeq/dynamic</I> style describes partial charges on atoms as point charges 
+that interact through 1/r, but the extended Lagrangian method is used to solve
+partial charges on atoms.  Only <I>chi</I> and <I>eta</I> parameters in the <I>params</I> file 
+are used.  Note that Coulomb catastrophe can occur if repulsion between the 
+pair of charged particles is too weak.
+A tolerance of 1.0e-3 is usually a good number.
+</P>
+<P>Note that <I>qeq/point</I>, <I>qeq/shielded</I>, and <I>qeq/slater</I> describe different charge
+models, whereas the matrix inversion method and the extended Lagrangian method 
+(<I>qeq/dynamic</I>) are different solvers.
+</P>
+<P>Note that the <I>qeq/point</I> and the <I>qeq/dynamic</I> styles both describe charges as 
+point charges that interact through 1/r relationship, but solve partial charges 
+on atoms using different solvers.  <I>qeq/point</I> and the <I>qeq/dynamic</I> styles should 
+yield comparable results if the QEq parameters and <I>Nevery</I>, cutoff</I>, 
+and <I>tolerance</I> are the same.  <I>qeq/point</I> is typically faster, but <I>qeq/dynamic</I> 
+scales better on larger sizes.
+</P>
+<P>IMPORTANT NOTE: To avoid the evaluation of the derivative of charge with 
+respect to position, which is typically ill-defined, the system should have a
+zero net charge.
+</P>
+<P>IMPORTANT NOTE: Developing QEq parameters (chi, eta, gamma, zeta, and qcore)
+is an "art".  Charges on atoms are not guaranteed to equilibrate with arbitrary 
+choices of these parameters.  We do not develop these QEq paramters.
+</P>
+<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
+</P>
+<P>No information about these fixes is written to <A HREF = "restart.html">binary restart
+files</A>.  No global scalar or vector or per-atom
+quantities are stored by these fixes for access by various <A HREF = "Section_howto.html#howto_15">output
+commands</A>.  No parameter of these fixes can
+be used with the <I>start/stop</I> keywords of the <A HREF = "run.html">run</A> command.
+</P>
+<P>Thexe fixes are invoked during <A HREF = "minimize.html">energy minimization</A>.
+</P>
+<P><B>Restrictions:</B>
+</P>
+<P>These fixes are part of the USER-QEQ package.  They are only enabled if
+LAMMPS was built with that package.  See the <A HREF = "Section_start.html#start_3">Making
+LAMMPS</A> section for more info.
+</P>
+<P><B>Related commands:</B>
+</P>
+<P><A HREF = "fix_qeq_reax.html">fix qeq/reax</A>
+<A HREF = "fix_qeq_comb.html">fix qeq/comb</A>
+</P>
+<P><B>Default:</B> none
+</P>
+<HR>
+
+<A NAME = "Rappe"></A>
+
+<P><B>(Rappe and Goddard)</B> A. K. Rappe and W. A. Goddard III, J Physical Chemistry, 105,
+3358-3363 (1991).
+</P>
+<A NAME = "Nakano"></A>
+
+<P><B>(Nakano)</B> A. Nakano, Computer Physics Communications, 104, 59-69 (1997).
+</P>
+<A NAME = "Rick"></A>
+
+<P><B>(Rick and Stuart)</B> S. W. Rick, S. J. Stuart, B. J. Berne, J Chemical Physics
+101, 16141 (1994).
+</P>
+<A NAME = "Streitz"></A>
+
+<P><B>(Streitz-Mintmire)</B> F. H. Streitz, J. W. Mintmire, Physical Review B, 50, 
+16, 11996 (1994)
+</P>
+<A NAME = "vanDuin"></A>
+
+<P><B>(ReaxFF)</B> A. C. T. van Duin, S. Dasgupta, F. Lorant, W. A. Goddard III, J 
+Physical Chemistry, 105, 9396-9049 (2001)
+</P>
+</HTML>

doc/fix_qeq.txt

@@ -0,0 +1,169 @@
+"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
+
+:link(lws,http://lammps.sandia.gov)
+:link(ld,Manual.html)
+:link(lc,Section_commands.html#comm)
+
+:line
+
+fix qeq/point command :h3
+fix qeq/shielded command :h3
+fix qeq/slater command :h3
+fix qeq/dynamic command :h3
+
+[Syntax:]
+
+fix ID group-ID style Nevery cutoff tolerance maxiter params :pre
+
+ID, group-ID are documented in "fix"_fix.html command
+style = {qeq/point} or {qeq/shielded} or {qeq/slater} or {qeq/dynamic}
+Nevery = perform charge equilibration every this many steps
+cutoff = global cutoff for charge-charge interactions (distance unit)
+tolerance = precision to which charges will be equilibrated
+maxiter = maximum iterations to perform charge equilibration
+params = a filename :ul
+
+[Examples:]
+
+fix 1 all qeq/point 1 10 1.0e-6 200 param.qeq1
+fix 1 qeq qeq/shielded 1 8 1.0e-6 100 param.qeq2
+fix 1 all qeq/slater 5 10 1.0e-6 100 params
+fix 1 qeq qeq/dynamic 1 12 1.0e-3 100 my_qeq :pre
+
+[Description:]
+
+Perform the charge equilibration (QEq) method as described in "(Rappe
+and Goddard)"_#Rappe and formulated in "(Nakano)"_#Nakano (also 
+known as the matrix inversion method)
+and in "(Rick and Stuart)"_#Rick (also known as the extended 
+Lagrangian method) based on the electronegativity equilization principle.  
+These fixes can be used with any potential in LAMMPS, so long as it defines and
+uses charges on each atom and that QEq parameters are provided.
+
+IMPORTANT NOTE: The "fix qeq/comb"_fix_qeq_comb.html
+command should be used to perform charge equliibration with the "COMB
+potential"_pair_comb.html.  The "fix qeq/reax"_fix_qeq_reax.html
+command can be used to perform charge equilibration with the "ReaxFF force
+field"_pair_reax_c.html, although fix qeq/shielded yields exact same 
+results as fix qeq/reax if {Nevery}, cutoff}, and {tolerance} are the same.
+
+The QEq method minimizes the electrostatic energy of the system (or 
+equalizes the derivative of energy with respect to charge of all the 
+atoms) by adjusting the partial charge on individual atoms based on 
+interactions with their neighbors within {cutoff}.
+It reqires some parameters for each atom type provided in a file 
+specified by {params}.  First line of the file should be the unit 
+style of these parameters.  These
+fixes support real, metal, si, cgs, and electron units.  Using lj, 
+micro, and nano units will result in an error.
+Each of the following lines should be formatted as follows:
+
+itype chi eta gamma zeta qcore :pre
+
+where {itype} is the atom type from 1 to Ntypes, {chi} denotes the
+electronegativity in energy units, {eta} denotes the self-Coulomb
+potential in energy units, {gamma} denotes the shielded Coulomb 
+constant defined by "ReaxFF force field"_#vanDuin in distance units, 
+{zeta} denotes the Slater type orbital exponent defined by the 
+"Streitz-Mintmire"_#Streitz potential (not yet available in LAMMPS) 
+in reverse distance units, and {qcore} denotes the charge of the 
+nucleus defined by the Streitz-Mintmire potential in charge units.
+
+The {qeq/point} style describes partial charges on atoms as point charges.
+Interaction between a pair of charged particles is 1/r, which is the simplest
+description of the interaction between charges.  Only {chi} and {eta} 
+parameters in the {params} file are used.  Note that Coulomb catastrophe 
+can occur if repulsion between the pair of charged particles is too weak.
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+
+The {qeq/shielded} style describes partial charges on atoms also as point 
+charges, but uses a shielded Coulomb potential to describe
+the interaction between a pair of charged particles.  Interaction through 
+the shielded Coulomb is given by equation (13) of the 
+"ReaxFF force field"_#vanDuin paper.  The shielding accounts for charge overlap 
+between charged particles at small separation.  This style is the same as 
+"fix qeq/reax"_fix_qeq_reax.html, and can be used with 
+"pair_style reax/c"_pair_reax_c.html.  Only {chi}, {eta}, and {gamma} parameters 
+in the {params} file are used.
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+
+The {qeq/slater} style describes partial charges on atoms as spherical 
+charge densities centered around atoms via the Slater 1{s} orbital, so that 
+the interaction between a pair of charged particles is the product of two 
+Slater 1{s} orbitals.  The expression for the Slater 1{s} orbital is given under
+equation (6) of the "Streitz-Mintmire"_#Streitz paper.  {chi}, {eta}, {zeta}, 
+and {qcore} parameters in the {params} file are used. 
+This style solves partial charges on atoms via the matrix inversion method.
+A tolerance of 1.0e-6 is usually a good number.
+
+The {qeq/dynamic} style describes partial charges on atoms as point charges 
+that interact through 1/r, but the extended Lagrangian method is used to solve
+partial charges on atoms.  Only {chi} and {eta} parameters in the {params} file 
+are used.  Note that Coulomb catastrophe can occur if repulsion between the 
+pair of charged particles is too weak.
+A tolerance of 1.0e-3 is usually a good number.
+
+Note that {qeq/point}, {qeq/shielded}, and {qeq/slater} describe different charge
+models, whereas the matrix inversion method and the extended Lagrangian method 
+({qeq/dynamic}) are different solvers.
+
+Note that the {qeq/point} and the {qeq/dynamic} styles both describe charges as 
+point charges that interact through 1/r relationship, but solve partial charges 
+on atoms using different solvers.  {qeq/point} and the {qeq/dynamic} styles should 
+yield comparable results if the QEq parameters and {Nevery}, cutoff}, 
+and {tolerance} are the same.  {qeq/point} is typically faster, but {qeq/dynamic} 
+scales better on larger sizes.
+
+IMPORTANT NOTE: To avoid the evaluation of the derivative of charge with 
+respect to position, which is typically ill-defined, the system should have a
+zero net charge.
+
+IMPORTANT NOTE: Developing QEq parameters (chi, eta, gamma, zeta, and qcore)
+is an "art".  Charges on atoms are not guaranteed to equilibrate with arbitrary 
+choices of these parameters.  We do not develop these QEq paramters.
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+No information about these fixes is written to "binary restart
+files"_restart.html.  No global scalar or vector or per-atom
+quantities are stored by these fixes for access by various "output
+commands"_Section_howto.html#howto_15.  No parameter of these fixes can
+be used with the {start/stop} keywords of the "run"_run.html command.
+
+Thexe fixes are invoked during "energy minimization"_minimize.html.
+
+[Restrictions:]
+
+These fixes are part of the USER-QEQ package.  They are only enabled if
+LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
+
+[Related commands:]
+
+"fix qeq/reax"_fix_qeq_reax.html
+"fix qeq/comb"_fix_qeq_comb.html
+
+[Default:] none
+
+:line
+
+:link(Rappe)
+[(Rappe and Goddard)] A. K. Rappe and W. A. Goddard III, J Physical Chemistry, 105,
+3358-3363 (1991).
+
+:link(Nakano)
+[(Nakano)] A. Nakano, Computer Physics Communications, 104, 59-69 (1997).
+
+:link(Rick)
+[(Rick and Stuart)] S. W. Rick, S. J. Stuart, B. J. Berne, J Chemical Physics
+101, 16141 (1994).
+
+:link(Streitz)
+[(Streitz-Mintmire)] F. H. Streitz, J. W. Mintmire, Physical Review B, 50, 
+16, 11996 (1994)
+
+:link(vanDuin)
+[(ReaxFF)] A. C. T. van Duin, S. Dasgupta, F. Lorant, W. A. Goddard III, J 
+Physical Chemistry, 105, 9396-9049 (2001)