-
Notifications
You must be signed in to change notification settings - Fork 3
WIP: Backbone of a tutorial #1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Bibobu
wants to merge
32
commits into
lammps:main
Choose a base branch
from
Bibobu:main
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
32 commits
Select commit
Hold shift + click to select a range
af3d2ff
A first commit with some initial description of the
Bibobu c700bad
Some edits to continue the initial lesson.
Bibobu 8ded3f9
Added a basic structure of the tutorial in three steps. Added simple
Bibobu 59c61e2
made some minor changes to the text
simongravelle da47092
Added labels to files at the top.
Bibobu c88f9a5
Changes visualizing file name to american english spelling
Bibobu 70641e3
Corrected a file name in Beginner.rst
Bibobu 1cc9d24
Adding the end of the file setting_up_simulations and reference to
Bibobu 8cd58c3
Added a mention to the general [Classics] ref.
Bibobu d8c1bc0
Homogen. references to commands, added some [Classics] ref.
Bibobu c353468
Continued the writing of running_and_pp.
Bibobu af102ea
Revert "Continued the writing of running_and_pp."
Bibobu 8767856
Revert "Homogen. references to commands, added some [Classics] ref."
Bibobu 0f485c8
Revert "Added a mention to the general [Classics] ref."
Bibobu 7a7ca18
Update src/file_format.rst
Bibobu a01bbf8
Update src/file_format.rst
Bibobu fa9d9cc
Update src/file_format.rst
Bibobu 4773a5e
Update src/file_format.rst
Bibobu 83794c0
Update src/file_format.rst
Bibobu e8ac14a
Update src/file_format.rst
Bibobu c27c722
Update src/file_format.rst
Bibobu c9c4f23
Update src/file_format.rst
Bibobu b0650bc
Update src/file_format.rst
Bibobu a94cec0
Update src/setting_up_simulations.rst
Bibobu 62ebc91
Update src/setting_up_simulations.rst
Bibobu 547295c
Update src/file_format.rst
Bibobu 871f8c6
Some rst formating in file_format.rst.
Bibobu 79e4a61
Re-added the mention of [Classics] MD texts.
Bibobu 18528b2
Mentioned the last version of LAMMPS is assumed in the text.
Bibobu 9db8f73
Added links to several commands' manual pages.
Bibobu 8e200dc
Added mention of [Classics].
Bibobu 245d0b7
Continued writing of running and post_processing.
Bibobu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
.. _averages-calculations: | ||
|
||
===================================================== | ||
Using averages and computing values during simulation | ||
===================================================== | ||
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). | ||
|
||
Bibobu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.