jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

This commit is contained in:
sjplimp 2014-05-15 21:20:05 +00:00
parent 65e0020948
commit bc3cd87496
2 changed files with 130 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
doc/Section_modify.html
View File

@ -635,48 +635,51 @@ then be accessed by variables) was discussed
<A NAME = "mod_15"></A><H4>10.15 Submitting new features for inclusion in LAMMPS <A NAME = "mod_15"></A><H4>10.15 Submitting new features for inclusion in LAMMPS
</H4> </H4>
<P>We encourage users to submit new features that they add to LAMMPS to <P>We encourage users to submit new features to <A HREF = "http://lammps.sandia.gov/authors.html">the
<A HREF = "http://lammps.sandia.gov/authors.html">the developers</A>, especially if developers</A> that they add to
you think the features will be of interest to other users. If they LAMMPS, especially if you think they will be of interest to other
are broadly useful we may add them as core files to LAMMPS or as part users. If they are broadly useful we may add them as core files to
of a <A HREF = "Section_start.html#start_3">standard package</A>. Else we will add LAMMPS or as part of a <A HREF = "Section_start.html#start_3">standard package</A>.
them as a user-contributed package or file. Examples of user packages Else we will add them as a user-contributed file or package. Examples
are in src sub-directories that start with USER. The USER-MISC of user packages are in src sub-directories that start with USER. The
package is simply a collection of (mostly) unrelated single files, USER-MISC package is simply a collection of (mostly) unrelated single
which is the simplest way to have your contribution quickly added to files, which is the simplest way to have your contribution quickly
the LAMMPS distribution. You can see a list of the both standard and added to the LAMMPS distribution. You can see a list of the both
user packages by typing "make package" in the LAMMPS src directory. standard and user packages by typing "make package" in the LAMMPS src
directory.
</P> </P>
<P>Note that by providing us the files to release you are agreeing to <P>Note that by providing us the files to release, you are agreeing to
make them open-source, i.e. that we can release them under the terms make them open-source, i.e. we can release them under the terms of the
of the GPL used as a license for the rest of LAMMPS. See <A HREF = "Section_intro.html#intro_4">Section GPL used as a license for the rest of LAMMPS. See <A HREF = "Section_intro.html#intro_4">Section
1.4</A> for details. 1.4</A> for details.
</P> </P>
<P>With user packages and files, all we are really providing (aside from <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 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> 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 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 work to the LAMMPS user community, and a mechanism for others to
try out your new feature. This may help you find bugs or make contact easily try out your new feature. This may help you find bugs or make
with new collaborators. Note that you're also implicitly agreeing to contact with new collaborators. Note that you're also implicitly
support your code which means answer questions, fix bugs, and maintain agreeing to support your code which means answer questions, fix bugs,
it if LAMMPS changes. and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).
</P> </P>
<P>The previous sections of this doc page describe how to add new <P>The previous sections of this doc page describe how to add new "style"
features of various kinds to LAMMPS. Packages are simply collections files of various kinds to LAMMPS. Packages are simply collections of
of one or more new class files which are invoked as a new "style" one or more new class files which are invoked as a new style within a
within a LAMMPS input script. If designed correctly, these additions LAMMPS input script. If designed correctly, these additions typically
typically do not require changes to the main core of LAMMPS; they are do not require changes to the main core of LAMMPS; they are simply
simply add-on files. If you think your new feature requires add-on files. If you think your new feature requires non-trivial
non-trivial changes in core LAMMPS files, you'll need to <A HREF = "http://lammps.sandia.gov/authors.html">communicate changes in core LAMMPS files, you'll need to <A HREF = "http://lammps.sandia.gov/authors.html">communicate with the
with the developers</A>, since we developers</A>, since we may or may
may or may not want to make those changes. An example of a trivial not want to make those changes. An example of a trivial change is
change is making a parent-class method "virtual" when you derive a new making a parent-class method "virtual" when you derive a new child
child class from it. class from it.
</P> </P>
<P>Here is what you need to do to submit a user package or single file <P>Here are the steps you need to follow to submit a single file or user
for our consideration. Following these steps will save time for both package for our consideration. Following these steps will save both
you and us. See existing package files for examples. you and us time. See existing files in packages in the src dir for
examples.
</P> </P>
<UL><LI>All source files you provide must compile with the most current <UL><LI>All source files you provide must compile with the most current
version of LAMMPS. version of LAMMPS.
@ -723,45 +726,47 @@ 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 single-file feature. For a package, it might be several files. These
are simple text files which we auto-convert to HTML. Thus they must are simple text files which we auto-convert to HTML. Thus they must
be in the same format as other *.txt files in the lammps/doc directory be in the same format as other *.txt files in the lammps/doc directory
for similar commands and styles. As appropriate, the text files can for similar commands and styles; use one or more of them as a starting
includelinks to equations (see doc/Eqs/*.tex for examples, we point. As appropriate, the text files can include links to equations
auto-create the associated JPG files), or figures (see doc/JPG for (see doc/Eqs/*.tex for examples, we auto-create the associated JPG
examples), or even additional PDF files with further details (see files), or figures (see doc/JPG for examples), or even additional PDF
doc/PDF for examples). The doc page should also include literature files with further details (see doc/PDF for examples). The doc page
citations; see the bottom of doc/fix_nh.txt for examples and the should also include literature citations as appropriate; see the
earlier part of the same file for examples of how to format the cite. bottom of doc/fix_nh.txt for examples and the earlier part of the same
The "Restrictions" section of the doc page should indicate that your file for how to format the cite itself. The "Restrictions" section of
command is only available if LAMMPS is built with the appropriate the doc page should indicate that your command is only available if
USER-MISC or USER-FOO package. See other user package doc files for LAMMPS is built with the appropriate USER-MISC or USER-FOO package.
an example of how to do this. The txt2html tool we use to do the See other user package doc files for examples of how to do this. The
conversion can be downloaded from <A HREF = "http://www.sandia.gov/~sjplimp/download.html">this txt2html tool we use to convert to HTML can be downloaded from <A HREF = "http://www.sandia.gov/~sjplimp/download.html">this
site</A>, so you can perform site</A>, so you can perform
the HTML conversion yourself to proofread your doc page. the HTML conversion yourself to proofread your doc page.
<LI>For a new package (or even a single command) you can include one or <LI>For a new package (or even a single command) you can include one or
more example scripts. These should run in no more than 1 minute, even more example scripts. These should run in no more than 1 minute, even
on a single processor, and not require large data files as input. See on a single processor, and not require large data files as input. See
directories under examples/USER for examples of user-provided input directories under examples/USER for examples of input scripts other
scripts for their packages. users provided for their packages.
<LI>If there is a paper of yours describing your feature (either the <LI>If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its implementation in algorithm/science behind the feature itself, or its initial usage, or
LAMMPS), you can add the citation to the *.cpp source file. See its implementation in LAMMPS), you can add the citation to the *.cpp
src/USER-EFF/atom_vec_electron.cpp for an example. A LaTeX citation source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
is stored in a variable at the top of the file and a single line of A LaTeX citation is stored in a variable at the top of the file and a
code that references the variable is added to the constructor of the single line of code that references the variable is added to the
class. This will cause LAMMPS to output the citation to a log.cite constructor of the class. Whenever a user invokes your feature from
file and issue a prompt to examine the file, whenever a user inovkes their input script, this will cause LAMMPS to output the citation to a
your feature from their input script. Note that you should only use log.cite file and prompt the user to examine the file. Note that you
this for a paper you or your group authored. Adding a cite in the should only use this for a paper you or your group authored.
code for a paper by Nose and Hoover if you write a fix that implements E.g. adding a cite in the code for a paper by Nose and Hoover if you
their integrator is not the intended usage. That kind of citation write a fix that implements their integrator is not the intended
should just be in the doc page you provide. usage. That kind of citation should just be in the doc page you
provide.
</UL> </UL>
<P>Finally, as a general rule-of-thumb, the more clear and <P>Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your doc and README files, and the easier self-explanatory you make your doc and README files, and the easier
you make it for people to get started, e.g. by providing example you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try your new feature. scripts, the more likely it is that users will try out your new
feature.
</P> </P>
<HR> <HR>

125
doc/Section_modify.txt
View File

@ -609,48 +609,51 @@ then be accessed by variables) was discussed
10.15 Submitting new features for inclusion in LAMMPS :link(mod_15),h4 10.15 Submitting new features for inclusion in LAMMPS :link(mod_15),h4
We encourage users to submit new features that they add to LAMMPS to We encourage users to submit new features to "the
"the developers"_http://lammps.sandia.gov/authors.html, especially if developers"_http://lammps.sandia.gov/authors.html that they add to
you think the features will be of interest to other users. If they LAMMPS, especially if you think they will be of interest to other
are broadly useful we may add them as core files to LAMMPS or as part users. If they are broadly useful we may add them as core files to
of a "standard package"_Section_start.html#start_3. Else we will add LAMMPS or as part of a "standard package"_Section_start.html#start_3.
them as a user-contributed package or file. Examples of user packages Else we will add them as a user-contributed file or package. Examples
are in src sub-directories that start with USER. The USER-MISC of user packages are in src sub-directories that start with USER. The
package is simply a collection of (mostly) unrelated single files, USER-MISC package is simply a collection of (mostly) unrelated single
which is the simplest way to have your contribution quickly added to files, which is the simplest way to have your contribution quickly
the LAMMPS distribution. You can see a list of the both standard and added to the LAMMPS distribution. You can see a list of the both
user packages by typing "make package" in the LAMMPS src directory. standard and user packages by typing "make package" in the LAMMPS src
directory.
Note that by providing us the files to release you are agreeing to Note that by providing us the files to release, you are agreeing to
make them open-source, i.e. that we can release them under the terms make them open-source, i.e. we can release them under the terms of the
of the GPL used as a license for the rest of LAMMPS. See "Section GPL used as a license for the rest of LAMMPS. See "Section
1.4"_Section_intro.html#intro_4 for details. 1.4"_Section_intro.html#intro_4 for details.
With user packages and files, all we are really providing (aside from With user packages and files, all we are really providing (aside from
the fame and fortune that accompanies having your name in the source the fame and fortune that accompanies having your name in the source
code and on the "Authors page"_http://lammps.sandia.gov/authors.html code and on the "Authors page"_http://lammps.sandia.gov/authors.html
of the "LAMMPS WWW site"_lws), is a means for you to distribute your of the "LAMMPS WWW site"_lws), is a means for you to distribute your
work to the LAMMPS user community and a mechanism for others to easily work to the LAMMPS user community, and a mechanism for others to
try out your new feature. This may help you find bugs or make contact easily try out your new feature. This may help you find bugs or make
with new collaborators. Note that you're also implicitly agreeing to contact with new collaborators. Note that you're also implicitly
support your code which means answer questions, fix bugs, and maintain agreeing to support your code which means answer questions, fix bugs,
it if LAMMPS changes. and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).
The previous sections of this doc page describe how to add new The previous sections of this doc page describe how to add new "style"
features of various kinds to LAMMPS. Packages are simply collections files of various kinds to LAMMPS. Packages are simply collections of
of one or more new class files which are invoked as a new "style" one or more new class files which are invoked as a new style within a
within a LAMMPS input script. If designed correctly, these additions LAMMPS input script. If designed correctly, these additions typically
typically do not require changes to the main core of LAMMPS; they are do not require changes to the main core of LAMMPS; they are simply
simply add-on files. If you think your new feature requires add-on files. If you think your new feature requires non-trivial
non-trivial changes in core LAMMPS files, you'll need to "communicate changes in core LAMMPS files, you'll need to "communicate with the
with the developers"_http://lammps.sandia.gov/authors.html, since we developers"_http://lammps.sandia.gov/authors.html, since we may or may
may or may not want to make those changes. An example of a trivial not want to make those changes. An example of a trivial change is
change is making a parent-class method "virtual" when you derive a new making a parent-class method "virtual" when you derive a new child
child class from it. class from it.
Here is what you need to do to submit a user package or single file Here are the steps you need to follow to submit a single file or user
for our consideration. Following these steps will save time for both package for our consideration. Following these steps will save both
you and us. See existing package files for examples. you and us time. See existing files in packages in the src dir for
examples.
All source files you provide must compile with the most current All source files you provide must compile with the most current
version of LAMMPS. :ulb,l version of LAMMPS. :ulb,l
@ -697,45 +700,47 @@ 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 single-file feature. For a package, it might be several files. These
are simple text files which we auto-convert to HTML. Thus they must are simple text files which we auto-convert to HTML. Thus they must
be in the same format as other *.txt files in the lammps/doc directory be in the same format as other *.txt files in the lammps/doc directory
for similar commands and styles. As appropriate, the text files can for similar commands and styles; use one or more of them as a starting
includelinks to equations (see doc/Eqs/*.tex for examples, we point. As appropriate, the text files can include links to equations
auto-create the associated JPG files), or figures (see doc/JPG for (see doc/Eqs/*.tex for examples, we auto-create the associated JPG
examples), or even additional PDF files with further details (see files), or figures (see doc/JPG for examples), or even additional PDF
doc/PDF for examples). The doc page should also include literature files with further details (see doc/PDF for examples). The doc page
citations; see the bottom of doc/fix_nh.txt for examples and the should also include literature citations as appropriate; see the
earlier part of the same file for examples of how to format the cite. bottom of doc/fix_nh.txt for examples and the earlier part of the same
The "Restrictions" section of the doc page should indicate that your file for how to format the cite itself. The "Restrictions" section of
command is only available if LAMMPS is built with the appropriate the doc page should indicate that your command is only available if
USER-MISC or USER-FOO package. See other user package doc files for LAMMPS is built with the appropriate USER-MISC or USER-FOO package.
an example of how to do this. The txt2html tool we use to do the See other user package doc files for examples of how to do this. The
conversion can be downloaded from "this txt2html tool we use to convert to HTML can be downloaded from "this
site"_http://www.sandia.gov/~sjplimp/download.html, so you can perform site"_http://www.sandia.gov/~sjplimp/download.html, so you can perform
the HTML conversion yourself to proofread your doc page. :l the HTML conversion yourself to proofread your doc page. :l
For a new package (or even a single command) you can include one or For a new package (or even a single command) you can include one or
more example scripts. These should run in no more than 1 minute, even more example scripts. These should run in no more than 1 minute, even
on a single processor, and not require large data files as input. See on a single processor, and not require large data files as input. See
directories under examples/USER for examples of user-provided input directories under examples/USER for examples of input scripts other
scripts for their packages. :l users provided for their packages. :l
If there is a paper of yours describing your feature (either the If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its implementation in algorithm/science behind the feature itself, or its initial usage, or
LAMMPS), you can add the citation to the *.cpp source file. See its implementation in LAMMPS), you can add the citation to the *.cpp
src/USER-EFF/atom_vec_electron.cpp for an example. A LaTeX citation source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
is stored in a variable at the top of the file and a single line of A LaTeX citation is stored in a variable at the top of the file and a
code that references the variable is added to the constructor of the single line of code that references the variable is added to the
class. This will cause LAMMPS to output the citation to a log.cite constructor of the class. Whenever a user invokes your feature from
file and issue a prompt to examine the file, whenever a user inovkes their input script, this will cause LAMMPS to output the citation to a
your feature from their input script. Note that you should only use log.cite file and prompt the user to examine the file. Note that you
this for a paper you or your group authored. Adding a cite in the should only use this for a paper you or your group authored.
code for a paper by Nose and Hoover if you write a fix that implements E.g. adding a cite in the code for a paper by Nose and Hoover if you
their integrator is not the intended usage. That kind of citation write a fix that implements their integrator is not the intended
should just be in the doc page you provide. :l,ule usage. That kind of citation should just be in the doc page you
provide. :l,ule
Finally, as a general rule-of-thumb, the more clear and Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your doc and README files, and the easier self-explanatory you make your doc and README files, and the easier
you make it for people to get started, e.g. by providing example you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try your new feature. scripts, the more likely it is that users will try out your new
feature.
:line :line
:line :line