Merge pull request #1762 from rbberger/doc_lammps_lexer

Thus this sequence of commands:

.. parsed-literal::

.. code-block:: LAMMPS

   timestep 0.5

   run      100

does something different than this sequence:

.. parsed-literal::

.. code-block:: LAMMPS

   run      100

   timestep 0.5

continuing on the next line.  Also note that for multi-line commands a

single leading "#" will comment out the entire command.

.. code-block:: LAMMPS

   # this is a comment

(3) The line is searched repeatedly for $ characters, which indicate

variables that are replaced with a text string.  See an exception in

(6).

them to variable names.  For example, these 3 input script lines:

.. parsed-literal::

.. code-block:: LAMMPS

   variable X equal (xlo+xhi)/2+sqrt(v_area)

   region 1 block $X 2 INF INF EDGE EDGE

can be replaced by

.. parsed-literal::

.. code-block:: LAMMPS

   region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

This can be useful for formatting print output to a desired precision:

.. parsed-literal::

.. code-block:: LAMMPS

   print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"

Thus you cannot do this:

.. parsed-literal::

.. code-block:: LAMMPS

   variable        a equal 2

   variable        b2 equal 4

needed.  For example:

.. parsed-literal::

.. code-block:: LAMMPS

   print "Volume = $v"

   print 'Volume = $v'

Step 1a: For the CMake based build system, the steps are:

.. parsed-literal::

.. code-block:: bash

   mkdir $LAMMPS_DIR/build-shared

   cd  $LAMMPS_DIR/build-shared

Step 1b: For the legacy, make based build system, the steps are:

.. parsed-literal::

.. code-block:: bash

   cd $LAMMPS_DIR/src

that package into your current Python installation with:

.. parsed-literal::

.. code-block:: bash

   make install-python

**Prerequisite (e.g. on Ubuntu)**

.. parsed-literal::

.. code-block:: bash

   apt-get install python-virtualenv

"""""""""""""""""""""""""""""""""""""""""""

.. parsed-literal::

.. code-block:: bash

   # create virtualenv named 'testing'

   virtualenv $HOME/python/testing

to the location in the virtual environment with:

.. parsed-literal::

.. code-block:: bash

   cmake . -DPYTHON_EXECUTABLE=$(which python)

module. By using the default constructor, a new *lammps* instance is created.

.. parsed-literal::

.. code-block:: Python

   from lammps import PyLammps

   L = PyLammps()

You can also initialize PyLammps on top of this existing *lammps* object:

.. parsed-literal::

.. code-block:: Python

   from lammps import lammps, PyLammps

   lmp = lammps()

For instance, let's take the following LAMMPS command:

.. parsed-literal::

.. code-block:: LAMMPS

   region box block 0 10 0 5 -0.5 0.5

Python code if *L* was a lammps instance:

.. parsed-literal::

.. code-block:: Python

   L.command("region box block 0 10 0 5 -0.5 0.5")

separated by white-space, passed as individual arguments to a region method.

.. parsed-literal::

.. code-block:: Python

   L.region("box block", 0, 10, 0, 5, -0.5, 0.5)

manually by creating formatted strings.

.. parsed-literal::

.. code-block:: Python

   L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))

them automatically to a final command string.

.. parsed-literal::

.. code-block:: Python

   L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)

To define a variable you can use the :doc:`variable <variable>` command:

.. parsed-literal::

.. code-block:: Python

   L.variable("a index 2")

L.variables dictionary by name

.. parsed-literal::

.. code-block:: Python

   a = L.variables['a']

property of this object.

.. parsed-literal::

.. code-block:: Python

   print(a.value)

   a.value = 4

variables, compute or fix data.

.. parsed-literal::

.. code-block:: Python

   result = L.eval("ke") # kinetic energy

   result = L.eval("pe") # potential energy

position, velocity, force, etc.).

.. parsed-literal::

.. code-block:: Python

   # access first atom

   L.atoms[0].id

Some properties can also be used to set:

.. parsed-literal::

.. code-block:: Python

   # set position in 2D simulation

   L.atoms[0].position = (1.0, 0.0)

the second run.

.. parsed-literal::

.. code-block:: Python

   L.run(1000)

   L.runs[0] # data of first 1000 time steps

accessible through its thermo name:

.. parsed-literal::

.. code-block:: Python

   L.runs[0].step # list of time steps in first run

   L.runs[0].ke   # list of kinetic energy values in first run

import matplotlib.plot as plt

.. parsed-literal::

.. code-block:: Python

   steps = L.runs[0].step

   ke    = L.runs[0].ke

Python environment (this assumes you followed the Quick Start instructions):

.. parsed-literal::

.. code-block:: bash

   jupyter notebook

setting its position from Python, which changes the dihedral angle.

.. parsed-literal::

.. code-block:: Python

   phi = [d \* math.pi / 180 for d in range(360)]

It is then disordered by moving each atom by a random delta.

.. parsed-literal::

.. code-block:: Python

   random.seed(27848)

   deltaperturb = 0.2

moves random atoms by a random delta and only accepts certain moves.

.. parsed-literal::

.. code-block:: Python

   estart = L.eval("pe")

   elast = estart

PyLammps can be run in parallel using mpi4py. This python package can be installed using

.. parsed-literal::

.. code-block:: bash

   pip install mpi4py

executes it in parallel.  You can find in.melt in the examples/melt folder.

.. parsed-literal::

.. code-block:: Python

   from mpi4py import MPI

   from lammps import PyLammps

following mpirun command:

.. parsed-literal::

.. code-block:: bash

   mpirun -np 4 python melt.py

If you downloaded LAMMPS from the public SVN or Git repositories, then

the HTML and PDF files are not included.  Instead you need to create

them, in one of three ways:

them, in one of two ways:

(a) You can "fetch" the current HTML and PDF files from the LAMMPS web

site.  Just type "make fetch".  This should create a html\_www dir and

Manual\_www.pdf/Developer\_www.pdf files.  Note that if new LAMMPS

features have been added more recently than the date of your version,

the fetched documentation will include those changes (but your source

code will not, unless you update your local repository).

a. You can "fetch" the current HTML and PDF files from the LAMMPS web site.

   Just type "make fetch".  This should create a html\_www dir and

   Manual\_www.pdf/Developer\_www.pdf files.  Note that if new LAMMPS features

   have been added more recently than the date of your version, the fetched

   documentation will include those changes (but your source code will not, unless

   you update your local repository).

(b) You can build the HTML and PDF files yourself, by typing "make

b. You can build the HTML and PDF files yourself, by typing "make

   html" followed by "make pdf".  Note that the PDF make requires the

   HTML files already exist.  This requires various tools including

   Sphinx, which the build process will attempt to download and install

   on your system, if not already available.  See more details below.

(c) You can generate an older, simpler, less-fancy style of HTML

documentation by typing "make old".  This will create an "old"

directory.  This can be useful if (b) does not work on your box for

some reason, or you want to quickly view the HTML version of a doc

page you have created or edited yourself within the src directory.

E.g. if you are planning to submit a new feature to LAMMPS.

----------

the doc dir.

.. parsed-literal::

.. code-block:: bash

   Documentation Build Options:

   make html         # generate HTML in html dir using Sphinx

   make pdf          # generate 2 PDF files (Manual.pdf,Developer.pdf)

                     #   in doc dir via htmldoc and pdflatex

   make old          # generate old-style HTML pages in old dir via txt2html

   make fetch        # fetch HTML doc pages and 2 PDF files from web site

                     #   as a tarball and unpack into html dir and 2 PDFs

   make epub         # generate LAMMPS.epub in ePUB format using Sphinx

------

.. parsed-literal::

.. code-block:: bash

   sudo apt-get install python-virtualenv

------------------------------------------------------------------------------------

.. parsed-literal::

.. code-block:: bash

   sudo yum install python3-virtualenv

-------------------------

.. parsed-literal::

.. code-block:: bash

   sudo dnf install python3-virtualenv

Once Python 3 is installed, open a Terminal and type

.. parsed-literal::

.. code-block:: bash

   pip3 install virtualenv

----------

Installing prerequisites for PDF build

Building the PDF manual requires a working C++ compiler (to

compile the txt2html tool and a working installation of

`HTMLDOC <https://www.msweet.org/htmldoc/>`_

HTMLDOC has its own list of prerequisites, but in most cases

you can install a binary package of it either through your

Linux package manager or MacOS (dmg) and Windows installer

(msi) packages from its

`GitHub releases page at <https://github.com/michaelrsweet/htmldoc/releases>`_

----------

Installing prerequisites for epub build

=======================================

"Higher level section"_Commands.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

LAMMPS input scripts :h3

LAMMPS executes by reading commands from a input script (text file),

one line at a time.  When the input script ends, LAMMPS exits.  Each

command causes LAMMPS to take some action.  It may set an internal

variable, read in a file, or run a simulation.  Most commands have

default settings, which means you only need to use the command if you

wish to change the default.

In many cases, the ordering of commands in an input script is not

important.  However the following rules apply:

(1) LAMMPS does not read your entire input script and then perform a

simulation with all the settings.  Rather, the input script is read

one line at a time and each command takes effect when it is read.

Thus this sequence of commands:

timestep 0.5

run      100

run      100 :pre

does something different than this sequence:

run      100

timestep 0.5

run      100 :pre

In the first case, the specified timestep (0.5 fs) is used for two

simulations of 100 timesteps each.  In the 2nd case, the default

timestep (1.0 fs) is used for the 1st 100 step simulation and a 0.5 fs

timestep is used for the 2nd one.

(2) Some commands are only valid when they follow other commands.  For

example you cannot set the temperature of a group of atoms until atoms

have been defined and a group command is used to define which atoms

belong to the group.

(3) Sometimes command B will use values that can be set by command A.

This means command A must precede command B in the input script if it

is to have the desired effect.  For example, the

"read_data"_read_data.html command initializes the system by setting

up the simulation box and assigning atoms to processors.  If default

values are not desired, the "processors"_processors.html and

"boundary"_boundary.html commands need to be used before read_data to

tell LAMMPS how to map processors to the simulation box.

Many input script errors are detected by LAMMPS and an ERROR or

WARNING message is printed.  The "Errors"_Errors.html doc page gives

more information on what errors mean.  The documentation for each

command lists restrictions on how the command can be used.