From f28b6cf0e583633a786c6eef9c998bede96ba3cf Mon Sep 17 00:00:00 2001 From: sjplimp Date: Mon, 28 Mar 2016 15:09:29 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14792 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/_sources/compute_angle.txt | 60 +++++++ doc/_sources/compute_dihedral.txt | 59 +++++++ doc/_sources/compute_improper.txt | 59 +++++++ doc/_sources/pair_reax.txt | 18 ++- doc/_sources/pair_reax_c.txt | 12 +- doc/_sources/tutorial_github.txt | 256 ++++++++++++++++++++++++++++++ 6 files changed, 451 insertions(+), 13 deletions(-) create mode 100644 doc/_sources/compute_angle.txt create mode 100644 doc/_sources/compute_dihedral.txt create mode 100644 doc/_sources/compute_improper.txt create mode 100644 doc/_sources/tutorial_github.txt diff --git a/doc/_sources/compute_angle.txt b/doc/_sources/compute_angle.txt new file mode 100644 index 0000000000..91df79f906 --- /dev/null +++ b/doc/_sources/compute_angle.txt @@ -0,0 +1,60 @@ +.. index:: compute angle + +compute angle command +===================== + +Syntax +"""""" + +.. parsed-literal:: + + compute ID group-ID angle + +* ID, group-ID are documented in :doc:`compute ` command +* angle = style name of this compute command + +Examples +"""""""" + +.. parsed-literal:: + + compute 1 all angle + +Description +""""""""""" + +Define a computation that extracts the angle energy calculated by each +of the angle sub-styles used in the "angle_style +hybrid" angle_hybrid.html command. These values are made accessible +for output or further processing by other commands. The group +specified for this command is ignored. + +This compute is useful when using :doc:`angle_style hybrid ` if you want to know the portion of the total +energy contributed by one or more of the hybrid sub-styles. + +**Output info:** + +This compute calculates a global vector of length N where N is the +number of sub_styles defined by the :doc:`angle_style hybrid ` command, which can be accessed by indices +1-N. These values can be used by any command that uses global scalar +or vector values from a compute as input. See :ref:`this section ` for an overview of LAMMPS output +options. + +The vector values are "extensive" and will be in energy +:doc:`units `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`compute pe `, :doc:`compute pair ` + +**Default:** none + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Section_commands.html#comm diff --git a/doc/_sources/compute_dihedral.txt b/doc/_sources/compute_dihedral.txt new file mode 100644 index 0000000000..8c0281e409 --- /dev/null +++ b/doc/_sources/compute_dihedral.txt @@ -0,0 +1,59 @@ +.. index:: compute dihedral + +compute dihedral command +======================== + +Syntax +"""""" + +.. parsed-literal:: + + compute ID group-ID dihedral + +* ID, group-ID are documented in :doc:`compute ` command +* dihedral = style name of this compute command + +Examples +"""""""" + +.. parsed-literal:: + + compute 1 all dihedral + +Description +""""""""""" + +Define a computation that extracts the dihedral energy calculated by +each of the dihedral sub-styles used in the :doc:`dihedral_style hybrid ` command. These values are made +accessible for output or further processing by other commands. The +group specified for this command is ignored. + +This compute is useful when using :doc:`dihedral_style hybrid ` if you want to know the portion of the +total energy contributed by one or more of the hybrid sub-styles. + +**Output info:** + +This compute calculates a global vector of length N where N is the +number of sub_styles defined by the :doc:`dihedral_style hybrid ` command. which can be accessed by indices +1-N. These values can be used by any command that uses global scalar +or vector values from a compute as input. See :ref:`this section ` for an overview of LAMMPS output +options. + +The vector values are "extensive" and will be in energy +:doc:`units `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`compute pe `, :doc:`compute pair ` + +**Default:** none + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Section_commands.html#comm diff --git a/doc/_sources/compute_improper.txt b/doc/_sources/compute_improper.txt new file mode 100644 index 0000000000..ade78d6cb7 --- /dev/null +++ b/doc/_sources/compute_improper.txt @@ -0,0 +1,59 @@ +.. index:: compute improper + +compute improper command +======================== + +Syntax +"""""" + +.. parsed-literal:: + + compute ID group-ID improper + +* ID, group-ID are documented in :doc:`compute ` command +* improper = style name of this compute command + +Examples +"""""""" + +.. parsed-literal:: + + compute 1 all improper + +Description +""""""""""" + +Define a computation that extracts the improper energy calculated by +each of the improper sub-styles used in the :doc:`improper_style hybrid ` command. These values are made +accessible for output or further processing by other commands. The +group specified for this command is ignored. + +This compute is useful when using :doc:`improper_style hybrid ` if you want to know the portion of the +total energy contributed by one or more of the hybrid sub-styles. + +**Output info:** + +This compute calculates a global vector of length N where N is the +number of sub_styles defined by the :doc:`improper_style hybrid ` command. which can be accessed by indices +1-N. These values can be used by any command that uses global scalar +or vector values from a compute as input. See :ref:`this section ` for an overview of LAMMPS output +options. + +The vector values are "extensive" and will be in energy +:doc:`units `. + +Restrictions +"""""""""""" + none + +Related commands +"""""""""""""""" + +:doc:`compute pe `, :doc:`compute pair ` + +**Default:** none + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Section_commands.html#comm diff --git a/doc/_sources/pair_reax.txt b/doc/_sources/pair_reax.txt index 5f764d55d4..4ab6c3ad96 100644 --- a/doc/_sources/pair_reax.txt +++ b/doc/_sources/pair_reax.txt @@ -54,18 +54,18 @@ value other than "ffield.reax" will be rejected (see below). LAMMPS provides several different versions of ffield.reax in its potentials dir, each called potentials/ffield.reax.label. These are documented in potentials/README.reax. The default ffield.reax -contains parameterizations for the following elements: C, H, O, N, S. +contains parameterizations for the following elements: C, H, O, N. .. note:: We do not distribute a wide variety of ReaxFF force field files with LAMMPS. Adri van Duin's group at PSU is the central repository for this kind of data as they are continuously deriving and updating - parameterizations for different classes of materials. You can visit - their WWW site at - `http://www.engr.psu.edu/adri `_, register - as a "new user", and then submit a request to their group describing - material(s) you are interested in modeling with ReaxFF. They can tell + parameterizations for different classes of materials. You can submit + a contact request at the Materials Computation Center (MCC) website + `https://www.mri.psu.edu/materials-computation-center/connect-mcc `_, + describing the material(s) you are interested in modeling with ReaxFF. + They can tell you what is currently available or what it would take to create a suitable ReaxFF parameterization. @@ -86,7 +86,11 @@ be specified. Two examples using *pair_style reax* are provided in the examples/reax sub-directory, along with corresponding examples for -:doc:`pair_style reax/c `. +:doc:`pair_style reax/c `. Note that while the energy and force +calculated by both of these pair styles match very closely, the +contributions due to the valence angles differ slightly due to +the fact that with *pair_style reax/c* the default value of *thb_cutoff_sq* +is 0.00001, while for *pair_style reax* it is hard-coded to be 0.001. Use of this pair style requires that a charge be defined for every atom since the *reax* pair style performs a charge equilibration (QEq) diff --git a/doc/_sources/pair_reax_c.txt b/doc/_sources/pair_reax_c.txt index 8b28f476dd..4040f67287 100644 --- a/doc/_sources/pair_reax_c.txt +++ b/doc/_sources/pair_reax_c.txt @@ -55,7 +55,7 @@ a package. LAMMPS provides several different versions of ffield.reax in its potentials dir, each called potentials/ffield.reax.label. These are documented in potentials/README.reax. The default ffield.reax -contains parameterizations for the following elements: C, H, O, N, S. +contains parameterizations for the following elements: C, H, O, N. The format of these files is identical to that used originally by van Duin. We have tested the accuracy of *pair_style reax/c* potential @@ -69,11 +69,11 @@ tested). We do not distribute a wide variety of ReaxFF force field files with LAMMPS. Adri van Duin's group at PSU is the central repository for this kind of data as they are continuously deriving and updating - parameterizations for different classes of materials. You can visit - their WWW site at - `http://www.engr.psu.edu/adri `_, register - as a "new user", and then submit a request to their group describing - material(s) you are interested in modeling with ReaxFF. They can tell + parameterizations for different classes of materials. You can submit + a contact request at the Materials Computation Center (MCC) website + `https://www.mri.psu.edu/materials-computation-center/connect-mcc `_, + describing the material(s) you are interested in modeling with ReaxFF. + They can tell you what is currently available or what it would take to create a suitable ReaxFF parameterization. diff --git a/doc/_sources/tutorial_github.txt b/doc/_sources/tutorial_github.txt new file mode 100644 index 0000000000..d15403efeb --- /dev/null +++ b/doc/_sources/tutorial_github.txt @@ -0,0 +1,256 @@ +LAMMPS GitHub tutorial +###################### + +written by Stefan Paquay +======================== + + +---------- + + +This document briefly describes how to use GitHub to merge changes +into LAMMPS using GitHub. It assumes that you are familiar with +git. You may want to have a look at the `Git book `_ to reacquaint yourself. + + +---------- + + +Making an account +***************** + +First of all, you need a GitHub account. This is fairly simple, just +go to `GitHub `_ and create an account by clicking +the ``Sign up for GitHub'' button. Once your account is created, you +can sign in by clicking the button in the top left and filling in your +username or e-mail address and password. + + +---------- + + +Forking the repository +********************** + +To get changes into LAMMPS, you need to first fork the repository. At +the time of writing, LAMMPS-ICMS is the preferred fork. Go to `LAMMPS on GitHub `_ and make sure branch is +set to ``lammps-icms'', see the figure below. + +.. image:: JPG/tutorial_branch.png + :align: center + +Now, click on fork in the top right corner: + +.. image:: JPG/tutorial_fork.png + :align: center + +This will create your own fork of the LAMMPS repository. You can make +changes in this fork and later file *pull requests* to allow the +upstream repository to merge changes from your own fork into the one +we just forked from. At the same time, you can set things up, so you +can include changes from upstream into your repository. + + +---------- + + +Adding changes to your own fork +******************************* + +Before adding changes, it is better to first create a new branch that +will contain these changes, a so-called feature branch. + +Feature branches +================ + +Since LAMMPS is such a big project and most user contributions come in +small portions, the most ideal workflow for LAMMPS is the so-called +``Feature branch'' workflow. It is explained in great detail here: +`feature branch workflow `_. + +The idea is that every new feature for LAMMPS gets its own +branch. This way, it is fairly painless to incorporate new features +into the upstream repository. I will explain briefly here how to do +it. In this feature branch, I will add a USER-package. + +I assume that git is installed on the local machine and you know how +to use a command line. + +First of all, you need to clone your own fork of LAMMPS: + +.. parsed-literal:: + + $ git clone https://github.com//lammps.git + +You can find the proper url to the right of the "HTTPS" block, see figure. + +.. image:: JPG/tutorial_https_block.png + :align: center + +The above command copies (``clones'') the git repository to your local +machine. You can use this local clone to make changes and test them +without interfering with the repository on github. First, however, it +is recommended to make a new branch for a particular feature you would +like added to LAMMPS. In this example, I will try adding a new +USER-package called USER-MANIFOLD. + +To create a new branch, run the following git command in your repository: + +.. parsed-literal:: + + $ git checkout -b add-user-manifold + +The name of this new branch is "add-user-manifold" in my case. Just +name it after something that resembles the feature you want added to +LAMMPS. + +Now that you've changed branches, you can edit the files as you see +fit, add new files, and commit as much as you would like. Just +remember that if halfway you decide to add another, unrelated feature, +you should switch branches! + +After everything is done, add the files to the branch and commit them: + +.. parsed-literal:: + + $ git add src/USER-MANIFOLD examples/USER/manifold/ + $ git add doc/fix_nv*t,e*_manifold_rattle.txt + $ git add doc/fix_manifoldforce.txt doc/user_manifolds.txt + +After the files are added, the change should be comitted: + +.. parsed-literal:: + + $ git commit -m 'Added user-manifold package' + +The "-m" switch is used to add a message to the commit. Use this to +indicate what type of change was commited. + +Wisdom by Axel: +--------------- + +*"Do not use "git commit -a". the -a flag will automatically include +*all* modified or new files. mercurial does that and it find it +hugely annoying and often leading to accidental commits of files you +don't want. use git add, git rm, git mv for adding, removing, +renaming and then git commit to finalize the commit. personally, i +find it very convenient to use the bundled gui for commits, i.e. git +gui. typically, i will do git add and other operations, but then +verify and review them with git gui. git gui also allows to do +line-by-line unstaging and other convenient operations."* + +After the commit, the changes can be pushed to the same branch on GitHub: + +.. parsed-literal:: + + $ git push + +Git will ask you for your user name and password on GitHub if you have +not configured anything. If you correctly type your user name and +password, the change should be added to your fork on GitHub. + +If you want to make really sure you push to the right repository +(which is good practice), you can provide it explicitly: + +.. parsed-literal:: + + $ git push origin + +or using an explicit URL: + +.. parsed-literal:: + + $ git push git@github.com:Pakketeretet2/lammps.git + +After that, you can file a new pull request based on this +branch. GitHub will now look like this: + +.. image:: JPG/tutorial_pull_request_feature_branch1.png + :align: center + +Make sure that the current branch is set to the correct one, which, in +this case, is "add-user-manifold". Now click "New pull request". If +done correctly, the only changes you will see are those that were made +on this branch, so in my case, I will see nothing related to +$\mathrm*pair\_dzugatov*.$ + +This will open up a new window that lists changes made to the +repository. If you are just adding new files, there is not much to do, +but I suppose merge conflicts are to be resolved here if there are +changes in existing files. If all changes can automatically be merged, +green text at the top will say so and you can click the "Create pull +request" button, see image. + +.. image:: JPG/tutorial_pull_request2.png + :align: center + +After this you have to specify a short title and a comment with +details about your pull request. I guess here you write what your +modifications do and why they should be incorporated upstream. After +that, click the "Create pull request" button, see image below. + +.. image:: JPG/tutorial_pull_request3.png + :align: center + +Now just write some nice comments, click "Comment", and that is it. It +is now up to the maintainer(s) of the upstream repository to +incorporate the changes into the repository and to close the pull +request. + +.. image:: JPG/tutorial_pull_request4.png + :align: center + + +---------- + + +Additional changes +****************** + +Before the pull request is accepted, any additional changes you push +into your repository will automatically become part of the pull +request. + + +---------- + + +After a merge +************* + +When everything is fine the feature branch is merged into the LAMMPS +repositories: + +.. image:: JPG/tutorial_merged.png + :align: center + +Now one question remains: What to do with the feature branch that got +merged into upstream? + +It is in principle safe to delete them from your own fork. This helps +keep it a bit more tidy. Note that you first have to switch to another +branch! + +.. parsed-literal:: + + $ git checkout lammps-icms + $ git pull lammps-icms + $ git branch -d add-user-manifold + +If you do not pull first, it is not really a problem but git will warn +you at the next statement that you are deleting a local branch that +was not yet fully merged into HEAD. This is because git does not yet +know your branch just got merged into lammps-icms upstream. If you +first delete and then pull, everything should still be fine. + +Finally, if you delete the branch locally, you might want to push this +to your remote(s) as well: + +.. parsed-literal:: + + $ git push origin :add-user-manifold + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Section_commands.html#comm