From af3d2ff3919953773dbe718afef4ce4558b09dc6 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 13 Nov 2023 17:41:39 +0100 Subject: [PATCH 01/32] A first commit with some initial description of the tutorial goals and a first incomplete class on file formats. --- src/Learning_MD.rst | 22 ++++++ src/first_script.rst | 161 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 src/first_script.rst diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index 1eae425..0e5a9f9 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -5,3 +5,25 @@ 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, +visualization of your simulation and finally autonomy in the use of the code. + +These tutorials assumes you are familiar with text file manipulation, basic +command-line use and your computer environment. They also assume you already +have LAMMPS executable installed. If not, contact your IT departement or follow +the installation guide from the manual. LAMMPS usage is generally easier on +UNIX like systems (Linux distributions, macOS) so most examples shall assume +this type of environment. On Windows systems, you can set-up WSL to be in an +equivalent environment. + +.. _manual: https://docs.lammps.org diff --git a/src/first_script.rst b/src/first_script.rst new file mode 100644 index 0000000..2a42461 --- /dev/null +++ b/src/first_script.rst @@ -0,0 +1,161 @@ +============================== +Running your first simulations +============================== + +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. + +Minimal input and file formats +------------------------------ + +In an empty directory, open a text file and copy the following text inside: + +.. 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 + +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 line 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 sucessful (very simple) simulation! + +You will also notice that two file 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 and you can see that there are general information at the +top of the file and several sections starting with a capitalized word, a blank +line and some numbers. 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 +informations 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 informations. The first two lines are explicit, +you define a system with 125 atoms all of which have the same caracteristics. +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 +assigned to atom types so you only have one line here. All types have their own +masses but several types can have the same mass. Types are LAMMPS way to refer +to properties of particles that are *the same* for all particles of *the same +type*. They are also used to determine how particles interact with one another. +Types are not always binded to chemical species and you will see in further +tutorials how it can be convenient to define different types for similar atoms. + +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. + +The format and meaning of the number in the `Atoms` and `Velocities` sections +will depend on the `atom_style` the code is told to use. In most recents +versions of LAMMPS, writing a data file with `write_data` will append a comment +next to the `Atoms` section name (here `# atomic`). This helps human readers to +know the meaning of the different number. Some formats can include more +information like a molecule tag, particles' charges, particles' spins or +orientation etc. For the velocities, some `atom_style` can require keeping +track of angular momentum, angular velocities etc. You'll find a detailed +description of each format in the `read_data section of the manual`_. + +As a first takeaway, remember that `data files` contain detailed informations +on a simulation system at a given time. They are more convenient for input and +output. Several simulation softwares allow you to export files as LAMMPS +`data files` and take them as input. But data format are not straightforward to +use for analyses: they are heavy and may contain useless informations. This is +what the dump file format is for. + +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 format is more simple compared to 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). + +You can compare the informations with the one you got from the `data file` and +see that for now we have the same information in both files, with some +exceptions (total number of types, masses and the velocities). Getting only the +scaled coordinates of the atoms is a bit limited but fortunately, we can get +much more. + +In your `in.lmp` file, replace the `write_dump` line with the following: + +.. code-block:: LAMMPS + + write_dump all custom dump.lammpstrj 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: +.. _read_data section of the manual: https://docs.lammps.org/read_data.html From c700bade5e39144da07978392268047d48f3f505 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 13 Nov 2023 17:42:37 +0100 Subject: [PATCH 02/32] Some edits to continue the initial lesson. --- src/first_script.rst | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/src/first_script.rst b/src/first_script.rst index 2a42461..669af93 100644 --- a/src/first_script.rst +++ b/src/first_script.rst @@ -149,7 +149,7 @@ In your `in.lmp` file, replace the `write_dump` line with the following: .. code-block:: LAMMPS - write_dump all custom dump.lammpstrj x y z vx vy vz + write_dump all custom dump.lammpstrj id type x y z vx vy vz Save the file, and run the code as previously: @@ -158,4 +158,23 @@ Save the file, and run the code as previously: 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 + ... + .. _read_data section of the manual: https://docs.lammps.org/read_data.html From 8ded3f90dd3776a92c9161ad0682e8105a72bd34 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Thu, 23 Nov 2023 16:57:50 +0100 Subject: [PATCH 03/32] Added a basic structure of the tutorial in three steps. Added simple files for the outline of the tutorial. Added empty files for the first sections of the Beginner section. --- src/Advanced.rst | 14 +++ src/Beginner.rst | 15 +++ src/Confirmed.rst | 15 +++ src/Learning_MD.rst | 43 +++++-- src/averages_and_on_the_fly_computation.rst | 4 + src/{first_script.rst => file_format.rst} | 17 ++- src/images/Lennard-Jones.png | Bin 0 -> 73811 bytes src/running_and_post_processing.rst | 4 + src/setting_up_simulations.rst | 128 ++++++++++++++++++++ src/variables_computes_fixes.rst | 3 + src/visualising_trajectories.rst | 3 + 11 files changed, 235 insertions(+), 11 deletions(-) create mode 100644 src/Advanced.rst create mode 100644 src/Beginner.rst create mode 100644 src/Confirmed.rst create mode 100644 src/averages_and_on_the_fly_computation.rst rename src/{first_script.rst => file_format.rst} (92%) create mode 100644 src/images/Lennard-Jones.png create mode 100644 src/running_and_post_processing.rst create mode 100644 src/setting_up_simulations.rst create mode 100644 src/variables_computes_fixes.rst create mode 100644 src/visualising_trajectories.rst diff --git a/src/Advanced.rst b/src/Advanced.rst new file mode 100644 index 0000000..b39c5df --- /dev/null +++ b/src/Advanced.rst @@ -0,0 +1,14 @@ +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..2891e8e --- /dev/null +++ b/src/Beginner.rst @@ -0,0 +1,15 @@ +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 + visualising_trajectories diff --git a/src/Confirmed.rst b/src/Confirmed.rst new file mode 100644 index 0000000..fbdf776 --- /dev/null +++ b/src/Confirmed.rst @@ -0,0 +1,15 @@ +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 0e5a9f9..b7b8203 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -15,15 +15,44 @@ Quoting the first paragraph of the overview section of the manual_: 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, -visualization of your simulation and finally autonomy in the use of the code. +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 assumes you are familiar with text file manipulation, basic +These tutorials assume you are familiar with text file manipulation, basic command-line use and your computer environment. They also assume you already have LAMMPS executable installed. If not, contact your IT departement or follow -the installation guide from the manual. LAMMPS usage is generally easier on -UNIX like systems (Linux distributions, macOS) so most examples shall assume -this type of environment. On Windows systems, you can set-up WSL to be in an -equivalent environment. +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. + +**************** +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..cea8ebc --- /dev/null +++ b/src/averages_and_on_the_fly_computation.rst @@ -0,0 +1,4 @@ +===================================================== +Using averages and computing values during simulation +===================================================== + diff --git a/src/first_script.rst b/src/file_format.rst similarity index 92% rename from src/first_script.rst rename to src/file_format.rst index 669af93..3e376b6 100644 --- a/src/first_script.rst +++ b/src/file_format.rst @@ -1,6 +1,6 @@ -============================== -Running your first simulations -============================== +================================ +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 @@ -10,7 +10,7 @@ position, velocities etc. In this section, you will learn how to create a very simple simulation box using LAMMPS built-in tools. -Minimal input and file formats +Running a minimal LAMMPS input ------------------------------ In an empty directory, open a text file and copy the following text inside: @@ -177,4 +177,13 @@ Now the `dump.lammpstrj` file should have changed to the following: 5 1 4 0 0 0 0 0 ... +You now have different information in your dump file. 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. + .. _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 0000000000000000000000000000000000000000..2ceaf4a9c4a6e1e490209900f8d3929cedf4d5e9 GIT binary patch literal 73811 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 literal 0 HcmV?d00001 diff --git a/src/running_and_post_processing.rst b/src/running_and_post_processing.rst new file mode 100644 index 0000000..67d5a2b --- /dev/null +++ b/src/running_and_post_processing.rst @@ -0,0 +1,4 @@ +=========================== +Running and post-processing +=========================== + diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst new file mode 100644 index 0000000..b504e4b --- /dev/null +++ b/src/setting_up_simulations.rst @@ -0,0 +1,128 @@ +================================= +Setting up your first simulations +================================= + +In this section we will modify the input from the previous section to run +integrate the equations of motion of the atoms and have a first look at +variable and computes use 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 interaction between atoms defined. As such they do not +interact with one another. Let's change that. + +Edit the `in.lmp` file with 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 in 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 after the `#` symbol indicates +which pair style was used when defining the system non-bonded interactions. It +is only indicative and will not be read by LAMMPS when reading the data file. +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 types of atoms. 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 +long range interactions between atoms with regard to 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 local structure cause force +divergence and numerical integration becomes unstable. Bad initial geometry +is a common problem that many people encounter without realising. + +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 +algorith 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* 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. + +.. _lj/cut: https://docs.lammps.org/pair_lj.html diff --git a/src/variables_computes_fixes.rst b/src/variables_computes_fixes.rst new file mode 100644 index 0000000..895afb5 --- /dev/null +++ b/src/variables_computes_fixes.rst @@ -0,0 +1,3 @@ +======================================= +Variables, computes and fixes in LAMMPS +======================================= diff --git a/src/visualising_trajectories.rst b/src/visualising_trajectories.rst new file mode 100644 index 0000000..45cf40c --- /dev/null +++ b/src/visualising_trajectories.rst @@ -0,0 +1,3 @@ +================================ +Visualising trajectories outputs +================================ From 59c61e2bff76d2ad81457c1b04c18b636418f8ea Mon Sep 17 00:00:00 2001 From: Simon Gravelle Date: Thu, 23 Nov 2023 19:56:43 +0100 Subject: [PATCH 04/32] made some minor changes to the text --- src/file_format.rst | 26 +++++++++++++------------- src/setting_up_simulations.rst | 20 ++++++++++---------- src/visualising_trajectories.rst | 2 +- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index 3e376b6..c20ef32 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -34,13 +34,13 @@ run the following command to execute LAMMPS with this input: lmp -i in.lmp -You should see a bunch of line appear in your screen. The first one should start +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 sucessful (very simple) simulation! +congratulation! This is maybe your first successful (very simple) simulation! -You will also notice that two file appeared in the directory: `data.lmp` and +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 @@ -53,12 +53,12 @@ line and some numbers. 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 -informations on the way the file was generated. Here we see the LAMMPS version +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 informations. The first two lines are explicit, -you define a system with 125 atoms all of which have the same caracteristics. +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. 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). @@ -102,11 +102,11 @@ orientation etc. For the velocities, some `atom_style` can require keeping track of angular momentum, angular velocities etc. You'll find a detailed description of each format in the `read_data section of the manual`_. -As a first takeaway, remember that `data files` contain detailed informations +As a first takeaway, remember that `data files` contain detailed information on a simulation system at a given time. They are more convenient for input and output. Several simulation softwares allow you to export files as LAMMPS `data files` and take them as input. But data format are not straightforward to -use for analyses: they are heavy and may contain useless informations. This is +use for analyses: they are heavy and may contain useless information. This is what the dump file format is for. Dump file format @@ -139,10 +139,10 @@ 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). -You can compare the informations with the one you got from the `data file` and -see that for now we have the same information in both files, with some -exceptions (total number of types, masses and the velocities). Getting only the -scaled coordinates of the atoms is a bit limited but fortunately, we can get +You can compare the `dump file` with the `data file`, and +see that they basically contain the same information, with few +exceptions, namely the total number of types, masses and the velocities. Getting only the +scaled coordinates of the atoms is not alway ideal, but fortunately we can get much more. In your `in.lmp` file, replace the `write_dump` line with the following: @@ -177,7 +177,7 @@ Now the `dump.lammpstrj` file should have changed to the following: 5 1 4 0 0 0 0 0 ... -You now have different information in your dump file. The `custom` format allows +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 diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index b504e4b..06e286a 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -2,9 +2,9 @@ Setting up your first simulations ================================= -In this section we will modify the input from the previous section to run +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 -variable and computes use in LAMMPS. +the use of variables and computes in LAMMPS. Defining non-bonded interactions ******************************** @@ -37,7 +37,7 @@ What this script does is: That's it. Nowhere are interaction between atoms defined. As such they do not interact with one another. Let's change that. -Edit the `in.lmp` file with the following lines between the `mass` and +Edit the `in.lmp` file by adding the following lines between the `mass` and `write_data` commands: .. code-block:: LAMMPS @@ -51,11 +51,11 @@ Edit the `in.lmp` file with the following lines between the `mass` and write_data data.lmp ... -If you save this file and execute the script in LAMMPS you might think that +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 after the `#` symbol indicates -which pair style was used when defining the system non-bonded interactions. It -is only indicative and will not be read by LAMMPS when reading the data file. +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 @@ -67,7 +67,7 @@ will not interact. 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 types of atoms. Note that the second step must be done +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 @@ -101,13 +101,13 @@ 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 local structure cause force divergence and numerical integration becomes unstable. Bad initial geometry -is a common problem that many people encounter without realising. +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 -algorith to this end. +algorithm to this end. You can add the following line in your `in.lmp` file. diff --git a/src/visualising_trajectories.rst b/src/visualising_trajectories.rst index 45cf40c..3ada451 100644 --- a/src/visualising_trajectories.rst +++ b/src/visualising_trajectories.rst @@ -1,3 +1,3 @@ ================================ -Visualising trajectories outputs +Visualizing trajectories outputs ================================ From da470925db275d1283783ce9fadb47f7966d7f03 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Sat, 25 Nov 2023 16:49:58 +0100 Subject: [PATCH 05/32] Added labels to files at the top. --- src/Advanced.rst | 2 ++ src/Beginner.rst | 2 ++ src/Confirmed.rst | 2 ++ src/averages_and_on_the_fly_computation.rst | 2 ++ src/file_format.rst | 4 +++- src/running_and_post_processing.rst | 2 ++ src/setting_up_simulations.rst | 2 ++ src/variables_computes_fixes.rst | 2 ++ src/visualising_trajectories.rst | 2 ++ 9 files changed, 19 insertions(+), 1 deletion(-) diff --git a/src/Advanced.rst b/src/Advanced.rst index b39c5df..b534c33 100644 --- a/src/Advanced.rst +++ b/src/Advanced.rst @@ -1,3 +1,5 @@ +.. _Advanced: + Advanced Section ================ diff --git a/src/Beginner.rst b/src/Beginner.rst index 2891e8e..fba92cb 100644 --- a/src/Beginner.rst +++ b/src/Beginner.rst @@ -1,3 +1,5 @@ +.. _Beginner: + Beginner Section ================ diff --git a/src/Confirmed.rst b/src/Confirmed.rst index fbdf776..a09ac63 100644 --- a/src/Confirmed.rst +++ b/src/Confirmed.rst @@ -1,3 +1,5 @@ +.. _Confirmed: + Confirmed Section ================= diff --git a/src/averages_and_on_the_fly_computation.rst b/src/averages_and_on_the_fly_computation.rst index cea8ebc..10c2dcf 100644 --- a/src/averages_and_on_the_fly_computation.rst +++ b/src/averages_and_on_the_fly_computation.rst @@ -1,3 +1,5 @@ +.. _averages-calculations: + ===================================================== Using averages and computing values during simulation ===================================================== diff --git a/src/file_format.rst b/src/file_format.rst index c20ef32..cc5ae67 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -1,3 +1,5 @@ +.. _file-format: + ================================ Introduction to the file formats ================================ @@ -184,6 +186,6 @@ 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. +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/running_and_post_processing.rst b/src/running_and_post_processing.rst index 67d5a2b..52877f8 100644 --- a/src/running_and_post_processing.rst +++ b/src/running_and_post_processing.rst @@ -1,3 +1,5 @@ +.. _running-post-processing: + =========================== Running and post-processing =========================== diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index 06e286a..c1d3842 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -1,3 +1,5 @@ +.. _setting-up-simulations: + ================================= Setting up your first simulations ================================= diff --git a/src/variables_computes_fixes.rst b/src/variables_computes_fixes.rst index 895afb5..91f4e37 100644 --- a/src/variables_computes_fixes.rst +++ b/src/variables_computes_fixes.rst @@ -1,3 +1,5 @@ +.. _variables-computes-fixes: + ======================================= Variables, computes and fixes in LAMMPS ======================================= diff --git a/src/visualising_trajectories.rst b/src/visualising_trajectories.rst index 3ada451..72910c0 100644 --- a/src/visualising_trajectories.rst +++ b/src/visualising_trajectories.rst @@ -1,3 +1,5 @@ +.. _visualizing-trajectories: + ================================ Visualizing trajectories outputs ================================ From c88f9a5a690eaec9179d8077349e756cc0879e23 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Sat, 25 Nov 2023 16:50:45 +0100 Subject: [PATCH 06/32] Changes visualizing file name to american english spelling --- ...{visualising_trajectories.rst => visualizing_trajectories.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/{visualising_trajectories.rst => visualizing_trajectories.rst} (100%) diff --git a/src/visualising_trajectories.rst b/src/visualizing_trajectories.rst similarity index 100% rename from src/visualising_trajectories.rst rename to src/visualizing_trajectories.rst From 70641e345eb6c4d38909625138f678145aeb510b Mon Sep 17 00:00:00 2001 From: Bibobu Date: Sun, 26 Nov 2023 16:23:15 +0100 Subject: [PATCH 07/32] Corrected a file name in Beginner.rst --- src/Beginner.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Beginner.rst b/src/Beginner.rst index fba92cb..92ce490 100644 --- a/src/Beginner.rst +++ b/src/Beginner.rst @@ -14,4 +14,4 @@ simulation softwares and practice. running_and_post_processing variables_computes_fixes averages_and_on_the_fly_computation - visualising_trajectories + visualizing_trajectories From 1cc9d241012af98766820eb8970d082199f5771f Mon Sep 17 00:00:00 2001 From: Bibobu Date: Sun, 26 Nov 2023 16:23:48 +0100 Subject: [PATCH 08/32] Adding the end of the file setting_up_simulations and reference to running_and_post_processing. --- src/setting_up_simulations.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index c1d3842..cc57013 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -100,10 +100,10 @@ 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 local structure cause force -divergence and numerical integration becomes unstable. Bad initial geometry -is a common problem that many people encounter without realizing. +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 @@ -123,8 +123,13 @@ You can add the following line in your `in.lmp` file. 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* 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. +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! .. _lj/cut: https://docs.lammps.org/pair_lj.html From 8cd58c31e58d5eda7c29de2ebf624939a782fad6 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:22:50 +0100 Subject: [PATCH 09/32] Added a mention to the general [Classics] ref. --- src/Learning_MD.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index b7b8203..a95b4cf 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -40,6 +40,15 @@ As for now the tutorial is organised in three main sections, mainly: 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 **************** From d8c1bc0aaf080a26211978bc99c56b16b570bf7a Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:23:40 +0100 Subject: [PATCH 10/32] Homogen. references to commands, added some [Classics] ref. --- src/setting_up_simulations.rst | 51 +++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index cc57013..d4a509f 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -16,7 +16,7 @@ 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 + region box block 0 10 0 10 0 10 create_box 1 box create_atoms 1 box @@ -27,11 +27,12 @@ Let's have a look at the script we used in the first part: the `in.lmp` file. 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. +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. + position per cell this results in :math:`10^3=1000` 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. @@ -39,8 +40,9 @@ What this script does is: That's it. Nowhere are interaction 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: +Edit the `in.lmp` file by adding the following lines between the +`mass`_ and +`write_data`_ commands: .. code-block:: LAMMPS @@ -54,27 +56,30 @@ Edit the `in.lmp` file by adding the following lines between the `mass` and ... 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. +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 -long range interactions between atoms with regard to their types. That is the -reason there are four values after the command: two for the types of interacting +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 long +range interactions between atoms with regard to 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: @@ -109,7 +114,7 @@ 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 to this end. +algorithm [Classics]_ to this end. You can add the following line in your `in.lmp` file. @@ -132,4 +137,4 @@ 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! -.. _lj/cut: https://docs.lammps.org/pair_lj.html +.. [Classics] Classical textbooks From c35346845b037081055b627858a1422b8f365fb6 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:24:07 +0100 Subject: [PATCH 11/32] Continued the writing of running_and_pp. --- src/running_and_post_processing.rst | 117 ++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/src/running_and_post_processing.rst b/src/running_and_post_processing.rst index 52877f8..4794c46 100644 --- a/src/running_and_post_processing.rst +++ b/src/running_and_post_processing.rst @@ -4,3 +4,120 @@ 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 +*************************** + +.. [Classics] Classical textbooks From af102ea9d177e08ac1addb93e58fe50efd768d3e Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:47:04 +0100 Subject: [PATCH 12/32] Revert "Continued the writing of running_and_pp." This reverts commit c35346845b037081055b627858a1422b8f365fb6. --- src/running_and_post_processing.rst | 117 ---------------------------- 1 file changed, 117 deletions(-) diff --git a/src/running_and_post_processing.rst b/src/running_and_post_processing.rst index 4794c46..52877f8 100644 --- a/src/running_and_post_processing.rst +++ b/src/running_and_post_processing.rst @@ -4,120 +4,3 @@ 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 -*************************** - -.. [Classics] Classical textbooks From 8767856b096a97784bbec423259cc95324234865 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:47:14 +0100 Subject: [PATCH 13/32] Revert "Homogen. references to commands, added some [Classics] ref." This reverts commit d8c1bc0aaf080a26211978bc99c56b16b570bf7a. --- src/setting_up_simulations.rst | 51 +++++++++++++++------------------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index d4a509f..cc57013 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -16,7 +16,7 @@ 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 10 0 10 0 10 + region box block 0 5 0 5 0 5 create_box 1 box create_atoms 1 box @@ -27,12 +27,11 @@ Let's have a look at the script we used in the first part: the `in.lmp` file. 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. +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:`10^3=1000` atoms. + 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. @@ -40,9 +39,8 @@ What this script does is: That's it. Nowhere are interaction 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: +Edit the `in.lmp` file by adding the following lines between the `mass` and +`write_data` commands: .. code-block:: LAMMPS @@ -56,30 +54,27 @@ Edit the `in.lmp` file by adding the following lines between the ... 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. +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 long -range interactions between atoms with regard to their types. That is the reason -there are four values after the command: two for the types of interacting +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 +long range interactions between atoms with regard to 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: @@ -114,7 +109,7 @@ 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. +algorithm to this end. You can add the following line in your `in.lmp` file. @@ -137,4 +132,4 @@ 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 +.. _lj/cut: https://docs.lammps.org/pair_lj.html From 0f485c85a822afba897741c5cdc95fca79da6499 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 18 Dec 2023 17:47:19 +0100 Subject: [PATCH 14/32] Revert "Added a mention to the general [Classics] ref." This reverts commit 8cd58c31e58d5eda7c29de2ebf624939a782fad6. --- src/Learning_MD.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index a95b4cf..b7b8203 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -40,15 +40,6 @@ As for now the tutorial is organised in three main sections, mainly: 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 **************** From 7a7ca1813878f0af28210ba8aa88fe48c2cb426f Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 13:47:12 +0100 Subject: [PATCH 15/32] Update src/file_format.rst I agree with this suggestion. Co-authored-by: Shern Tee --- src/file_format.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index cc5ae67..ee5dae1 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -49,9 +49,14 @@ Data file format **************** The first file of the two is usually referred to as a `data file`. Its format -is rather strict and you can see that there are general information at the -top of the file and several sections starting with a capitalized word, a blank -line and some numbers. Let's slowly go through all of this. +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 From a01bbf871d060d1c3226d15383da6bc26b6cc1dd Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 13:47:25 +0100 Subject: [PATCH 16/32] Update src/file_format.rst I agree with this suggestion. Co-authored-by: Shern Tee --- src/file_format.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/file_format.rst b/src/file_format.rst index ee5dae1..fe110e5 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -66,6 +66,9 @@ 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 fa9d9ccb87cfe5bd8e0c64e3473e0d5a690e14ac Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 13:47:59 +0100 Subject: [PATCH 17/32] Update src/file_format.rst I agree with this suggestion. It is more coherent overall. Co-authored-by: Shern Tee --- src/file_format.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index fe110e5..935ae67 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -83,12 +83,8 @@ but all of them must come in the format: 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 -assigned to atom types so you only have one line here. All types have their own -masses but several types can have the same mass. Types are LAMMPS way to refer -to properties of particles that are *the same* for all particles of *the same -type*. They are also used to determine how particles interact with one another. -Types are not always binded to chemical species and you will see in further -tutorials how it can be convenient to define different types for similar atoms. +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: From 4773a5e24b15edd060a0ed08a4ffed1cd01c653b Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 13:52:36 +0100 Subject: [PATCH 18/32] Update src/file_format.rst Accepted suggestion. See my comment concerning the alternative of leaving it out all together. Co-authored-by: Shern Tee --- src/file_format.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/src/file_format.rst b/src/file_format.rst index 935ae67..2c1b806 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -19,6 +19,7 @@ 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 From 83794c0742c6992be631895703b0cabca8aa44f4 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:01:07 +0100 Subject: [PATCH 19/32] Update src/file_format.rst I agree with the rephrasing. See my response. Co-authored-by: Shern Tee --- src/file_format.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index 2c1b806..a955995 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -99,14 +99,15 @@ 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. -The format and meaning of the number in the `Atoms` and `Velocities` sections -will depend on the `atom_style` the code is told to use. In most recents -versions of LAMMPS, writing a data file with `write_data` will append a comment -next to the `Atoms` section name (here `# atomic`). This helps human readers to -know the meaning of the different number. Some formats can include more -information like a molecule tag, particles' charges, particles' spins or -orientation etc. For the velocities, some `atom_style` can require keeping -track of angular momentum, angular velocities etc. You'll find a detailed +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`_. As a first takeaway, remember that `data files` contain detailed information From e8ac14a40cdc2d5e28f1c017cfe54e4f8cf39db0 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:02:18 +0100 Subject: [PATCH 20/32] Update src/file_format.rst Co-authored-by: Shern Tee --- src/file_format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/file_format.rst b/src/file_format.rst index a955995..c51fc03 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -142,7 +142,7 @@ have appeared in your directory. This is a `dump file` containing a single 5 1 0.8 0 0 ... -The format is more simple compared to the data file. Each section is labeled +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 c27c72212b43214d337aa01724225291ec958f10 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:05:36 +0100 Subject: [PATCH 21/32] Update src/file_format.rst Co-authored-by: Shern Tee --- src/file_format.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/file_format.rst b/src/file_format.rst index c51fc03..18e8fca 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -147,6 +147,25 @@ 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. You can compare the `dump file` with the `data file`, and see that they basically contain the same information, with few exceptions, namely the total number of types, masses and the velocities. Getting only the From c9c4f23c693932c49d5c94afeb52158085fe933a Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:06:15 +0100 Subject: [PATCH 22/32] Update src/file_format.rst Given previous accepted changes, it makes sense to also accept this one. Co-authored-by: Shern Tee --- src/file_format.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index 18e8fca..46e16c9 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -166,11 +166,6 @@ 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. -You can compare the `dump file` with the `data file`, and -see that they basically contain the same information, with few -exceptions, namely the total number of types, masses and the velocities. Getting only the -scaled coordinates of the atoms is not alway ideal, but fortunately we can get -much more. In your `in.lmp` file, replace the `write_dump` line with the following: From b0650bc600bd560a59f6fb4e0ae72cd6db512824 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:06:43 +0100 Subject: [PATCH 23/32] Update src/file_format.rst Co-authored-by: Shern Tee --- src/file_format.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/file_format.rst b/src/file_format.rst index 46e16c9..325f6cc 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -167,7 +167,8 @@ 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. -In your `in.lmp` file, replace the `write_dump` line with the following: +As an example of customizing the dump file, +in your `in.lmp` file, replace the `write_dump` line with the following: .. code-block:: LAMMPS From a94cec0580e963be40372026bb9f32d4bcc35732 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:09:35 +0100 Subject: [PATCH 24/32] Update src/setting_up_simulations.rst Co-authored-by: Shern Tee --- src/setting_up_simulations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index cc57013..94f77a1 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -36,7 +36,7 @@ What this script does is: 4. putting atoms at the coordinates defined by the lattice. 5. giving them a mass, and writing output files. -That's it. Nowhere are interaction between atoms defined. As such they do not +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 From 62ebc91d07bda6aaabd4ab76ab57778573f293f3 Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:09:52 +0100 Subject: [PATCH 25/32] Update src/setting_up_simulations.rst Co-authored-by: Shern Tee --- src/setting_up_simulations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index 94f77a1..969a362 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -73,7 +73,7 @@ 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 -long range interactions between atoms with regard to their types. That is the +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 From 547295c5ef3ad01d00a5d903c07aace8dbba380b Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Mon, 15 Jan 2024 14:11:18 +0100 Subject: [PATCH 26/32] Update src/file_format.rst Co-authored-by: Shern Tee --- src/file_format.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/file_format.rst b/src/file_format.rst index 325f6cc..c87b34b 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -110,12 +110,9 @@ 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`_. -As a first takeaway, remember that `data files` contain detailed information -on a simulation system at a given time. They are more convenient for input and -output. Several simulation softwares allow you to export files as LAMMPS -`data files` and take them as input. But data format are not straightforward to -use for analyses: they are heavy and may contain useless information. This is -what the dump file format is for. +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 **************** From 871f8c6a009571a0a5a7cd34ca137cb96f202a26 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:30:56 +0100 Subject: [PATCH 27/32] Some rst formating in file_format.rst. --- src/file_format.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/file_format.rst b/src/file_format.rst index c87b34b..96c3fa2 100644 --- a/src/file_format.rst +++ b/src/file_format.rst @@ -19,7 +19,7 @@ In an empty directory, open a text file and copy the following text inside: .. code-block:: LAMMPS -atom_style atomic + atom_style atomic lattice sc 1. region box block 0 5 0 5 0 5 create_box 1 box @@ -51,8 +51,10 @@ 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") From 79e4a61deb0104dc2d14df6d2c139d0d3533ea9a Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:32:38 +0100 Subject: [PATCH 28/32] Re-added the mention of [Classics] MD texts. --- src/Learning_MD.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index b7b8203..e0e8059 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -40,6 +40,14 @@ As for now the tutorial is organised in three main sections, mainly: 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 **************** From 18528b2c54231ae647759c206bd078672e882fe8 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:33:30 +0100 Subject: [PATCH 29/32] Mentioned the last version of LAMMPS is assumed in the text. --- src/Learning_MD.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/Learning_MD.rst b/src/Learning_MD.rst index e0e8059..18aaaa4 100644 --- a/src/Learning_MD.rst +++ b/src/Learning_MD.rst @@ -24,13 +24,14 @@ 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 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. +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: From 9db8f73741aebe7f495e1e99d53ab3893de69c77 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:38:52 +0100 Subject: [PATCH 30/32] Added links to several commands' manual pages. --- src/setting_up_simulations.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index 969a362..5fdf9cf 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -27,7 +27,7 @@ Let's have a look at the script we used in the first part: the `in.lmp` file. What this script does is: -1. defining a `lattice`, which is simply a set of positions, here all the +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 @@ -39,8 +39,8 @@ What this script does is: 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: +Edit the `in.lmp` file by adding the following lines between the `mass`_ and +`write_data`_ commands: .. code-block:: LAMMPS @@ -59,7 +59,7 @@ 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 +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. @@ -68,11 +68,11 @@ will not interact. :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 +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 +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 From 8e200dc6745d1eac033fa1ed684116c50cff7b7e Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:40:07 +0100 Subject: [PATCH 31/32] Added mention of [Classics]. --- src/setting_up_simulations.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/setting_up_simulations.rst b/src/setting_up_simulations.rst index 5fdf9cf..3e73212 100644 --- a/src/setting_up_simulations.rst +++ b/src/setting_up_simulations.rst @@ -109,7 +109,7 @@ 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 to this end. +algorithm [Classics]_ to this end. You can add the following line in your `in.lmp` file. @@ -132,4 +132,4 @@ 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! -.. _lj/cut: https://docs.lammps.org/pair_lj.html +.. [Classics] Classical textbooks From 245d0b7e7c0f930c1ee5f01c1fc507057d81b0d3 Mon Sep 17 00:00:00 2001 From: Bibobu Date: Mon, 15 Jan 2024 14:42:34 +0100 Subject: [PATCH 32/32] Continued writing of running and post_processing. --- src/running_and_post_processing.rst | 115 ++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/src/running_and_post_processing.rst b/src/running_and_post_processing.rst index 52877f8..58dde2f 100644 --- a/src/running_and_post_processing.rst +++ b/src/running_and_post_processing.rst @@ -4,3 +4,118 @@ 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