forked from lijiext/lammps
728 lines
38 KiB
HTML
728 lines
38 KiB
HTML
<HTML>
|
|
<CENTER><A HREF = "Section_tools.html">Previous Section</A> - <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> - <A HREF = "Section_python.html">Next
|
|
Section</A>
|
|
</CENTER>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
|
|
<H3>10. Modifying & extending LAMMPS
|
|
</H3>
|
|
<P>This section describes how to customize LAMMPS by modifying
|
|
and extending its source code.
|
|
</P>
|
|
10.1 <A HREF = "#mod_1">Atom styles</A><BR>
|
|
10.2 <A HREF = "#mod_2">Bond, angle, dihedral, improper potentials</A><BR>
|
|
10.3 <A HREF = "#mod_3">Compute styles</A><BR>
|
|
10.4 <A HREF = "#mod_4">Dump styles</A><BR>
|
|
10.5 <A HREF = "#mod_5">Dump custom output options</A><BR>
|
|
10.6 <A HREF = "#mod_6">Fix styles</A> which include integrators, temperature and pressure control, force constraints, boundary conditions, diagnostic output, etc<BR>
|
|
10.7 <A HREF = "mod_7">Input script commands</A><BR>
|
|
10.8 <A HREF = "#mod_8">Kspace computations</A><BR>
|
|
10.9 <A HREF = "#mod_9">Minimization styles</A><BR>
|
|
10.10 <A HREF = "#mod_10">Pairwise potentials</A><BR>
|
|
10.11 <A HREF = "#mod_11">Region styles</A><BR>
|
|
10.12 <A HREF = "#mod_12">Body styles</A><BR>
|
|
10.13 <A HREF = "#mod_13">Thermodynamic output options</A><BR>
|
|
10.14 <A HREF = "#mod_14">Variable options</A><BR>
|
|
10.15 <A HREF = "#mod_15">Submitting new features for inclusion in LAMMPS</A> <BR>
|
|
|
|
<P>LAMMPS is designed in a modular fashion so as to be easy to modify and
|
|
extend with new functionality. In fact, about 75% of its source code
|
|
is files added in this fashion.
|
|
</P>
|
|
<P>In this section, changes and additions users can make are listed along
|
|
with minimal instructions. If you add a new feature to LAMMPS and
|
|
think it will be of interest to general users, we encourage you to
|
|
submit it to the developers for inclusion in the released version of
|
|
LAMMPS. Information about how to do this is provided
|
|
<A HREF = "#mod_14">below</A>.
|
|
</P>
|
|
<P>The best way to add a new feature is to find a similar feature in
|
|
LAMMPS and look at the corresponding source and header files to figure
|
|
out what it does. You will need some knowledge of C++ to be able to
|
|
understand the hi-level structure of LAMMPS and its class
|
|
organization, but functions (class methods) that do actual
|
|
computations are written in vanilla C-style code and operate on simple
|
|
C-style data structures (vectors and arrays).
|
|
</P>
|
|
<P>Most of the new features described in this section require you to
|
|
write a new C++ derived class (except for exceptions described below,
|
|
where you can make small edits to existing files). Creating a new
|
|
class requires 2 files, a source code file (*.cpp) and a header file
|
|
(*.h). The derived class must provide certain methods to work as a
|
|
new option. Depending on how different your new feature is compared
|
|
to existing features, you can either derive from the base class
|
|
itself, or from a derived class that already exists. Enabling LAMMPS
|
|
to invoke the new class is as simple as putting the two source
|
|
files in the src dir and re-building LAMMPS.
|
|
</P>
|
|
<P>The advantage of C++ and its object-orientation is that all the code
|
|
and variables needed to define the new feature are in the 2 files you
|
|
write, and thus shouldn't make the rest of LAMMPS more complex or
|
|
cause side-effect bugs.
|
|
</P>
|
|
<P>Here is a concrete example. Suppose you write 2 files pair_foo.cpp
|
|
and pair_foo.h that define a new class PairFoo that computes pairwise
|
|
potentials described in the classic 1997 <A HREF = "#Foo">paper</A> by Foo, et al.
|
|
If you wish to invoke those potentials in a LAMMPS input script with a
|
|
command like
|
|
</P>
|
|
<PRE>pair_style foo 0.1 3.5
|
|
</PRE>
|
|
<P>then your pair_foo.h file should be structured as follows:
|
|
</P>
|
|
<PRE>#ifdef PAIR_CLASS
|
|
PairStyle(foo,PairFoo)
|
|
#else
|
|
...
|
|
(class definition for PairFoo)
|
|
...
|
|
#endif
|
|
</PRE>
|
|
<P>where "foo" is the style keyword in the pair_style command, and
|
|
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
|
|
files.
|
|
</P>
|
|
<P>When you re-build LAMMPS, your new pairwise potential becomes part of
|
|
the executable and can be invoked with a pair_style command like the
|
|
example above. Arguments like 0.1 and 3.5 can be defined and
|
|
processed by your new class.
|
|
</P>
|
|
<P>As illustrated by this pairwise example, many kinds of options are
|
|
referred to in the LAMMPS documentation as the "style" of a particular
|
|
command.
|
|
</P>
|
|
<P>The instructions below give the header file for the base class that
|
|
these styles are derived from. Public variables in that file are ones
|
|
used and set by the derived classes which are also used by the base
|
|
class. Sometimes they are also used by the rest of LAMMPS. Virtual
|
|
functions in the base class header file which are set = 0 are ones you
|
|
must define in your new derived class to give it the functionality
|
|
LAMMPS expects. Virtual functions that are not set to 0 are functions
|
|
you can optionally define.
|
|
</P>
|
|
<P>Additionally, new output options can be added directly to the
|
|
thermo.cpp, dump_custom.cpp, and variable.cpp files as explained
|
|
below.
|
|
</P>
|
|
<P>Here are additional guidelines for modifying LAMMPS and adding new
|
|
functionality:
|
|
</P>
|
|
<UL><LI>Think about whether what you want to do would be better as a pre- or
|
|
post-processing step. Many computations are more easily and more
|
|
quickly done that way.
|
|
|
|
<LI>Don't do anything within the timestepping of a run that isn't
|
|
parallel. E.g. don't accumulate a bunch of data on a single processor
|
|
and analyze it. You run the risk of seriously degrading the parallel
|
|
efficiency.
|
|
|
|
<LI>If your new feature reads arguments or writes output, make sure you
|
|
follow the unit conventions discussed by the <A HREF = "units.html">units</A>
|
|
command.
|
|
|
|
<LI>If you add something you think is truly useful and doesn't impact
|
|
LAMMPS performance when it isn't used, send an email to the
|
|
<A HREF = "http://lammps.sandia.gov/authors.html">developers</A>. We might be
|
|
interested in adding it to the LAMMPS distribution. See further
|
|
details on this at the bottom of this page.
|
|
</UL>
|
|
<HR>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_1"></A><H4>10.1 Atom styles
|
|
</H4>
|
|
<P>Classes that define an <A HREF = "atom_style.html">atom style</A> 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.
|
|
</P>
|
|
<P>Atom_vec_atomic.cpp is a simple example of an atom style.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See atom_vec.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >init</TD><TD > one time setup (optional)</TD></TR>
|
|
<TR><TD >grow</TD><TD > re-allocate atom arrays to longer lengths (required)</TD></TR>
|
|
<TR><TD >grow_reset</TD><TD > make array pointers in Atom and AtomVec classes consistent (required)</TD></TR>
|
|
<TR><TD >copy</TD><TD > copy info for one atom to another atom's array locations (required)</TD></TR>
|
|
<TR><TD >pack_comm</TD><TD > store an atom's info in a buffer communicated every timestep (required)</TD></TR>
|
|
<TR><TD >pack_comm_vel</TD><TD > add velocity info to communication buffer (required)</TD></TR>
|
|
<TR><TD >pack_comm_hybrid</TD><TD > store extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >unpack_comm</TD><TD > retrieve an atom's info from the buffer (required)</TD></TR>
|
|
<TR><TD >unpack_comm_vel</TD><TD > also retrieve velocity info (required)</TD></TR>
|
|
<TR><TD >unpack_comm_hybrid</TD><TD > retreive extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >pack_reverse</TD><TD > store an atom's info in a buffer communicating partial forces (required)</TD></TR>
|
|
<TR><TD >pack_reverse_hybrid</TD><TD > store extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >unpack_reverse</TD><TD > retrieve an atom's info from the buffer (required)</TD></TR>
|
|
<TR><TD >unpack_reverse_hybrid</TD><TD > retreive extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >pack_border</TD><TD > store an atom's info in a buffer communicated on neighbor re-builds (required)</TD></TR>
|
|
<TR><TD >pack_border_vel</TD><TD > add velocity info to buffer (required)</TD></TR>
|
|
<TR><TD >pack_border_hybrid</TD><TD > store extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >unpack_border</TD><TD > retrieve an atom's info from the buffer (required)</TD></TR>
|
|
<TR><TD >unpack_border_vel</TD><TD > also retrieve velocity info (required)</TD></TR>
|
|
<TR><TD >unpack_border_hybrid</TD><TD > retreive extra info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >pack_exchange</TD><TD > store all an atom's info to migrate to another processor (required)</TD></TR>
|
|
<TR><TD >unpack_exchange</TD><TD > retrieve an atom's info from the buffer (required)</TD></TR>
|
|
<TR><TD >size_restart</TD><TD > number of restart quantities associated with proc's atoms (required)</TD></TR>
|
|
<TR><TD >pack_restart</TD><TD > pack atom quantities into a buffer (required)</TD></TR>
|
|
<TR><TD >unpack_restart</TD><TD > unpack atom quantities from a buffer (required)</TD></TR>
|
|
<TR><TD >create_atom</TD><TD > create an individual atom of this style (required)</TD></TR>
|
|
<TR><TD >data_atom</TD><TD > parse an atom line from the data file (required)</TD></TR>
|
|
<TR><TD >data_atom_hybrid</TD><TD > parse additional atom info unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >data_vel</TD><TD > parse one line of velocity information from data file (optional)</TD></TR>
|
|
<TR><TD >data_vel_hybrid</TD><TD > parse additional velocity data unique to this atom style (optional)</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > tally memory allocated by atom arrays (required)
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<P>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.
|
|
</P>
|
|
<P>IMPORTANT NOTE: It is possible to add some attributes, such as a
|
|
molecule ID, to atom styles that do not have them via the <A HREF = "fix_property_atom.html">fix
|
|
property/atom</A> command. This command also
|
|
allows new custom attributes consisting of extra integer or
|
|
floating-point values to be added to atoms. See the <A HREF = "fix_property_atom.html">fix
|
|
property/atom</A> doc page for examples of cases
|
|
where this is useful and details on how to initialize, access, and
|
|
output the custom values.
|
|
</P>
|
|
<P>New <A HREF = "pair_style.html">pair styles</A>, <A HREF = "fix.html">fixes</A>, or
|
|
<A HREF = "compute.html">computes</A> can be added to LAMMPS, 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:
|
|
</P>
|
|
<PRE>int index = atom->find_custom(char *name, int &flag);
|
|
</PRE>
|
|
<P>The "name" of a custom attribute, as specified in the <A HREF = "fix_property_atom.html">fix
|
|
property/atom</A> 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
|
|
</P>
|
|
<PRE>int *ivector = atom->ivector[index];
|
|
double *dvector = atom->dvector[index];
|
|
</PRE>
|
|
<P>Ivector or dvector are vectors of length Nlocal = # of owned atoms,
|
|
which store the attributes of individual atoms.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_2"></A><H4>10.2 Bond, angle, dihedral, improper potentials
|
|
</H4>
|
|
<P>Classes that compute molecular interactions are derived from the Bond,
|
|
Angle, Dihedral, and Improper classes. New styles can be created to
|
|
add new potentials to LAMMPS.
|
|
</P>
|
|
<P>Bond_harmonic.cpp is the simplest example of a bond style. Ditto for
|
|
the harmonic forms of the angle, dihedral, and improper style
|
|
commands.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >init</TD><TD > check if all coefficients are set, calls <I>init_style</I> (optional)</TD></TR>
|
|
<TR><TD >init_style</TD><TD > check if style specific conditions are met (optional)</TD></TR>
|
|
<TR><TD >compute</TD><TD > compute the molecular interactions (required)</TD></TR>
|
|
<TR><TD >settings</TD><TD > apply global settings for all types (optional)</TD></TR>
|
|
<TR><TD >coeff</TD><TD > set coefficients for one type (required)</TD></TR>
|
|
<TR><TD >equilibrium_distance</TD><TD > length of bond, used by SHAKE (required, bond only)</TD></TR>
|
|
<TR><TD >equilibrium_angle</TD><TD > opening of angle, used by SHAKE (required, angle only)</TD></TR>
|
|
<TR><TD >write & read_restart</TD><TD > writes/reads coeffs to restart files (required)</TD></TR>
|
|
<TR><TD >single</TD><TD > force and energy of a single bond or angle (required, bond or angle only)</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > tally memory allocated by the style (optional)
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_3"></A><H4>10.3 Compute styles
|
|
</H4>
|
|
<P>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 LAMMPS.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See compute.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >init</TD><TD > perform one time setup (required)</TD></TR>
|
|
<TR><TD >init_list</TD><TD > neighbor list setup, if needed (optional)</TD></TR>
|
|
<TR><TD >compute_scalar</TD><TD > compute a scalar quantity (optional)</TD></TR>
|
|
<TR><TD >compute_vector</TD><TD > compute a vector of quantities (optional)</TD></TR>
|
|
<TR><TD >compute_peratom</TD><TD > compute one or more quantities per atom (optional)</TD></TR>
|
|
<TR><TD >compute_local</TD><TD > compute one or more quantities per processor (optional)</TD></TR>
|
|
<TR><TD >pack_comm</TD><TD > pack a buffer with items to communicate (optional)</TD></TR>
|
|
<TR><TD >unpack_comm</TD><TD > unpack the buffer (optional)</TD></TR>
|
|
<TR><TD >pack_reverse</TD><TD > pack a buffer with items to reverse communicate (optional)</TD></TR>
|
|
<TR><TD >unpack_reverse</TD><TD > unpack the buffer (optional)</TD></TR>
|
|
<TR><TD >remove_bias</TD><TD > remove velocity bias from one atom (optional)</TD></TR>
|
|
<TR><TD >remove_bias_all</TD><TD > remove velocity bias from all atoms in group (optional)</TD></TR>
|
|
<TR><TD >restore_bias</TD><TD > restore velocity bias for one atom after remove_bias (optional)</TD></TR>
|
|
<TR><TD >restore_bias_all</TD><TD > same as before, but for all atoms in group (optional)</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > tally memory usage (optional)
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_4"></A><H4>10.4 Dump styles
|
|
</H4>
|
|
<A NAME = "mod_5"></A><H4>10.5 Dump custom output options
|
|
</H4>
|
|
<P>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.
|
|
</P>
|
|
<P>Dump_atom.cpp is a simple example of a derived dump class.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See dump.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >write_header</TD><TD > write the header section of a snapshot of atoms</TD></TR>
|
|
<TR><TD >count</TD><TD > count the number of lines a processor will output</TD></TR>
|
|
<TR><TD >pack</TD><TD > pack a proc's output data into a buffer</TD></TR>
|
|
<TR><TD >write_data</TD><TD > write a proc's data to a file
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<P>See the <A HREF = "dump.html">dump</A> command and its <I>custom</I> 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.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_6"></A><H4>10.6 Fix styles
|
|
</H4>
|
|
<P>In LAMMPS, 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 LAMMPS.
|
|
</P>
|
|
<P>Fix_setforce.cpp is a simple example of setting forces on atoms to
|
|
prescribed values. There are dozens of fix options already in LAMMPS;
|
|
choose one as a template that is similar to what you want to
|
|
implement.
|
|
</P>
|
|
<P>Here is a brief description of methods you can define in your new
|
|
derived class. See fix.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >setmask</TD><TD > determines when the fix is called during the timestep (required)</TD></TR>
|
|
<TR><TD >init</TD><TD > initialization before a run (optional)</TD></TR>
|
|
<TR><TD >setup_pre_exchange</TD><TD > called before atom exchange in setup (optional)</TD></TR>
|
|
<TR><TD >setup_pre_force</TD><TD > called before force computation in setup (optional)</TD></TR>
|
|
<TR><TD >setup</TD><TD > called immediately before the 1st timestep and after forces are computed (optional)</TD></TR>
|
|
<TR><TD >min_setup_pre_force</TD><TD > like setup_pre_force, but for minimizations instead of MD runs (optional)</TD></TR>
|
|
<TR><TD >min_setup</TD><TD > like setup, but for minimizations instead of MD runs (optional)</TD></TR>
|
|
<TR><TD >initial_integrate</TD><TD > called at very beginning of each timestep (optional)</TD></TR>
|
|
<TR><TD >pre_exchange</TD><TD > called before atom exchange on re-neighboring steps (optional)</TD></TR>
|
|
<TR><TD >pre_neighbor</TD><TD > called before neighbor list build (optional)</TD></TR>
|
|
<TR><TD >pre_force</TD><TD > called after pair & molecular forces are computed (optional)</TD></TR>
|
|
<TR><TD >post_force</TD><TD > called after pair & molecular forces are computed and communicated (optional)</TD></TR>
|
|
<TR><TD >final_integrate</TD><TD > called at end of each timestep (optional)</TD></TR>
|
|
<TR><TD >end_of_step</TD><TD > called at very end of timestep (optional)</TD></TR>
|
|
<TR><TD >write_restart</TD><TD > dumps fix info to restart file (optional)</TD></TR>
|
|
<TR><TD >restart</TD><TD > uses info from restart file to re-initialize the fix (optional)</TD></TR>
|
|
<TR><TD >grow_arrays</TD><TD > allocate memory for atom-based arrays used by fix (optional)</TD></TR>
|
|
<TR><TD >copy_arrays</TD><TD > copy atom info when an atom migrates to a new processor (optional)</TD></TR>
|
|
<TR><TD >pack_exchange</TD><TD > store atom's data in a buffer (optional)</TD></TR>
|
|
<TR><TD >unpack_exchange</TD><TD > retrieve atom's data from a buffer (optional)</TD></TR>
|
|
<TR><TD >pack_restart</TD><TD > store atom's data for writing to restart file (optional)</TD></TR>
|
|
<TR><TD >unpack_restart</TD><TD > retrieve atom's data from a restart file buffer (optional)</TD></TR>
|
|
<TR><TD >size_restart</TD><TD > size of atom's data (optional)</TD></TR>
|
|
<TR><TD >maxsize_restart</TD><TD > max size of atom's data (optional)</TD></TR>
|
|
<TR><TD >setup_pre_force_respa</TD><TD > same as setup_pre_force, but for rRESPA (optional)</TD></TR>
|
|
<TR><TD >initial_integrate_respa</TD><TD > same as initial_integrate, but for rRESPA (optional)</TD></TR>
|
|
<TR><TD >post_integrate_respa</TD><TD > called after the first half integration step is done in rRESPA (optional)</TD></TR>
|
|
<TR><TD >pre_force_respa</TD><TD > same as pre_force, but for rRESPA (optional)</TD></TR>
|
|
<TR><TD >post_force_respa</TD><TD > same as post_force, but for rRESPA (optional)</TD></TR>
|
|
<TR><TD >final_integrate_respa</TD><TD > same as final_integrate, but for rRESPA (optional)</TD></TR>
|
|
<TR><TD >min_pre_force</TD><TD > called after pair & molecular forces are computed in minimizer (optional)</TD></TR>
|
|
<TR><TD >min_post_force</TD><TD > called after pair & molecular forces are computed and communicated in minmizer (optional)</TD></TR>
|
|
<TR><TD >min_store</TD><TD > store extra data for linesearch based minimization on a LIFO stack (optional)</TD></TR>
|
|
<TR><TD >min_pushstore</TD><TD > push the minimization LIFO stack one element down (optional)</TD></TR>
|
|
<TR><TD >min_popstore</TD><TD > pop the minimization LIFO stack one element up (optional)</TD></TR>
|
|
<TR><TD >min_clearstore</TD><TD > clear minimization LIFO stack (optional)</TD></TR>
|
|
<TR><TD >min_step</TD><TD > reset or move forward on line search minimization (optional)</TD></TR>
|
|
<TR><TD >min_dof</TD><TD > report number of degrees of freedom <I>added</I> by this fix in minimization (optional)</TD></TR>
|
|
<TR><TD >max_alpha</TD><TD > report maximum allowed step size during linesearch minimization (optional)</TD></TR>
|
|
<TR><TD >pack_comm</TD><TD > pack a buffer to communicate a per-atom quantity (optional)</TD></TR>
|
|
<TR><TD >unpack_comm</TD><TD > unpack a buffer to communicate a per-atom quantity (optional)</TD></TR>
|
|
<TR><TD >pack_reverse_comm</TD><TD > pack a buffer to reverse communicate a per-atom quantity (optional)</TD></TR>
|
|
<TR><TD >unpack_reverse_comm</TD><TD > unpack a buffer to reverse communicate a per-atom quantity (optional)</TD></TR>
|
|
<TR><TD >dof</TD><TD > report number of degrees of freedom <I>removed</I> by this fix during MD (optional)</TD></TR>
|
|
<TR><TD >compute_scalar</TD><TD > return a global scalar property that the fix computes (optional)</TD></TR>
|
|
<TR><TD >compute_vector</TD><TD > return a component of a vector property that the fix computes (optional)</TD></TR>
|
|
<TR><TD >compute_array</TD><TD > return a component of an array property that the fix computes (optional)</TD></TR>
|
|
<TR><TD >deform</TD><TD > called when the box size is changed (optional)</TD></TR>
|
|
<TR><TD >reset_target</TD><TD > called when a change of the target temperature is requested during a run (optional)</TD></TR>
|
|
<TR><TD >reset_dt</TD><TD > is called when a change of the time step is requested during a run (optional)</TD></TR>
|
|
<TR><TD >modify_param</TD><TD > called when a fix_modify request is executed (optional)</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > report memory used by fix (optional)</TD></TR>
|
|
<TR><TD >thermo</TD><TD > compute quantities for thermodynamic output (optional)
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<P>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 (<I>nve</I>, <I>nvt</I>, <I>npt</I>) implement initial_integrate() and
|
|
final_integrate() to perform velocity Verlet updates. Fixes that
|
|
constrain forces implement post_force().
|
|
</P>
|
|
<P>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).
|
|
</P>
|
|
<P>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 <A HREF = "run_style.html">run_style</A>
|
|
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.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_7"></A><H4>10.7 Input script commands
|
|
</H4>
|
|
<P>New commands can be added to LAMMPS 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 LAMMPS input
|
|
script, LAMMPS 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 LAMMPS data structures.
|
|
</P>
|
|
<P>The single method your new class must define is as follows:
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >command</TD><TD > operations performed by the new command
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<P>Of course, the new class can define other methods and variables as
|
|
needed.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_8"></A><H4>10.8 Kspace computations
|
|
</H4>
|
|
<P>Classes that compute long-range Coulombic interactions via K-space
|
|
representations (Ewald, PPPM) are derived from the KSpace class. New
|
|
styles can be created to add new K-space options to LAMMPS.
|
|
</P>
|
|
<P>Ewald.cpp is an example of computing K-space interactions.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See kspace.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >init</TD><TD > initialize the calculation before a run</TD></TR>
|
|
<TR><TD >setup</TD><TD > computation before the 1st timestep of a run</TD></TR>
|
|
<TR><TD >compute</TD><TD > every-timestep computation</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > tally of memory usage
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_9"></A><H4>10.9 Minimization styles
|
|
</H4>
|
|
<P>Classes that perform energy minimization derived from the Min class.
|
|
New styles can be created to add new minimization algorithms to
|
|
LAMMPS.
|
|
</P>
|
|
<P>Min_cg.cpp is an example of conjugate gradient minimization.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See min.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >init</TD><TD > initialize the minimization before a run</TD></TR>
|
|
<TR><TD >run</TD><TD > perform the minimization</TD></TR>
|
|
<TR><TD >memory_usage</TD><TD > tally of memory usage
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_10"></A><H4>10.10 Pairwise potentials
|
|
</H4>
|
|
<P>Classes that compute pairwise interactions are derived from the Pair
|
|
class. In LAMMPS, 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
|
|
LAMMPS.
|
|
</P>
|
|
<P>Pair_lj_cut.cpp is a simple example of a Pair class, though it
|
|
includes some optional methods to enable its use with rRESPA.
|
|
</P>
|
|
<P>Here is a brief description of the class methods in pair.h:
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >compute</TD><TD > workhorse routine that computes pairwise interactions</TD></TR>
|
|
<TR><TD >settings</TD><TD > reads the input script line with arguments you define</TD></TR>
|
|
<TR><TD >coeff</TD><TD > set coefficients for one i,j type pair</TD></TR>
|
|
<TR><TD >init_one</TD><TD > perform initialization for one i,j type pair</TD></TR>
|
|
<TR><TD >init_style</TD><TD > initialization specific to this pair style</TD></TR>
|
|
<TR><TD >write & read_restart</TD><TD > write/read i,j pair coeffs to restart files</TD></TR>
|
|
<TR><TD >write & read_restart_settings</TD><TD > write/read global settings to restart files</TD></TR>
|
|
<TR><TD >single</TD><TD > force and energy of a single pairwise interaction between 2 atoms</TD></TR>
|
|
<TR><TD >compute_inner/middle/outer</TD><TD > versions of compute used by rRESPA
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<P>The inner/middle/outer routines are optional.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_11"></A><H4>10.11 Region styles
|
|
</H4>
|
|
<P>Classes that define geometric regions are derived from the Region
|
|
class. Regions are used elsewhere in LAMMPS 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 LAMMPS.
|
|
</P>
|
|
<P>Region_sphere.cpp is an example of a spherical region.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See region.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >match</TD><TD > determine whether a point is in the region
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_12"></A><H4>10.11 Body styles
|
|
</H4>
|
|
<P>Classes that define body particles are derived from the Body class.
|
|
Body particles can represent complex entities, such as surface meshes
|
|
of discrete points, collections of sub-particles, deformable objects,
|
|
etc.
|
|
</P>
|
|
<P>See <A HREF = "Section_howto.html#howto_14">Section_howto 14</A> of the manual for
|
|
an overview of using body particles and the <A HREF = "body.html">body</A> doc page
|
|
for details on the various body styles LAMMPS supports. New styles
|
|
can be created to add new kinds of body particles to LAMMPS.
|
|
</P>
|
|
<P>Body_nparticle.cpp is an example of a body particle that is treated as
|
|
a rigid body containing N sub-particles.
|
|
</P>
|
|
<P>Here is a brief description of methods you define in your new derived
|
|
class. See body.h for details.
|
|
</P>
|
|
<DIV ALIGN=center><TABLE BORDER=1 >
|
|
<TR><TD >data_body</TD><TD > process a line from the Bodies section of a data file</TD></TR>
|
|
<TR><TD >noutrow</TD><TD > number of sub-particles output is generated for</TD></TR>
|
|
<TR><TD >noutcol</TD><TD > number of values per-sub-particle output is generated for</TD></TR>
|
|
<TR><TD >output</TD><TD > output values for the Mth sub-particle</TD></TR>
|
|
<TR><TD >pack_comm_body</TD><TD > body attributes to communicate every timestep</TD></TR>
|
|
<TR><TD >unpack_comm_body</TD><TD > unpacking of those attributes</TD></TR>
|
|
<TR><TD >pack_border_body</TD><TD > body attributes to communicate when reneighboring is done</TD></TR>
|
|
<TR><TD >unpack_border_body</TD><TD > unpacking of those attributes
|
|
</TD></TR></TABLE></DIV>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_13"></A><H4>10.13 Thermodynamic output options
|
|
</H4>
|
|
<P>There is one class that computes and prints thermodynamic information
|
|
to the screen and log file; see the file thermo.cpp.
|
|
</P>
|
|
<P>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 <A HREF = "thermo_style.html">thermo_style</A> command for a list
|
|
of defined quantities.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>Note that the <A HREF = "thermo.html">thermo_style custom</A> command already allows
|
|
for thermo output of quantities calculated by <A HREF = "fix.html">fixes</A>,
|
|
<A HREF = "compute.html">computes</A>, and <A HREF = "variable.html">variables</A>. 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.
|
|
</P>
|
|
<HR>
|
|
|
|
<A NAME = "mod_14"></A><H4>10.14 Variable options
|
|
</H4>
|
|
<P>There is one class that computes and stores <A HREF = "variable.html">variable</A>
|
|
information in LAMMPS; see the file variable.cpp. The value
|
|
associated with a variable can be periodically printed to the screen
|
|
via the <A HREF = "print.html">print</A>, <A HREF = "fix_print.html">fix print</A>, or
|
|
<A HREF = "thermo_style.html">thermo_style custom</A> commands. Variables of style
|
|
"equal" can compute complex equations that involve the following types
|
|
of arguments:
|
|
</P>
|
|
<P>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<B>123</B>, y<B>3</B>, vx<B>34</B>, ...
|
|
compute values = c_mytemp<B>0</B>, c_thermo_press<B>3</B>, ...
|
|
</P>
|
|
<P>Adding keywords for the <A HREF = "thermo_style.html">thermo_style custom</A> command
|
|
(which can then be accessed by variables) was discussed
|
|
<A HREF = "Section_modify.html#thermo">here</A> on this page.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>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).
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<P>Adding new <A HREF = "compute.html">compute styles</A> (whose calculated values can
|
|
then be accessed by variables) was discussed
|
|
<A HREF = "Section_modify.html#compute">here</A> on this page.
|
|
</P>
|
|
<HR>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "mod_15"></A><H4>10.15 Submitting new features for inclusion in LAMMPS
|
|
</H4>
|
|
<P>We encourage users to submit new features that they add to LAMMPS to
|
|
<A HREF = "http://lammps.sandia.gov/authors.html">the developers</A>, 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 LAMMPS or as part
|
|
of a <A HREF = "Section_start.html#start_3">standard package</A>. Else we will add
|
|
them as a user-contributed package or file. Examples of user packages
|
|
are in src sub-directories that start with USER. The USER-MISC
|
|
package is simply a collection of (mostly) unrelated single files,
|
|
which is the simplest way to have your contribution quickly added to
|
|
the LAMMPS distribution. You can see a list of the both standard and
|
|
user packages by typing "make package" in the LAMMPS src directory.
|
|
</P>
|
|
<P>With user packages and files, all we are really providing (aside from
|
|
the fame and fortune that accompanies having your name in the source
|
|
code and on the <A HREF = "http://lammps.sandia.gov/authors.html">Authors page</A>
|
|
of the <A HREF = "http://lammps.sandia.gov">LAMMPS WWW site</A>), is a means for you to distribute your
|
|
work to the LAMMPS user community and a mechanism for others to easily
|
|
try out your new feature. This may help you find bugs or make contact
|
|
with new collaborators. Note that you're also implicitly agreeing to
|
|
support your code which means answer questions, fix bugs, and maintain
|
|
it if LAMMPS changes.
|
|
</P>
|
|
<P>The previous sections of this doc page describe how to add new
|
|
features of various kinds to LAMMPS. Packages are simply collections
|
|
of one or more new class files which are invoked as a new "style"
|
|
within a LAMMPS input script. If designed correctly, these additions
|
|
do not require changes to the main core of LAMMPS; they are simply
|
|
add-on files. If you think your new feature requires non-trivial
|
|
changes in core LAMMPS files, you'll need to <A HREF = "http://lammps.sandia.gov/authors.html">communicate with the
|
|
developers</A>, since we may or may
|
|
not want to make those changes. An example of a trivial change is
|
|
making a parent-class method "virtual" when you derive a new child
|
|
class from it.
|
|
</P>
|
|
<P>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.
|
|
</P>
|
|
<UL><LI>All source files you provide must compile with the most current
|
|
version of LAMMPS.
|
|
|
|
<LI>If your contribution is a single file (actually a *.cpp and *.h file)
|
|
it can most rapidly be added to the USER-MISC directory. Send us the
|
|
one-line entry to add to the USER-MISC/README file in that dir, along
|
|
with the 2 source files. You can do this multiple times if you wish
|
|
to contribute several individual features.
|
|
|
|
<LI>If your contribution is several related featues, it is probably best
|
|
to make it a user package directory with a name like USER-FOO. In
|
|
addition to your new files, the directory should contain a README, and
|
|
Install.csh file. The README text file should contain your name and
|
|
contact information and a brief description of what your new package
|
|
does. The Install.csh file enables LAMMPS to include and exclude your
|
|
package. See other README and Install.sh files in other USER
|
|
directories as examples. Send us a tarball of this USER-FOO
|
|
directory.
|
|
|
|
<LI>Your new source files need to have the LAMMPS copyright, GPL notice,
|
|
and your name at the top, like other LAMMPS source files. They need
|
|
to create a class that is inside the LAMMPS namespace. Other than
|
|
that, your files can do whatever is necessary to implement the new
|
|
features. They don't have to be written in the same stylistic format
|
|
and syntax as other LAMMPS files, though that would be nice.
|
|
|
|
<LI>Finally, you must also send a documentation file for each new command
|
|
or style you are adding to LAMMPS. 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 "Restrictions" section of the doc
|
|
page should indicate that your command is only available if LAMMPS is
|
|
built with the appropriate USER-MISC or USER-FOO package. See other
|
|
user package doc files for an example of how to do this. The txt2html
|
|
tool we use to do the conversion can be downloaded from <A HREF = "http://www.sandia.gov/~sjplimp/download.html">this
|
|
site</A>, so you can perform
|
|
the HTML conversion yourself to proofread your doc page.
|
|
</UL>
|
|
<P>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.
|
|
</P>
|
|
<HR>
|
|
|
|
<HR>
|
|
|
|
<A NAME = "Foo"></A>
|
|
|
|
<P><B>(Foo)</B> Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).
|
|
</P>
|
|
</HTML>
|