ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #3517 from akohlmey/document-style-flags

Browse Source 
Provide more and updated details about implementing new styles in LAMMPS
This commit is contained in:
Axel Kohlmeyer
2022-12-10 09:59:01 -05:00
committed by GitHub
parent 4a18561005 2db1a74ba7
commit 2421f9098c
3 changed files with 181 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
doc/src/Modify_bond.rst
View File

@ -13,24 +13,65 @@ Here is a brief description of common methods you define in your
new derived class. See bond.h, angle.h, dihedral.h, and improper.h
for details and specific additional methods.
+-----------------------+---------------------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init_style* (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| init_style | check if style specific conditions are met (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (required, bond only) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (required, angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| single | force (bond only) and energy of a single bond or angle (required, bond or angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
+-----------------------+---------------------------------------------------------------------+
| Required | "pure" methods that *must* be overridden in a derived class |
+=======================+=====================================================================+
| compute | compute the molecular interactions for all listed items |
+-----------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one type |
+-----------------------+---------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (bond styles only) |
+-----------------------+---------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (angle styles only) |
+-----------------------+---------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files |
+-----------------------+---------------------------------------------------------------------+
| single | force/r (bond styles only) and energy of a single bond or angle |
+-----------------------+---------------------------------------------------------------------+
+--------------------------------+----------------------------------------------------------------------+
| Optional | methods that have a default or dummy implementation |
+================================+======================================================================+
| init | check if all coefficients are set, calls init_style() |
+--------------------------------+----------------------------------------------------------------------+
| init_style | check if style specific conditions are met |
+--------------------------------+----------------------------------------------------------------------+
| settings | apply global settings for all types |
+--------------------------------+----------------------------------------------------------------------+
| write & read_restart_settings | writes/reads global style settings to restart files |
+--------------------------------+----------------------------------------------------------------------+
| write_data | write corresponding Coeffs section(s) in data file |
+--------------------------------+----------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style |
+--------------------------------+----------------------------------------------------------------------+
| extract | provide access to internal data (bond or angle styles only) |
+--------------------------------+----------------------------------------------------------------------+
| reinit | reset all type-based parameters, called by fix adapt (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
| pack & unpack_forward_comm | copy data to and from buffer in forward communication (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
| pack & unpack_reverse_comm | copy data to and from buffer in reverse communication (bonds only) |
+--------------------------------+----------------------------------------------------------------------+
Here is a list of flags or settings that should be set in the
constructor of the derived class when they differ from the default
setting.
+---------------------------------+------------------------------------------------------------------------------+---------+
| Name of flag | Description | default |
+=================================+==============================================================================+=========+
| writedata | 1 if write_data() is implemented | 1 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| single_extra | number of extra single values calculated (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| partial_flag | 1 if bond type can be set to 0 and deleted (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| reinitflag | 1 if style has reinit() and is compatible with fix adapt | 1 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_forward | size of buffer (in doubles) for forward communication (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_reverse | size of buffer (in doubles) for reverse communication (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+
| comm_reverse_off | size of buffer for reverse communication with newton off (bond styles only) | 0 |
+---------------------------------+------------------------------------------------------------------------------+---------+

132
doc/src/Modify_pair.rst
View File

@ -1,35 +1,121 @@
Pair styles
===========
Classes that compute pairwise interactions are derived from the Pair
class. In LAMMPS, pairwise calculation include many-body 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
LAMMPS.
Classes that compute pairwise non-bonded interactions are derived from
the Pair class. In LAMMPS, pairwise calculation include many-body
potentials such as EAM, Tersoff, or ReaxFF where particles interact
without an explicit bond topology but include interactions beyond
pairwise non-bonded contributions. New styles can be created to add
support for additional pair potentials to LAMMPS. When the
modifications are small, sometimes it is more effective to derive from
an existing pair style class. This latter approach is also used by
:doc:`Accelerator packages <Speed_packages>` where the accelerated style
names differ from their base classes by an appended suffix.
Pair_lj_cut.cpp is a simple example of a Pair class, though it
includes some optional methods to enable its use with rRESPA.
The file ``src/pair_lj_cut.cpp`` is an example of a Pair class with a
very simple potential function. It includes several optional methods to
enable its use with :doc:`run_style respa <run_style>` and :doc:`compute
group/group <compute_group_group>`.
Here is a brief description of the class methods in pair.h:
Here is a brief list of some the class methods in the Pair class that
*must* be or *may* be overridden in a derived class.
+---------------------------------+---------------------------------------------------------------------+
| Required | "pure" methods that *must* be overridden in a derived class |
+=================================+=====================================================================+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+---------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
| settings | processes the arguments to the pair_style command |
+---------------------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+---------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+---------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
| coeff | set coefficients for one i,j type pair, called from pair_coeff |
+---------------------------------+---------------------------------------------------------------------+
The inner/middle/outer routines are optional.
+---------------------------------+----------------------------------------------------------------------+
| Optional | methods that have a default or dummy implementation |
+=================================+======================================================================+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+----------------------------------------------------------------------+
| init_style | style initialization: request neighbor list(s), error checks |
+---------------------------------+----------------------------------------------------------------------+
| init_list | Neighbor class callback function to pass neighbor list to pair style |
+---------------------------------+----------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+----------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+----------------------------------------------------------------------+
| memory_usage | return estimated amount of memory used by the pair style |
+---------------------------------+----------------------------------------------------------------------+
| modify_params | process arguments to pair_modify command |
+---------------------------------+----------------------------------------------------------------------+
| extract | provide access to internal scalar or per-type data like cutoffs |
+---------------------------------+----------------------------------------------------------------------+
| extract_peratom | provide access to internal per-atom data |
+---------------------------------+----------------------------------------------------------------------+
| setup | initialization at the beginning of a run |
+---------------------------------+----------------------------------------------------------------------+
| finish | called at the end of a run, e.g. to print |
+---------------------------------+----------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+----------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+----------------------------------------------------------------------+
| write_data | write Pair Coeffs section to data file |
+---------------------------------+----------------------------------------------------------------------+
| write_data_all | write PairIJ Coeffs section to data file |
+---------------------------------+----------------------------------------------------------------------+
| pack & unpack_forward_comm | copy data to and from buffer if style uses forward communication |
+---------------------------------+----------------------------------------------------------------------+
| pack & unpack_reverse_comm | copy data to and from buffer if style uses reverse communication |
+---------------------------------+----------------------------------------------------------------------+
| reinit | reset all type-based parameters, called by fix adapt for example |
+---------------------------------+----------------------------------------------------------------------+
| reset_dt | called when the time step is changed by timestep or fix reset/dt |
+---------------------------------+----------------------------------------------------------------------+
Here is a list of flags or settings that should be set in the
constructor of the derived pair class when they differ from the default
setting.
+---------------------------------+-------------------------------------------------------------+---------+
| Name of flag | Description | default |
+=================================+=============================================================+=========+
| single_enable | 1 if single() method is implemented, 0 if missing | 1 |
+---------------------------------+-------------------------------------------------------------+---------+
| respa_enable | 1 if pair style has compute_inner/middle/outer() | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| restartinfo | 1 if pair style writes its settings to a restart | 1 |
+---------------------------------+-------------------------------------------------------------+---------+
| one_coeff | 1 if only a pair_coeff * * command is allowed | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| manybody_flag | 1 if pair style is a manybody potential | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| unit_convert_flag | value != 0 indicates support for unit conversion | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| no_virial_fdotr_compute | 1 if pair style does not call virial_fdotr_compute() | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| writedata | 1 if write_data() and write_data_all() are implemented | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| comm_forward | size of buffer (in doubles) for forward communication | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| comm_reverse | size of buffer (in doubles) for reverse communication | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| ghostneigh | 1 if cutghost is set and style uses neighbors of ghosts | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| finitecutflag | 1 if cutoff depends on diameter of atoms | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| reinitflag | 1 if style has reinit() and is compatible with fix adapt | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| ewaldflag | 1 if compatible with kspace_style ewald | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| pppmflag | 1 if compatible with kspace_style pppm | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| msmflag | 1 if compatible with kspace_style msm | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| dispersionflag | 1 if compatible with ewald/disp or pppm/disp | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| tip4pflag | 1 if compatible with kspace_style pppm/tip4p | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| dipoleflag | 1 if compatible with dipole kspace_style | 0 |
+---------------------------------+-------------------------------------------------------------+---------+
| spinflag | 1 if compatible with spin kspace_style | 0 |
+---------------------------------+-------------------------------------------------------------+---------+

10
doc/utils/sphinx-config/false_positives.txt
View File

@ -611,6 +611,7 @@ curv
Cusentino
customIDs
cutbond
cutghost
cuthi
cutinner
cutlo
@ -753,6 +754,7 @@ dimensionality
dimensioned
dimgray
dipolar
dipoleflag
dir
Direc
dirname
@ -761,6 +763,7 @@ discretization
discretized
discretizing
disp
dispersionflag
dissipative
Dissipative
distharm
@ -1028,6 +1031,7 @@ evirials
ew
ewald
Ewald
ewaldflag
excitations
excv
exe
@ -1101,6 +1105,7 @@ Fincham
Fint
fingerprintconstants
fingerprintsperelement
finitecutflag
Finnis
Fiorin
fitpod
@ -2214,6 +2219,7 @@ msd
msi
MSI
msm
msmflag
msse
msst
Mtchell
@ -2793,6 +2799,7 @@ PowerShell
ppme
ppn
pppm
pppmflag
Prakash
Praprotnik
prd
@ -2973,6 +2980,7 @@ refactoring
reflectionstyle
Reinders
reinit
reinitflag
relaxbox
relink
relres
@ -3308,6 +3316,7 @@ SPH
spica
SPICA
Spickermann
spinflag
splined
spparks
Sprik
@ -3861,6 +3870,7 @@ workflows
Workum
Worley
Wriggers
writedata
Wuppertal
Wurtzite
www