diff --git a/src/Advanced.rst b/src/Advanced.rst new file mode 100644 index 0000000..b534c33 --- /dev/null +++ b/src/Advanced.rst @@ -0,0 +1,16 @@ +.. _Advanced: + +Advanced Section +================ + +These pages provide introduction tutorials for people familiar with molecular +simulation who want to "get things done" in LAMMPS + +.. + From G.Clavier: + WIP: This section might use or refer to more of the material in the How-to + section of the manual + +.. toctree:: + :maxdepth: 1 + diff --git a/src/Beginner.rst b/src/Beginner.rst new file mode 100644 index 0000000..92ce490 --- /dev/null +++ b/src/Beginner.rst @@ -0,0 +1,17 @@ +.. _Beginner: + +Beginner Section +================ + +These pages provide introduction tutorials for people unfamiliar with molecular +simulation softwares and practice. + +.. toctree:: + :maxdepth: 1 + + file_format + setting_up_simulations + running_and_post_processing + variables_computes_fixes + averages_and_on_the_fly_computation + visualizing_trajectories diff --git a/src/Confirmed.rst b/src/Confirmed.rst new file mode 100644 index 0000000..a09ac63 --- /dev/null +++ b/src/Confirmed.rst @@ -0,0 +1,17 @@ +.. _Confirmed: + +Confirmed Section +================= + +These pages provide introduction tutorials for people who have a good knowledge +of LAMMPS and want to go deeper in setting complicated simulation environment +or Python coupling. + +.. + From G.Clavier: + WIP: This section might get technical but given the current state of LAMMPS + questions in the forum, this is not the most pressing matter IMO. + +.. toctree:: + :maxdepth: 1 + diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index 1eae425..18aaaa4 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -5,3 +5,63 @@ Learning Molecular Dynamics with LAMMPS (version |version|) LAMMPS is a classical molecular dynamics simulation code focusing on materials modeling. +Quoting the first paragraph of the overview section of the manual_: + + LAMMPS is a classical molecular dynamics (MD) code that models ensembles of + particles in a liquid, solid, or gaseous state. It can model atomic, + polymeric, biological, solid-state (metals, ceramics, oxides), granular, + coarse-grained, or macroscopic systems using a variety of interatomic + potentials (force fields) and boundary conditions. It can model 2d or 3d + systems with sizes ranging from only a few particles up to billions. + +In this tutorials, you will find step-by-step guides that aim at giving you +some fundamental comprehension of the code, basic input/output manipulation and +visualization of your simulation in order to give you some autonomy in the use +of the LAMMPS software. This does not replace proper teaching of statistical +mechanics and direct adivising from skilled users close to you and your work +environment but should give you some basic understanding to start your learning +of molecular simulation. + +These tutorials assume you are familiar with text file manipulation, basic +command-line use and your computer environment. They also assume you already +have the last version of LAMMPS executable installed. If not, contact your IT +departement or follow the `installation guide +`_ from the manual. If necessary, also +see `how to run LAMMPS executable dedicated section. +`_ LAMMPS usage is generally easier on +UNIX like systems (Linux distributions, macOS) so most examples will assume +this type of environment. On Windows systems, you can set-up WSL to be in an +equivalent environment. + +As for now the tutorial is organised in three main sections, mainly: + +1. Beginner: for people who have no experience whatsoever with molecular + simulation codes +2. Advanced: for people with some familiarity with molecular simulation that + want to know how to do more refined things in LAMMPS. +3. Confirmed: Detailed discussions on the howto examples from the manual. + +.. note: + As this is a LAMMPS tutorial and not a molecular simulation tutorial, some + topics of general knowledge will not be covered in details here. You will + find more information in classical textbooks such as Allen and Tildesley + "Computer simulation of fluids", Frenkel and Smit "Understanding molecular + simulation" and many others statistical physics textbooks. Such topics shall + be noted with a reference to "Classical textbooks". + +**************** +Table of content +**************** + +.. toctree:: + :maxdepth: 2 + :numbered: 2 + :caption: Table of content + :name: tutorialtoc + :includehidden: + + Beginner + Advanced + Confirmed + +.. _manual: https://docs.lammps.org diff --git a/src/averages_and_on_the_fly_computation.rst b/src/averages_and_on_the_fly_computation.rst new file mode 100644 index 0000000..10c2dcf --- /dev/null +++ b/src/averages_and_on_the_fly_computation.rst @@ -0,0 +1,6 @@ +.. _averages-calculations: + +===================================================== +Using averages and computing values during simulation +===================================================== + diff --git a/src/file_format.rst b/src/file_format.rst new file mode 100644 index 0000000..96c3fa2 --- /dev/null +++ b/src/file_format.rst @@ -0,0 +1,211 @@ +.. _file-format: + +================================ +Introduction to the file formats +================================ + +LAMMPS internally keeps track of the evolution of atomistic systems. Such a +system is described as a `simulation box` containing an ensemble of particles +interacting with one another according to set of rules, and each with their own +position, velocities etc. + +In this section, you will learn how to create a very simple simulation box +using LAMMPS built-in tools. + +Running a minimal LAMMPS input +------------------------------ + +In an empty directory, open a text file and copy the following text inside: + +.. code-block:: LAMMPS + + atom_style atomic + lattice sc 1. + region box block 0 5 0 5 0 5 + create_box 1 box + create_atoms 1 box + + mass 1 1 + + write_data data.lmp + write_dump all atom dump.lammpstrj + +Let's save the file with the name `in.lmp`. Now in the command-line you can +run the following command to execute LAMMPS with this input: + +.. code-block:: bash + + lmp -i in.lmp + +You should see a bunch of lines appear in your screen. The first one should start +with `LAMMPS` followed by a parentheses with the specification of the version +of the code you are using. The last line should read something like +`Total wall time: 00:00:00`. If you've never executed LAMMPS before, +congratulation! This is maybe your first successful (very simple) simulation! + +You will also notice that two files appeared in the directory: `data.lmp` and +`dump.lammpstrj`. Let's start by opening the first one. + +Data file format +**************** + +The first file of the two is usually referred to as a `data file`. Its format +is rather strict, containing: + +* a "header" block, which must come first in the file, and +* several "data sections", each of which: + + * starts with a capitalized keyword (such as "Atoms" or "Velocities") + * followed by a blank line + * and then a block of numbers (such as each atom's ID, x, y, and z velocities in "Velocities") + +Let's slowly go through all of this. + +The first part of the file is called `the header`. The first line of the file +is always a comment that LAMMPS does not read but which can contain +information on the way the file was generated. Here we see the LAMMPS version +and some more information like timestep and units. The following lines contain +the number of `atoms` (125), the number of `atom types` (1) and three lines +containing `xlo xhi` like indications. This header is simple, but generally, +headers can contain much more information. The first two lines are explicit, +you define a system with 125 atoms all of which have the same characteristics. +They all have the same characteristics because your simulation has only one `atom type`; +you will soon learn how to specify different interactions between particles +in LAMMPS by giving the particles different atom types. +The last three lines define the volume in which these atoms are contained. It +is a box with edge coordinates starting at 0 and ending at 5 in every direction +(x, y and z). + +From here starts the body of the file. The order of the sections is not important +but all of them must come in the format: + +.. code-block:: LAMMPS + + Section name # Capitalized, correctly spelled + # blank line + Section input # Number of line and format depend on the section. + +The first section you should see is the `Masses` section. In LAMMPS, masses are +usually assigned by atom types. Since you have only one atom type +in this simulation, this `Masses` section has only one line. + +The `Atoms` section contains 125 lines, one per atom. The number on each line +are ordered and are for each particle: +* The particle ID which LAMMPS uses to refer to that particle internally +* The type of the particle +* The x, y and z coordinates in absolute distance value +* The xflag, yflag and zflag values, which you can put aside for now + +Below you can also see the `Velocities` section which also contains 125 lines. +Each lines gives the particle ID followed by the instantaneous velocities of +the particles along the x, y and z axis in that order. The particle ID refers +to the same ID as in the `Atoms` section. + +This data file is quite simple because our Very First LAMMPS Script had the +`atom_style` `atomic`, where each particle only has an ID number +and a three-dimensional position and velocity (and periodic image location). +More detailed simulations will use other `atom_style` commands, +such as `atom_style molecular`, which also tracks molecule ID +numbers and intramolecular arrangements like bonds, +angles, "dihedrals" and "impropers" (which you will learn about later). +You can see that LAMMPS includes a comment `# atomic` next to the +`Atoms` section name (here `# atomic`), and you can find a detailed +description of each format in the `read_data section of the manual`_. + +You may have noticed our first LAMMPS script also produced a `dump file`. +We will now read through this dump file, and then learn how it is +different from a data file and how to use each file type. + +Dump file format +**************** + +Following the previous sections, open the `dump.lammpstrj` file that should +have appeared in your directory. This is a `dump file` containing a single +`snapshot` You should see something like this: + +.. code-block:: LAMMPS + + ITEM: TIMESTEP + 0 + ITEM: NUMBER OF ATOMS + 125 + ITEM: BOX BOUNDS pp pp pp + 0.0000000000000000e+00 5.0000000000000000e+00 + 0.0000000000000000e+00 5.0000000000000000e+00 + 0.0000000000000000e+00 5.0000000000000000e+00 + ITEM: ATOMS id type xs ys zs + 1 1 0 0 0 + 2 1 0.2 0 0 + 3 1 0.4 0 0 + 4 1 0.6 0 0 + 5 1 0.8 0 0 + ... + +The dump file format is simpler than the data file. Each section is labeled +with a header directly followed by the data we wanted to dump. Here we used the +basic atom dump_style so we only have atoms' id, types and scaled coordinates +(that is coordinates divided by box length in each dimension). + +From the TIMESTEP heading, you might guess that a dump file will +usually contain information about how a simulation changes `over time`, +and you would be correct! Thus, a `data` file is used to store the `complete` +state of a simulation with the `write_data` command, and in later lessons +you will see how to start a new simulation from that state with the +`read_data` command. On the other hand, a `dump` file stores information +about how the system changes over time, and can then be used for analyzing +simulation results. + +If you (or your supervisor) have previously used other molecular dynamics +software, you may recognize that the dump file loosely corresponds to "coordinates" +or "trajectory" output files from other software. However, LAMMPS gives you +great flexibility in what you choose to output. For example, the default `dump` format +outputs scaled coordinates, but we will soon see how to output unscaled +coordinates instead. You may know that other molecular dynamics packages +store information that `does not` change throughout a simulation (such as +molecular bonds and particle charges) in "parameter", "topology" or +"configuration" files. In LAMMPS, this information is read from a `data` file, but +the `data` file also usually contains coordinates and velocities. + +As an example of customizing the dump file, +in your `in.lmp` file, replace the `write_dump` line with the following: + +.. code-block:: LAMMPS + + write_dump all custom dump.lammpstrj id type x y z vx vy vz + +Save the file, and run the code as previously: + +.. code-block:: bash + + lmp -i in.lmp + +Now the `dump.lammpstrj` file should have changed to the following: + +.. code-block:: LAMMPS + + ITEM: TIMESTEP + 0 + ITEM: NUMBER OF ATOMS + 125 + ITEM: BOX BOUNDS pp pp pp + 0.0000000000000000e+00 5.0000000000000000e+00 + 0.0000000000000000e+00 5.0000000000000000e+00 + 0.0000000000000000e+00 5.0000000000000000e+00 + ITEM: ATOMS id type x y z vx vy vz + 1 1 0 0 0 0 0 0 + 2 1 1 0 0 0 0 0 + 3 1 2 0 0 0 0 0 + 4 1 3 0 0 0 0 0 + 5 1 4 0 0 0 0 0 + ... + +The `custom` format allows +you to write every properties of each atoms to the file. There are a series of +keywords that you can use depending on the `atom_style` and values that you +can also calculate through the use of LAMMPS computes and variables. More on +that in later tutorials. + +For now on we haven't done much with our atoms. Let's see how to run an actual +simulation in the :ref:`setting-up-simulations` section. + +.. _read_data section of the manual: https://docs.lammps.org/read_data.html diff --git a/src/images/Lennard-Jones.png b/src/images/Lennard-Jones.png new file mode 100644 index 0000000..2ceaf4a Binary files /dev/null and b/src/images/Lennard-Jones.png differ diff --git a/src/running_and_post_processing.rst b/src/running_and_post_processing.rst new file mode 100644 index 0000000..58dde2f --- /dev/null +++ b/src/running_and_post_processing.rst @@ -0,0 +1,121 @@ +.. _running-post-processing: + +=========================== +Running and post-processing +=========================== + +The run command +*************** + +The `data.lmp` file LAMMPS has written for us in the previous section should be +the configuration to use to start a new simulation. Let's make a new directory +called `NVE` and copy the file `data.lmp` there. + +.. _note:: + + You can chain many simulations in a single LAMMPS script and make a lot of + complicated computations in one go. However this is prone to error. If + anything goes wrong and makes LAMMPS crash, all unsaved data will be lost. + Splitting simulations in several equilibration and production phases with + intermediate file writing is generally considered good practice. For this + tutorial, this is the chosen workflow. That being said, it is up to you to + find your own pace. + +We can make a new `in.lmp` file here to contain only the instruction related +to our simulation. Let's open a new file add the following lines: + +.. code-block:: LAMMPS + pair_style lj/cut 2.5 + read_data data.lmp + run 10000 + write_data data.out.lmp + +The `run`_ command is the one iteratively applying time integration as it goes. +Here we tell it go through 10000 timesteps. Execute the code the same way as +before by typing `lmp -i in.lmp` in your terminal. As before you should see +some text on your screen. But let's have a look to the `log.lammps` file that +is now in your directory. The text is the same as what appeared on your screen +but it is easier to go through a text file. + +.. _note:: + + The `log`_ command allow you to + change the name of the log file in your script. The -l command-line option + allows you to do the same. + +In the log file, you will also find the commands and comments that were read +and executed through the script. Below the `run 10000` command, you will see +a lot of new information that were not present in the previous run. For now +lets focus on the part that starts with `Per MPI rank memory allocation...` and +`Loop time of...`. This is the main output of your run command where you will +find most information related to computed quantities such as temperature, +pressure, etc computed during your simulation. This part is controlled through +the `thermo`_ and `thermo_modify`_ +commands. But the default only tells us what was computed on each 10000 step +of our run, which is not very useful for us. Let's go back to our script. + +Before the run, we can ask the output to be done more regularly by adding the +following: + +.. code-block:: LAMMPS + ... + thermo 1000 + run 10000 + ... + +Now if we run the script again we can see that the log contains 9 more values. +But these are always the same, so basically nothing is happening. This is +because we didn't tell the code to do anything on our atoms! For that, we +need to use `fix`_ commands. + +Integrating the equations of motion +*********************************** + +In LAMMPS a fix is + + ...any operation that is applied to the system during timestepping or + minimization. Examples include updating of atom positions and velocities + due to time integration, controlling temperature, applying constraint + forces to atoms, enforcing boundary conditions, computing diagnostics, + etc. (see `fix`_) + +This means that if we want atoms to update their position based on the force +they experience, we have to use one of the integrating fixes. Fix +`nve`_ integrates the positions using +the velocity Verlet algorithm. [Classics]_ NVE stands for integration with +constant number of particles (N), Volume (V) and Energy (E) but it is +important to emphasize that this fix **only integrates the equation of +motion**. The corresponding NVE ensemble (or micro-canonical ensemble) is +only produced when such integration is done on periodic system without any +source or sink of energy (external forces, fields, drag forces etc.) That being +said, let's add the following to our input script: + +.. code-block:: LAMMPS + ... + thermo 1000 + fix 1 all nve + run 10000 + ... + +Now if we run the simulation, we can see that there is some change in the +values. Notably, the `Temp` column shows us that the temperature, which is +proportional to the kinetic energy [Classics]_ evolves, as well as the `E_pair` +column which show the non-bonded interaction. This is fine, but what can we +also simply compute on such a system? + +.. note: + One might notice that, contrary to what is stated above, the `TotEng` column + containing the total energy of the system is not exactly constant. This is + unfortunately due to the use of finite differences to compute new position + from the forces and a small timestep value. This is a well known problem in + molecular dynamics. However are, on average, very stable over long time + period. + +Modifying the thermo output +*************************** + +.. todo:: + + Continue writing this section. + +.. [Classics] Classical textbooks diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst new file mode 100644 index 0000000..3e73212 --- /dev/null +++ b/src/setting_up_simulations.rst @@ -0,0 +1,135 @@ +.. _setting-up-simulations: + +================================= +Setting up your first simulations +================================= + +In this section we will modify the input from the previous section to +integrate the equations of motion of the atoms and have a first look at +the use of variables and computes in LAMMPS. + +Defining non-bonded interactions +******************************** + +Let's have a look at the script we used in the first part: the `in.lmp` file. + +.. code-block:: LAMMPS + + lattice sc 1. + region box block 0 5 0 5 0 5 + create_box 1 box + create_atoms 1 box + + mass 1 1 + + write_data data.lmp + write_dump all atom dump.lammpstrj + +What this script does is: + +1. defining a `lattice`_, which is simply a set of positions, here all the + combinations of {x,y,z} where each are multiples of 1. +2. defining an abstract region containing 5 lattice cells in each direction + and putting atoms at those positions. Since there is only one atomic + position per cell this results in :math:`5^3=125` atoms. +3. defining a concrete simulation box from this region. +4. putting atoms at the coordinates defined by the lattice. +5. giving them a mass, and writing output files. + +That's it. Nowhere are interactions between atoms defined. As such they do not +interact with one another. Let's change that. + +Edit the `in.lmp` file by adding the following lines between the `mass`_ and +`write_data`_ commands: + +.. code-block:: LAMMPS + + ... + mass 1 1 + + pair_style lj/cut 2.5 + pair_coeff 1 1 1 1 + + write_data data.lmp + ... + +If you save this file and execute the script using LAMMPS, you might think that +nothing changed, but if you open the data file, you'll notice that a new section +appeared: `Pair Coeffs # lj/cut`. The comment following the `#` symbol indicates +which pair style was used when defining the non-bonded interactions in the system. +A line starting with `#` is only indicative and will not be read by LAMMPS. +However, it will tell you which pair style you should set before reading the +said file. Here `lj/cut`_ is the standard Lennard-Jones potential using a +cutoff distance. Pair of atoms separated by a distance longer than the cutoff +will not interact. + +.. image:: images/Lennard-Jones.png + :scale: 50 + :align: center + +The definition of the interaction happens in two steps. First you set an +interaction style (here a `pair_style`_). You then have to define interaction +coefficients for each type of atom. Note that the second step must be done +**after** the number of `atom types` is defined in the simulation. + +It is worth detailing the format of the `pair_coeff`_ command. It defines +how nearby atoms interact, based on their types. That is the +reason there are four values after the command: two for the types of interacting +pairs, two for the interaction coefficients. Here we only have atoms of type 1 +so all the values are the same. If atoms of type 2 were present, we would have +had to add at least: + +.. code-block:: LAMMPS + + pair_coeff 2 2 1 1 + +where 1 1 can be any other parameters we would like to use for type 2. + +.. warning:: + + Some interactions like `lj/cut` have default mixing rules that save some + typing when defining cross-types interactions. Others might need specific + format for the `pair_coeff` commands. In any case you should be aware that + these mixing rules are euristics for simple models and that they do not + apply to all long-range_interactions. We refer you to the manual's sections + detailing the models you want to use for your simulations. + +Energy minimization +******************* + +Now that we have defined interactions between our atoms, we can compute forces +and energy for our system. In the general case, initial geometries are guesses +from chemical information from *real* systems, but they're not necessary +representative of equilibrium state of the model with the interactions you are +using. You can end-up in a situation where some local structure causes force +divergences and numerical integration becomes unstable. Bad initial geometry is +a common problem that many people encounter without realizing. + +If you are unsure about the situation, it is good practice to minimize the +energy of your system. Fortunately, LAMMPS allows you to do so. In short, it +makes atoms slowly go along their energy gradients. By default, the `minimize +`_ command uses conjugate gradients +algorithm [Classics]_ to this end. + +You can add the following line in your `in.lmp` file. + +.. code-block:: LAMMPS + + ... + minimize 1e-6 1e-8 1000 2000 + write_data data.lmp + ... + +What this command means is "try to minimize the energy of the system 1000 times +*or* until the energy difference between consecutive steps is less than 1 +millionth in energy units *or* until the relative force difference is less than +100 millionth *or* until it takes more than 2000 evaluation to converge in +energy and forces". In the case of our Lennard-Jones simple crystal, this +should be rather straight forward since we are already close to an energy +minimum. + +We now have an initial condiguration at minimum energy of a single crystal. It +is now time for the "dynamics" part of "molecular dynamics" to kick-in in the +:ref:`running-post-processing` section! + +.. [Classics] Classical textbooks diff --git a/src/variables_computes_fixes.rst b/src/variables_computes_fixes.rst new file mode 100644 index 0000000..91f4e37 --- /dev/null +++ b/src/variables_computes_fixes.rst @@ -0,0 +1,5 @@ +.. _variables-computes-fixes: + +======================================= +Variables, computes and fixes in LAMMPS +======================================= diff --git a/src/visualizing_trajectories.rst b/src/visualizing_trajectories.rst new file mode 100644 index 0000000..72910c0 --- /dev/null +++ b/src/visualizing_trajectories.rst @@ -0,0 +1,5 @@ +.. _visualizing-trajectories: + +================================ +Visualizing trajectories outputs +================================