WIP: Backbone of a tutorial

[Bibobu]

Summary

This is an initial PR to provide a basic outline for the tutorials and a first step on organizing the project. As Slack channels have finite lifetime, it can also be used as a place to make long term todo lists discuss goals.

Details

This PR provides some initial files for discussion in the project of making detailed LAMMPS tutorials for newcomers. In previous discussion on the Slack channel, many different views on the directions the project could take emerged.

Given the variety of profiles of people asking reference, I suggest an initial division in three stages sorted by topic complexity from the very basic to more advanced stuff. If the initial stages shall be guided and pedagogical (maybe in a linear fashion), the latter might be thought as independent sections for more autonomous users. The idea is to start with guided hands-on to autonomous hands-on tutorials, keeping a "do it yourself" approach at the center.

The initial proposed stages are:

• Beginner: Very basic stuff from how-to format input to how-to analyze a log file and visualize a trajectory (ffmpeg? very short intro to OVITO? or VMD?) with variables, compute and fixes introduction in between.
• Advanced: Introduction to advanced stuff from extended hamiltonians and fixes combination to replica exchange or other simulation techniques. Many sections of the how-to could be detailed here to illustrate more general concepts.
• Confirmed: maybe detailed examples of Python coupling or step by step guide of a small library example. This might be an introduction to the developer guide section and a complement to the "coupling LAMMPS to other code" section of the how-to.

This is a work-in-progress as many things need to be settled down, some important axis need to be discussed and most of the proposed sections need to actually be written.

I don't know how this could make use of the Github Project system.

[simongravelle]

Hello,

This is my first time commenting on a pull-request from vscode, so I hope that it will be simple for you to see/accept/reject my comments/suggestions.

Thank you very much @Bibobu for starting the project with a very nice simple tutorial. I did some tiny eddit to the text, feel free to reject them.

Some very generic comments:

• we should choose between american and british english. I suppose american is the most obvious choice here?
• I would impose from the start the LAMMPS version people have to use to follow the tutorial without trouble. Ideally the last stable version.
• is '.lmp' a convensional extension for LAMMPS data file? I am personaly using '.data' as it gets recognized directly by MDAnalysis...
• side note: I wonder if using LJ units for the very first tutorial makes it easier for beginners, or harder... on the one hand, we don't have to deal with units conversion, which is great , on the other hand, LJ units are counter intuitive and writting "pair_coeff 1 1 1 1" may seem bizare. I have the same interogation on lammpstutorials.github.io were I also use LJ units on the first tutorial.

Best,
Simon

edit: OK it seems that I have pushed my changes directly into the PR. Sorry @Bibobu, that was not my goal, I was hopping that the changes would appear more as "suggestions", as it does on Gitlab.

[Bibobu]

Hi @simongravelle,

To answer your questions/remarks:

• I agree american english makes more sense. I was taught british english but tend to mix the two if I am not careful. I'll try to stick to AE and set my spellcheck to do so.
• Asking to use at least the last stable version is a good idea. I think this is the one deployed on major Linux repositories. But I am unsure and I do not know who do the several packaging. This would make things consistent for people downloading and installing it through package managers.
• I personally use *.lmp as an extension as this is one of the extension for the vim syntax highlighter provided in the source repo along with in.* and *.in. I think this is also a convention to settle. This is not very important for LAMMPS itself but it should be consistent throughout the tutorial.
• I have the same question with regards to LJ units. But as a physicist by training I might be biased as dimensionless units feel very natural to me and more convenient. Maybe it is better to start using a real life example and show how to convert from there. I don't know.

I think your changes corrected typos and homogenized the overall text. So it's all good. Besides there is not much really fixed for now.

[Bibobu]

I also thought about making a "Common problems" files in the same spirit as the one that is already in the manual and the pinned post of the forum but:

• This might be redundant.
• The two mentioned sources might be edited and completed.

However, many people still come to the forum in a "see this, what do?" spirit, so maybe giving a first list of things to check when getting an error in a tutorial might make sense. If this tutorial ends up being linked to LAMMPS main communication channels this might be the place where people head to before the forum or the manual. (Not getting optimistic here, simply pragmatic.)

[akohlmey]

@Bibobu thanks for moving this forward.
I am a bit biased in this respect, but I think for the Beginners section it may be advantageous to use the LAMMPS-GUI first.
It wasn't ready for the LAMMPS workshop in August, but I've been receiving good feedback from multiple people. This can't do what the specialized tools can do, but is sufficient for the simple stuff if used in a smart way. Thus learning how to use OVITO or VMD or other tools for system generation, analysis, and visualization could be done toward the end of the section. If needed, I can add missing functionality, but at the moment there should not be much left except for features that are very difficult to add.

A "Common problems and solutions" document can be hosted anywhere and then other places that people might find would contain a link to that. I would not worry too much about people not search for this first. Some people cannot be helped, they will always post immediately if they encounter an issue. But everybody else that has not looked in the right place or not looked at all could be embarrassed by being pointed to the page and then look at it in the future (provided it contains the information being looked for).

[srtee]

General editing, with the comment that (for me at least) in good teaching, we try to give as little information to the student as possible at any one time, on the assumption that it will already be a lot of information for them to absorb -- some statements seem simple to an expert because we "don't know what we know" but will be very confusing to a student. For example, maybe we should completely remove all atom_style references and introduce atom_style in a next lesson, for example, when showing them a dimer molecule.

[Bibobu]

Thanks for your inputs @srtee. I continued writing and didn't see your comments so I committed and reverted back my changes. I'll take a detailed look at the conversation during the week.

To comment on @akohlmey answer, I think the "visualisation" part which IMO should come after analyzing thermo data should give a large part to the use of LAMMPS-GUI in a dedicated section. But I think it should be introduced after showing how to produce images in LAMMPS through the dump command. Also VMD and OVITO also provide a lot of computation options but, in my opinion, it is important to emphasize on time averaging in analyzing MD data, as I think many people tend to get stuck on "instantaneous values" computation due to these software limitation. I think visualization acts as a strong distraction with regard to this, so I would carefully introduce them later. LAMMPS-GUI allows for better understanding of what I consider a proper workflow. Note that this is not to downplay VMD or OVITO which are great, but I think self-teaching of these is prone to bad habits. (Let's not mention people drawing conclusion from instantaneous images without proper analysis of configuration when this is clearly needed.)

Any thought?

[akohlmey]

@Bibobu I suspect we are talking about two different types of visualization here. What LAMMPS-GUI can do and is good for is a quick look of the kind "does my system look like what I expect?". This is often extremely useful when people create systems from the "create_atoms" command with regions. Also, as I mentioned, I think an addition to the Image viewer in the LAMMPS GUI that provides the command line that looks good (the defaults of dump image are often not good) can be helpful.

Any serious visualization can come (much) later. The issue is that a lot of problems with inputs created by beginners would be better understood, if they would look at a rendering of their system. A common thing among beginners seems to be (or at least those that post their questions on MatSci) that they assume the system was created according to their expectations, even if the energies say it wasn't. For example, they didn't notice the need for using "units box" or similar. That is why LAMMPS GUI has the features it has minus what would be nice to have but could not be implemented due to limitations of the library interface or my programming skills or available time and interest.

[Bibobu]

@srtee I finally found time to take a look at your suggestion and agreed with them all. I agree that it is complicated to find a balance between what to tell and what not to tell to avoid overloading readers with information. However, I take into account that a written tutorial can be read at one's own pace, contrary to a class from which notes might be less complete. I would like to keep the discussion introducing the atom_style command but I agree that it might just conclude with something along the lines "Keep in mind it exists, more on it later."

[simongravelle]

@srtee I finally found time to take a look at your suggestion and agreed with them all. I agree that it is complicated to find a balance between what to tell and what not to tell to avoid overloading readers with information. However, I take into account that a written tutorial can be read at one's own pace, contrary to a class from which notes might be less complete. I would like to keep the discussion introducing the atom_style command but I agree that it might just conclude with something along the lines "Keep in mind it exists, more on it later."

What about colored text block (even possibly drop-down text block) just like the one used in the LAMMPS documentation for the Note and the Warning ? It could be a class "Info" that give more information to the interested reader, but can also be skipped without affecting the results of the tutorial?

[Bibobu]

What about colored text block (even possibly drop-down text block) just like the one used in the LAMMPS documentation for the Note and the Warning ? It could be a class "Info" that give more information to the interested reader, but can also be skipped without affecting the results of the tutorial?

That would meet us halfway. If @srtee is okay with that I can make an edit and add a section in the intro to mention that some "Info" blocks can be skipped on first read. I think a block name like "Advanced topic" would be more explicit to the reader. But it will then be important to not overload the text with those. ^^"

[srtee]

Hi! Coloured text blocks would work fine, I'm okay with that. Thanks for all the thought and discussion from everyone.