diff --git a/doc/Section_commands.html b/doc/Section_commands.html index 64a1b05bd8..ecca1808a8 100644 --- a/doc/Section_commands.html +++ b/doc/Section_commands.html @@ -435,7 +435,7 @@ description: LAMMPS is built with the appropriate package.

-
ewald/n +
ewald/n
diff --git a/doc/Section_errors.html b/doc/Section_errors.html index 0487e1f4e9..0333f3034f 100644 --- a/doc/Section_errors.html +++ b/doc/Section_errors.html @@ -110,7 +110,7 @@ request your input script and data files if necessary.

-

9.3 Error & warning Messages +

9.3 Error & warning messages

These are two alphabetic lists of the ERROR and WARNING messages LAMMPS prints out and the reason why. If the @@ -120,6 +120,11 @@ the error message and staring at the source code and comments is also not a bad idea! Note that sometimes the same message can be printed from multiple places in the code.

+

Also note that error messages from user-contributed +packages are not listed here. Is such an +error occurs and is not self-explanatory, you'll need to look in the +source code or contact the author of the package. +

Errors:

diff --git a/doc/Section_errors.txt b/doc/Section_errors.txt index b5e0f35452..6422a655bc 100644 --- a/doc/Section_errors.txt +++ b/doc/Section_errors.txt @@ -107,7 +107,7 @@ request your input script and data files if necessary. :line -9.3 Error & warning Messages :h4,link(9_3) +9.3 Error & warning messages :h4,link(9_3) These are two alphabetic lists of the "ERROR"_#error and "WARNING"_#warn messages LAMMPS prints out and the reason why. If the @@ -117,6 +117,11 @@ the error message and staring at the source code and comments is also not a bad idea! Note that sometimes the same message can be printed from multiple places in the code. +Also note that error messages from "user-contributed +packages"_Section_start.html#2_3 are not listed here. Is such an +error occurs and is not self-explanatory, you'll need to look in the +source code or contact the author of the package. + Errors: :h4,link(error) :dlb diff --git a/doc/Section_modify.html b/doc/Section_modify.html index 55b1fe14fd..49e70b95bd 100644 --- a/doc/Section_modify.html +++ b/doc/Section_modify.html @@ -18,13 +18,19 @@ extend with new functionality. In fact, about 75% if its source code is files added in this fashion.

In this section, changes and additions users can make are listed along -with minimal instructions. 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). +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 +below. +

+

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).

Most of the new features described in this section require you to write a new C++ derived class (except for exceptions described below, @@ -74,18 +80,25 @@ 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.

-

Here is a list of the new features that can be added in this way: +

Here is a list of the new features that can be added in this way, +along with information about how to submit your features for inclusion +in the LAMMPS distribution.

+

As illustrated by the pairwise example, these options are referred to in the LAMMPS documentation as the "style" of a particular command. @@ -513,6 +526,70 @@ then be accessed by variables) was discussed

+

Submitting new features to the developers to include in LAMMPS +

+

We encourage users to submit new features that they add to LAMMPS to +the developers, especially if +you think they will be useful to other users. If they are broadly +useful we may add them as core files to LAMMPS or as part of a +standard package. Else we will add them as a +user-contributed package. Examples of user packages are in src +sub-directories that start with USER. You can see a list of the both +standard and user packages by typing "make package" in the LAMMPS src +directory. +

+

With user packages, all we are really providing (aside from the fame +and fortune that accompanies having your name in the source code and +on the Authors page of the +LAMMPS WWW site), 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. +

+

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 does requires changes in +other LAMMPS files, you'll need to communicate with the +developers, since we may or may +not want to make those changes. +

+

Here is what you need to do to submit a user package for our +consideration. Following these steps will save time for both you and +us. See existing package files for examples of these details. +

+

Your user package will be a directory with a name like USER-FOO. In +addition to your new files, the directory should contain a README, +Install.csh and style_user_foo.h file. +

+

The README text file should contain your name and contact information +and a brief description of what your new package does. This is for +users to look at. +

+

The Install.csh and style_user_foo.h files enable LAMMPS to include +and exclude your package. +

+

Your new source files need to have the LAMMPS copyright, GPL notice, +and your name at the top. 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 style and syntax as other LAMMPS files, thought +that would be nice. +

+

Finally, you also need to send us a documentation file for each new +command or style you are adding to LAMMPS. These are text files which +we will convert to HTML. Use one of the *.txt files in the doc dir as +a starting point for the new file you create, since it should look +similar to the doc files for existing commands and styles. Note that +the more clear and self-exaplantory you make your documentation, the +more likely it is that users will try out your new feature. +

+
+
diff --git a/doc/Section_modify.txt b/doc/Section_modify.txt index 68eac5d0fc..fe3f361271 100644 --- a/doc/Section_modify.txt +++ b/doc/Section_modify.txt @@ -15,13 +15,19 @@ extend with new functionality. In fact, about 75% if its source code is files added in this fashion. In this section, changes and additions users can make are listed along -with minimal instructions. 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). +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 +"below"_#package. + +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). Most of the new features described in this section require you to write a new C++ derived class (except for exceptions described below, @@ -71,12 +77,15 @@ 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. -Here is a list of the new features that can be added in this way: +Here is a list of the new features that can be added in this way, +along with information about how to submit your features for inclusion +in the LAMMPS distribution. "Atom styles"_#atom "Bond, angle, dihedral, improper potentials"_#bond "Compute styles"_#compute "Dump styles"_#dump +"Dump custom output optoins"_#dump "Fix styles"_#fix which include integrators, \ temperature and pressure control, force constraints, \ boundary conditions, diagnostic output, etc @@ -84,7 +93,11 @@ Here is a list of the new features that can be added in this way: "Kspace computations"_#kspace "Minimization solvers"_#min "Pairwise potentials"_#pair -"Region styles"_#region :ul +"Region styles"_#region +"Thermodynamic output options"_#thermo +"Variable options"_#variable :ul + +"Submitting new features to the developers to include in LAMMPS"_#package :ul As illustrated by the pairwise example, these options are referred to in the LAMMPS documentation as the "style" of a particular command. @@ -488,6 +501,70 @@ Adding new "compute styles"_compute.html (whose calculated values can then be accessed by variables) was discussed "here"_Section_modify.html#compute on this page. +:line + +Submitting new features to the developers to include in LAMMPS :link(package),h4 + +We encourage users to submit new features that they add to LAMMPS to +"the developers"_http://lammps.sandia.gov/authors.html, especially if +you think they will be useful to other users. If they are broadly +useful we may add them as core files to LAMMPS or as part of a +"standard package"_Section_start.html#2_3. Else we will add them as a +user-contributed package. Examples of user packages are in src +sub-directories that start with USER. You can see a list of the both +standard and user packages by typing "make package" in the LAMMPS src +directory. + +With user packages, all we are really providing (aside from the fame +and fortune that accompanies having your name in the source 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 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. + +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 does requires changes in +other LAMMPS files, you'll need to "communicate with the +developers"_http://lammps.sandia.gov/authors.html, since we may or may +not want to make those changes. + +Here is what you need to do to submit a user package for our +consideration. Following these steps will save time for both you and +us. See existing package files for examples of these details. + +Your user package will be a directory with a name like USER-FOO. In +addition to your new files, the directory should contain a README, +Install.csh and style_user_foo.h file. + +The README text file should contain your name and contact information +and a brief description of what your new package does. This is for +users to look at. + +The Install.csh and style_user_foo.h files enable LAMMPS to include +and exclude your package. + +Your new source files need to have the LAMMPS copyright, GPL notice, +and your name at the top. 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 style and syntax as other LAMMPS files, thought +that would be nice. + +Finally, you also need to send us a documentation file for each new +command or style you are adding to LAMMPS. These are text files which +we will convert to HTML. Use one of the *.txt files in the doc dir as +a starting point for the new file you create, since it should look +similar to the doc files for existing commands and styles. Note that +the more clear and self-exaplantory you make your documentation, the +more likely it is that users will try out your new feature. + :line :line diff --git a/doc/Section_start.html b/doc/Section_start.html index ef237a45bd..726bd63894 100644 --- a/doc/Section_start.html +++ b/doc/Section_start.html @@ -269,11 +269,11 @@ instructions for tips. Good luck - we can't help you on this one.

2.3 Making LAMMPS with optional packages

The source code for LAMMPS is structured as a large set of core files -that are always used plus additional optional packages, which are -groups of files that enable a specific set of features. For example, -force fields for molecular systems or granular systems are in -packages. You can see the list of both standard and user-contributed -packages by typing "make package". +which are always used, plus optional packages, which are groups of +files that enable a specific set of features. For example, force +fields for molecular systems or granular systems are in packages. You +can see the list of both standard and user-contributed packages by +typing "make package".

The current list of standard packages is as follows:

@@ -294,8 +294,8 @@ packages by typing "make package".

There are also user-contributed packages which may be as simple as a -single additional file (class) or many files grouped together which -add a specific functionality to the code. The difference between a +single additional file or many files grouped together which add a +specific functionality to the code. The difference between a standard package versus a user package is as follows.

Standard packages are supported by the LAMMPS developers and are @@ -305,49 +305,10 @@ necessary, and keep them compatible with future changes to LAMMPS.

User packages don't necessarily meet these requirements. If you have problems using a feature provided in a user package, you will likely -need to contact the contributor directly to get help. -

-

We encourage users to submit new features to the -developers that they add to -LAMMPS, especially if you think they will be useful to other users. -If they are broadly useful and meet the requirements listed above, we -may add them as core files to LAMMPS or as part of a standard package. -Else we will add them as a user package. -

-

With user packages, all we are really providing (aside from the fame -and fortune that accompanies having your name in the source code and -on the Authors page of the -LAMMPS WWW site), 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. -

-

This section of the documentation describes how -to add new features of various kinds to LAMMPS. Packages are simply -collections of these kinds of new class files which are typically -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 something else in LAMMPS to change, you'll need to -communicate with the -developers. -

-

Examples of user-contributed packages are in src sub-directories that -start with USER. We impose only a few minor restrictions on the -source files you submit. They need to have the LAMMPS copyright, GPL -notice, and your name at the top. They need to create a class that is -inside the LAMMPS namespace. You need to provide the Install.csh and -style*.h files that enable the package to be installed/un-installed. -See any of the other LAMMPS source or package files for examples. -Following this pattern will save you and us time when you submit the -files. -

-

Finally, you also need to include a README file with your package, so -that other users can get a quick idea of what it does and know how to -contact you. You also need to include a doc file in text format for -each of the new styles you are adding, which we will convert to HTML. -See the doc directory for numerous examples of these *.txt files; you -should use one of them as a template for the feature you are adding. +need to contact the contributor directly to get help. Information on +how to submit additions you make to LAMMPS as a user-contributed +package is given in this section of the +documentation.

diff --git a/doc/Section_start.txt b/doc/Section_start.txt index 010f40568e..3c508789d4 100644 --- a/doc/Section_start.txt +++ b/doc/Section_start.txt @@ -264,11 +264,11 @@ instructions for tips. Good luck - we can't help you on this one. 2.3 Making LAMMPS with optional packages :h4,link(2_3) The source code for LAMMPS is structured as a large set of core files -that are always used plus additional optional packages, which are -groups of files that enable a specific set of features. For example, -force fields for molecular systems or granular systems are in -packages. You can see the list of both standard and user-contributed -packages by typing "make package". +which are always used, plus optional packages, which are groups of +files that enable a specific set of features. For example, force +fields for molecular systems or granular systems are in packages. You +can see the list of both standard and user-contributed packages by +typing "make package". The current list of standard packages is as follows: @@ -287,8 +287,8 @@ poems : coupled rigid body motion xtc : dump atom snapshots in XTC format :tb(s=:) There are also user-contributed packages which may be as simple as a -single additional file (class) or many files grouped together which -add a specific functionality to the code. The difference between a +single additional file or many files grouped together which add a +specific functionality to the code. The difference between a {standard} package versus a {user} package is as follows. Standard packages are supported by the LAMMPS developers and are @@ -298,49 +298,10 @@ necessary, and keep them compatible with future changes to LAMMPS. User packages don't necessarily meet these requirements. If you have problems using a feature provided in a user package, you will likely -need to contact the contributor directly to get help. - -We encourage users to submit new features to "the -developers"_http://lammps.sandia.gov/authors.html that they add to -LAMMPS, especially if you think they will be useful to other users. -If they are broadly useful and meet the requirements listed above, we -may add them as core files to LAMMPS or as part of a standard package. -Else we will add them as a user package. - -With user packages, all we are really providing (aside from the fame -and fortune that accompanies having your name in the source 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 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. - -"This section"_Section_modify.html of the documentation describes how -to add new features of various kinds to LAMMPS. Packages are simply -collections of these kinds of new class files which are typically -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 something else in LAMMPS to change, you'll need to -"communicate with the -developers"_http://lammps.sandia.gov/authors.html. - -Examples of user-contributed packages are in src sub-directories that -start with USER. We impose only a few minor restrictions on the -source files you submit. They need to have the LAMMPS copyright, GPL -notice, and your name at the top. They need to create a class that is -inside the LAMMPS namespace. You need to provide the Install.csh and -style*.h files that enable the package to be installed/un-installed. -See any of the other LAMMPS source or package files for examples. -Following this pattern will save you and us time when you submit the -files. - -Finally, you also need to include a README file with your package, so -that other users can get a quick idea of what it does and know how to -contact you. You also need to include a doc file in text format for -each of the new styles you are adding, which we will convert to HTML. -See the doc directory for numerous examples of these *.txt files; you -should use one of them as a template for the feature you are adding. +need to contact the contributor directly to get help. Information on +how to submit additions you make to LAMMPS as a user-contributed +package is given in "this section"_Section_modify.html#package of the +documentation. :line diff --git a/doc/kspace_style.html b/doc/kspace_style.html index 96d9020de1..63b2ae7b91 100644 --- a/doc/kspace_style.html +++ b/doc/kspace_style.html @@ -15,7 +15,7 @@ 

kspace_style style value
-