forked from lijiext/lammps
git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14729 f3b2605a-c512-4ea7-a41b-209d697bcdaa
This commit is contained in:
sjplimp
parent
247bf33d63
commit
52f20bbbd5
|
|
@ -36,9 +36,9 @@ Syntax
|
|||
itype = atom type (1-N) to assign to this basis atom
|
||||
*remap* value = *yes* or *no*
|
||||
*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*
|
||||
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
|
||||
Rx,Ry,Rz = rotation vector for single molecule
|
||||
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
|
||||
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
|
||||
accepting or rejecting the addition of an individual atom, based on
|
||||
its coordinates. The *vname* specified for the *var* keyword is the
|
||||
name of an :doc:`equal-style variable <variable>` which should evaluate
|
||||
to a zero or non-zero value based on one or two or three variables
|
||||
which will store the x, y, or z coordinates of an atom (one variable
|
||||
per coordinate). These other variables must be :doc:`equal-style variables <variable>` defined in the input script, but their
|
||||
formula can by anything. The *set* keyword is used to identify the
|
||||
names of these other variables, one variable for the x-coordinate of a
|
||||
created atom, one for y, and one for z.
|
||||
The *var* and *set* keywords can be used together to provide a
|
||||
criterion for accepting or rejecting the addition of an individual
|
||||
atom, based on its coordinates. The *name* specified for the *var*
|
||||
keyword is the name of an :doc:`equal-style variable <variable>` which
|
||||
should evaluate to a zero or non-zero value based on one or two or
|
||||
three variables which will store the x, y, or z coordinates of an atom
|
||||
(one variable per coordinate). If used, these other variables must be
|
||||
:doc:`equal-style variables <variable>` defined in the input script, but
|
||||
their formula can by anything. The *set* keyword is used to identify
|
||||
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
|
||||
formula for any *set* variable that is defined. The *var* variable is
|
||||
|
|
|
|||
|
|
@ -159,9 +159,9 @@
|
|||
itype = atom type (1-N) to assign to this basis atom
|
||||
<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>set</em> values = dim vname
|
||||
<em>set</em> values = dim name
|
||||
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
|
||||
Rx,Ry,Rz = rotation vector for single molecule
|
||||
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
|
||||
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>
|
||||
<p>The <em>var</em> and <em>set</em> keywords can be used to provide a criterion for
|
||||
accepting or rejecting the addition of an individual atom, based on
|
||||
its coordinates. The <em>vname</em> specified for the <em>var</em> keyword is the
|
||||
name of an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a> which should evaluate
|
||||
to a zero or non-zero value based on one or two or three variables
|
||||
which will store the x, y, or z coordinates of an atom (one variable
|
||||
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
|
||||
formula can by anything. The <em>set</em> keyword is used to identify 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>The <em>var</em> and <em>set</em> keywords can be used together to provide a
|
||||
criterion for accepting or rejecting the addition of an individual
|
||||
atom, based on its coordinates. The <em>name</em> specified for the <em>var</em>
|
||||
keyword is the name of an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a> which
|
||||
should evaluate to a zero or non-zero value based on one or two or
|
||||
three variables which will store the x, y, or z coordinates of an atom
|
||||
(one variable per coordinate). If used, 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 formula can by anything. The <em>set</em> keyword is used to identify
|
||||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
{remap} value = {yes} or {no}
|
||||
{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}
|
||||
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
|
||||
Rx,Ry,Rz = rotation vector for single molecule
|
||||
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
|
||||
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
|
||||
accepting or rejecting the addition of an individual atom, based on
|
||||
its coordinates. The {vname} specified for the {var} keyword is the
|
||||
name of an "equal-style variable"_variable.html which should evaluate
|
||||
to a zero or non-zero value based on one or two or three variables
|
||||
which will store the x, y, or z coordinates of an atom (one variable
|
||||
per coordinate). These other variables must be "equal-style
|
||||
variables"_variable.html defined in the input script, but their
|
||||
formula can by anything. The {set} keyword is used to identify the
|
||||
names of these other variables, one variable for the x-coordinate of a
|
||||
created atom, one for y, and one for z.
|
||||
The {var} and {set} keywords can be used together to provide a
|
||||
criterion for accepting or rejecting the addition of an individual
|
||||
atom, based on its coordinates. The {name} specified for the {var}
|
||||
keyword is the name of an "equal-style variable"_variable.html which
|
||||
should evaluate to a zero or non-zero value based on one or two or
|
||||
three variables which will store the x, y, or z coordinates of an atom
|
||||
(one variable per coordinate). If used, these other variables must be
|
||||
"equal-style variables"_variable.html defined in the input script, but
|
||||
their formula can by anything. The {set} keyword is used to identify
|
||||
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
|
||||
formula for any {set} variable that is defined. The {var} variable is
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -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 — 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 & 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 & 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>
|
||||
|
||||
</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> »</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’’ 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’‘, 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’’ 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/<your user name>/lammps.git
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can find the proper url to the right of the “HTTPS” 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’‘) 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 “add-user-manifold” in my case. Just
|
||||
name it after something that resembles the feature you want added to
|
||||
LAMMPS.</p>
|
||||
<p>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!</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 'Added user-manifold package'
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The “-m” switch is used to add a message to the commit. Use this to
|
||||
indicate what type of change was commited.</p>
|
||||
<p><em>“Do not use “git commit -a”. 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’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.”*</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 “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*.$</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 “Create pull
|
||||
request” 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 “Create pull request” 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 “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.</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>
|
||||
© 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>
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue