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@14729 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2016-03-10 16:09:11 +00:00
parent 247bf33d63
commit 52f20bbbd5
6 changed files with 616 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/_sources/create_atoms.txt
View File

@ -36,9 +36,9 @@ Syntax
itype = atom type (1-N) to assign to this basis atom itype = atom type (1-N) to assign to this basis atom
*remap* value = *yes* or *no* *remap* value = *yes* or *no*
*var* value = name = variable name to evaluate for test of atom creation *var* value = name = variable name to evaluate for test of atom creation
*set* values = dim vname *set* values = dim name
dim = *x* or *y* or *z* dim = *x* or *y* or *z*
name = name of variable to set with x,y,z atom position name = name of variable to set with x, y, or z atom position
*rotate* values = Rx Ry Rz theta *rotate* values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees) theta = rotation angle for single molecule (degrees)
@ -203,16 +203,17 @@ box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to *no*, no remapping is done dimensions are periodic. If it is set to *no*, no remapping is done
and no particle is created if its position is outside the box. and no particle is created if its position is outside the box.
The *var* and *set* keywords can be used to provide a criterion for The *var* and *set* keywords can be used together to provide a
accepting or rejecting the addition of an individual atom, based on criterion for accepting or rejecting the addition of an individual
its coordinates. The *vname* specified for the *var* keyword is the atom, based on its coordinates. The *name* specified for the *var*
name of an :doc:`equal-style variable <variable>` which should evaluate keyword is the name of an :doc:`equal-style variable <variable>` which
to a zero or non-zero value based on one or two or three variables should evaluate to a zero or non-zero value based on one or two or
which will store the x, y, or z coordinates of an atom (one variable three variables which will store the x, y, or z coordinates of an atom
per coordinate). These other variables must be :doc:`equal-style variables <variable>` defined in the input script, but their (one variable per coordinate). If used, these other variables must be
formula can by anything. The *set* keyword is used to identify the :doc:`equal-style variables <variable>` defined in the input script, but
names of these other variables, one variable for the x-coordinate of a their formula can by anything. The *set* keyword is used to identify
created atom, one for y, and one for z. the names of these other variables, one variable for the x-coordinate
of a created atom, one for y, and one for z.
When an atom is created, its x, y, or z coordinates override the When an atom is created, its x, y, or z coordinates override the
formula for any *set* variable that is defined. The *var* variable is formula for any *set* variable that is defined. The *var* variable is

25
doc/create_atoms.html
View File

@ -159,9 +159,9 @@
itype = atom type (1-N) to assign to this basis atom itype = atom type (1-N) to assign to this basis atom
<em>remap</em> value = <em>yes</em> or <em>no</em> <em>remap</em> value = <em>yes</em> or <em>no</em>
<em>var</em> value = name = variable name to evaluate for test of atom creation <em>var</em> value = name = variable name to evaluate for test of atom creation
<em>set</em> values = dim vname <em>set</em> values = dim name
dim = <em>x</em> or <em>y</em> or <em>z</em> dim = <em>x</em> or <em>y</em> or <em>z</em>
name = name of variable to set with x,y,z atom position name = name of variable to set with x, y, or z atom position
<em>rotate</em> values = Rx Ry Rz theta <em>rotate</em> values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees) theta = rotation angle for single molecule (degrees)
@ -303,16 +303,17 @@ to <em>yes</em>, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to <em>no</em>, no remapping is done dimensions are periodic. If it is set to <em>no</em>, no remapping is done
and no particle is created if its position is outside the box.</p> and no particle is created if its position is outside the box.</p>
<p>The <em>var</em> and <em>set</em> keywords can be used to provide a criterion for <p>The <em>var</em> and <em>set</em> keywords can be used together to provide a
accepting or rejecting the addition of an individual atom, based on criterion for accepting or rejecting the addition of an individual
its coordinates. The <em>vname</em> specified for the <em>var</em> keyword is the atom, based on its coordinates. The <em>name</em> specified for the <em>var</em>
name of an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a> which should evaluate keyword is the name of an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a> which
to a zero or non-zero value based on one or two or three variables should evaluate to a zero or non-zero value based on one or two or
which will store the x, y, or z coordinates of an atom (one variable three variables which will store the x, y, or z coordinates of an atom
per coordinate). These other variables must be <a class="reference internal" href="variable.html"><em>equal-style variables</em></a> defined in the input script, but their (one variable per coordinate). If used, these other variables must be
formula can by anything. The <em>set</em> keyword is used to identify the <a class="reference internal" href="variable.html"><em>equal-style variables</em></a> defined in the input script, but
names of these other variables, one variable for the x-coordinate of a their formula can by anything. The <em>set</em> keyword is used to identify
created atom, one for y, and one for z.</p> the names of these other variables, one variable for the x-coordinate
of a created atom, one for y, and one for z.</p>
<p>When an atom is created, its x, y, or z coordinates override the <p>When an atom is created, its x, y, or z coordinates override the
formula for any <em>set</em> variable that is defined. The <em>var</em> variable is formula for any <em>set</em> variable that is defined. The <em>var</em> variable is
then evaluated. If the returned value is 0.0, the atom is not then evaluated. If the returned value is 0.0, the atom is not

26
doc/create_atoms.txt
View File

@ -33,9 +33,9 @@ keyword = {mol} or {basis} or {remap} or {var} or {set} or {units} :l
itype = atom type (1-N) to assign to this basis atom itype = atom type (1-N) to assign to this basis atom
{remap} value = {yes} or {no} {remap} value = {yes} or {no}
{var} value = name = variable name to evaluate for test of atom creation {var} value = name = variable name to evaluate for test of atom creation
{set} values = dim vname {set} values = dim name
dim = {x} or {y} or {z} dim = {x} or {y} or {z}
name = name of variable to set with x,y,z atom position name = name of variable to set with x, y, or z atom position
{rotate} values = Rx Ry Rz theta {rotate} values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees) theta = rotation angle for single molecule (degrees)
@ -188,17 +188,17 @@ box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to {no}, no remapping is done dimensions are periodic. If it is set to {no}, no remapping is done
and no particle is created if its position is outside the box. and no particle is created if its position is outside the box.
The {var} and {set} keywords can be used to provide a criterion for The {var} and {set} keywords can be used together to provide a
accepting or rejecting the addition of an individual atom, based on criterion for accepting or rejecting the addition of an individual
its coordinates. The {vname} specified for the {var} keyword is the atom, based on its coordinates. The {name} specified for the {var}
name of an "equal-style variable"_variable.html which should evaluate keyword is the name of an "equal-style variable"_variable.html which
to a zero or non-zero value based on one or two or three variables should evaluate to a zero or non-zero value based on one or two or
which will store the x, y, or z coordinates of an atom (one variable three variables which will store the x, y, or z coordinates of an atom
per coordinate). These other variables must be "equal-style (one variable per coordinate). If used, these other variables must be
variables"_variable.html defined in the input script, but their "equal-style variables"_variable.html defined in the input script, but
formula can by anything. The {set} keyword is used to identify the their formula can by anything. The {set} keyword is used to identify
names of these other variables, one variable for the x-coordinate of a the names of these other variables, one variable for the x-coordinate
created atom, one for y, and one for z. of a created atom, one for y, and one for z.
When an atom is created, its x, y, or z coordinates override the When an atom is created, its x, y, or z coordinates override the
formula for any {set} variable that is defined. The {var} variable is formula for any {set} variable that is defined. The {var} variable is

2
doc/searchindex.js
View File

File diff suppressed because one or more lines are too long

362
doc/tutorial_github.html Normal file
View File

@ -0,0 +1,362 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>LAMMPS GitHub tutorial &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li>LAMMPS GitHub tutorial</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="lammps-github-tutorial">
<h1>LAMMPS GitHub tutorial<a class="headerlink" href="#lammps-github-tutorial" title="Permalink to this headline"></a></h1>
<div class="section" id="stefan-paquay">
<h2>Stefan Paquay<a class="headerlink" href="#stefan-paquay" title="Permalink to this headline"></a></h2>
<hr class="docutils" />
<p>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 <a class="reference external" href="http://git-scm.com/book/">Git book</a> to reacquaint yourself.</p>
<hr class="docutils" />
<div class="section" id="making-an-account">
<h3>Making an account<a class="headerlink" href="#making-an-account" title="Permalink to this headline"></a></h3>
<p>First of all, you need a GitHub account. This is fairly simple, just
go to <a class="reference external" href="https://github.com">GitHub</a> and create an account by clicking
the <a href="#id1"><span class="problematic" id="id2">``</span></a>Sign up for GitHub&#8217;&#8217; 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.</p>
</div>
<hr class="docutils" />
<div class="section" id="forking-the-repository">
<h3>Forking the repository<a class="headerlink" href="#forking-the-repository" title="Permalink to this headline"></a></h3>
<p>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 <a class="reference external" href="https://github.com/lammps/lammps">LAMMPS on GitHub</a> and make sure branch is
set to <a href="#id3"><span class="problematic" id="id4">``</span></a>lammps-icms&#8217;&#8216;, see the figure below.</p>
<img alt="_images/tutorial_branch.png" class="align-center" src="_images/tutorial_branch.png" />
<p>Now, click on fork in the top right corner:</p>
<img alt="_images/tutorial_fork.png" class="align-center" src="_images/tutorial_fork.png" />
<p>This will create your own fork of the LAMMPS repository. You can make
changes in this fork and later file <em>pull requests</em> 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.</p>
</div>
<hr class="docutils" />
<div class="section" id="adding-changes-to-your-own-fork">
<h3>Adding changes to your own fork<a class="headerlink" href="#adding-changes-to-your-own-fork" title="Permalink to this headline"></a></h3>
<p>Before adding changes, it is better to first create a new branch that
will contain these changes, a so-called feature branch.</p>
</div>
</div>
<div class="section" id="feature-branches">
<h2>Feature branches<a class="headerlink" href="#feature-branches" title="Permalink to this headline"></a></h2>
<p>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
<a href="#id5"><span class="problematic" id="id6">``</span></a>Feature branch&#8217;&#8217; workflow. It is explained in great detail here:
<a class="reference external" href="https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow">feature branch workflow</a>.</p>
<p>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.</p>
<p>I assume that git is installed on the local machine and you know how
to use a command line.</p>
<p>First of all, you need to clone your own fork of LAMMPS:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git clone https://github.com/&lt;your user name&gt;/lammps.git
</pre></div>
</div>
<p>You can find the proper url to the right of the &#8220;HTTPS&#8221; block, see figure.</p>
<img alt="_images/tutorial_https_block.png" class="align-center" src="_images/tutorial_https_block.png" />
<p>The above command copies (<a href="#id7"><span class="problematic" id="id8">``</span></a>clones&#8217;&#8216;) 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.</p>
<p>To create a new branch, run the following git command in your repository:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git checkout -b add-user-manifold
</pre></div>
</div>
<p>The name of this new branch is &#8220;add-user-manifold&#8221; in my case. Just
name it after something that resembles the feature you want added to
LAMMPS.</p>
<p>Now that you&#8217;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!</p>
<p>After everything is done, add the files to the branch and commit them:</p>
<div class="highlight-python"><div class="highlight"><pre>$ 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
</pre></div>
</div>
<p>After the files are added, the change should be comitted:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git commit -m &#39;Added user-manifold package&#39;
</pre></div>
</div>
<p>The &#8220;-m&#8221; switch is used to add a message to the commit. Use this to
indicate what type of change was commited.</p>
<p><em>&#8220;Do not use &#8220;git commit -a&#8221;. the -a flag will automatically include
*all</em> modified or new files. mercurial does that and it find it
hugely annoying and often leading to accidental commits of files you
don&#8217;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.&#8221;*</p>
<p>After the commit, the changes can be pushed to the same branch on GitHub:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git push
</pre></div>
</div>
<p>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.</p>
<p>If you want to make really sure you push to the right repository
(which is good practice), you can provide it explicitly:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git push origin
</pre></div>
</div>
<p>or using an explicit URL:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git push git@github.com:Pakketeretet2/lammps.git
</pre></div>
</div>
<p>After that, you can file a new pull request based on this
branch. GitHub will now look like this:</p>
<img alt="_images/tutorial_pull_request_feature_branch1.png" class="align-center" src="_images/tutorial_pull_request_feature_branch1.png" />
<p>Make sure that the current branch is set to the correct one, which, in
this case, is &#8220;add-user-manifold&#8221;. Now click &#8220;New pull request&#8221;. 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*.$</p>
<p>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 &#8220;Create pull
request&#8221; button, see image.</p>
<img alt="_images/tutorial_pull_request2.png" class="align-center" src="_images/tutorial_pull_request2.png" />
<p>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 &#8220;Create pull request&#8221; button, see image below.</p>
<img alt="_images/tutorial_pull_request3.png" class="align-center" src="_images/tutorial_pull_request3.png" />
<p>Now just write some nice comments, click &#8220;Comment&#8221;, 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.</p>
<img alt="_images/tutorial_pull_request4.png" class="align-center" src="_images/tutorial_pull_request4.png" />
<hr class="docutils" />
<div class="section" id="additional-changes">
<h3>Additional changes<a class="headerlink" href="#additional-changes" title="Permalink to this headline"></a></h3>
<p>Before the pull request is accepted, any additional changes you push
into your repository will automatically become part of the pull
request.</p>
</div>
<hr class="docutils" />
<div class="section" id="after-a-merge">
<h3>After a merge<a class="headerlink" href="#after-a-merge" title="Permalink to this headline"></a></h3>
<p>When everything is fine the feature branch is merged into the LAMMPS
repositories:</p>
<img alt="_images/tutorial_merged.png" class="align-center" src="_images/tutorial_merged.png" />
<p>Now one question remains: What to do with the feature branch that got
merged into upstream?</p>
<p>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!</p>
<div class="highlight-python"><div class="highlight"><pre>$ git checkout lammps-icms
$ git pull lammps-icms
$ git branch -d add-user-manifold
</pre></div>
</div>
<p>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.</p>
<p>Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:</p>
<div class="highlight-python"><div class="highlight"><pre>$ git push origin :add-user-manifold
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013 Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>

214
doc/tutorial_github.txt Normal file
View File

@ -0,0 +1,214 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
LAMMPS GitHub tutorial :h1
Stefan Paquay :h3
:line
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"_http://git-scm.com/book/ to reacquaint yourself.
:line
Making an account :h2
First of all, you need a GitHub account. This is fairly simple, just
go to "GitHub"_https://github.com 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.
:line
Forking the repository :h2
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"_https://github.com/lammps/lammps and make sure branch is
set to ``lammps-icms'', see the figure below.
:c,image(JPG/tutorial_branch.png)
Now, click on fork in the top right corner:
:c,image(JPG/tutorial_fork.png)
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.
:line
Adding changes to your own fork :h2
Before adding changes, it is better to first create a new branch that
will contain these changes, a so-called feature branch.
Feature branches :h3
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"_https://www.atlassian.com/git/tutorials/comparing-workflows/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:
$ git clone https://github.com/<your user name>/lammps.git :pre
You can find the proper url to the right of the "HTTPS" block, see figure.
:c,image(JPG/tutorial_https_block.png)
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:
$ git checkout -b add-user-manifold :pre
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:
$ 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 :pre
After the files are added, the change should be comitted:
$ git commit -m 'Added user-manifold package' :pre
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: :h4
{"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:
$ git push :pre
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:
$ git push origin :pre
or using an explicit URL:
$ git push git@github.com:Pakketeretet2/lammps.git :pre
After that, you can file a new pull request based on this
branch. GitHub will now look like this:
:c,image(JPG/tutorial_pull_request_feature_branch1.png)
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.
:c,image(JPG/tutorial_pull_request2.png)
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.
:c,image(JPG/tutorial_pull_request3.png)
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.
:c,image(JPG/tutorial_pull_request4.png)
:line
Additional changes :h2
Before the pull request is accepted, any additional changes you push
into your repository will automatically become part of the pull
request.
:line
After a merge :h2
When everything is fine the feature branch is merged into the LAMMPS
repositories:
:c,image(JPG/tutorial_merged.png)
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!
$ git checkout lammps-icms
$ git pull lammps-icms
$ git branch -d add-user-manifold :pre
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:
$ git push origin :add-user-manifold :pre