Getting started guide for posting LAMMPS questions to MatSci.org

Hi everybody!

As the traffic in the LAMMPS section of MatSci.org is increasing and since a significant fraction of those posts are by people that are new to the forum and/or new to LAMMPS, I have a feeling that we need to assemble some kind of Getting Started Guide™ that lists the most important things to do and to avoid when posting here.

Thus I am reaching out to everybody that has been responding to questions, or that is fairly new to the forum and thus remembers how it feels to be new and without clear guidelines and respond to this post with short 1-2 sentence recommendations. Since I hardly qualify as “new”, I will instead focus on the job to edit the suggestion, combine the most useful parts to a webpage on the LAMMPS homepage and then try to get the URL inserted into the category description.

Thanks in advance,
Axel.

4 Likes

Use ``` for input files and other pasted text

3 Likes

Hi everybody,

This is what I answer to co-workers who ask me: Should I ask this question to the LAMMPS forum? (the reason they ask me first is that people are usually scared of receiving a public roast by you Axel :smiley: ):

  • post a minimalist input file that reproduce the error - this one is crucial, but almost never done
  • make sure a similar question was not already addressed on this forum by hitting the search button
  • make sure you read the documentation corresponding to your main commands
  • indicate your LAMMPS version

Simon

6 Likes

I would add to Simon’s comment that there is a conflict between what the forum (and the late mailing-list) were set up for and what people tend to think they are for.

So something along the lines:

  1. Do
    • Be specific: State your problem as clearly as possible. People cannot provide help if they have to guess half of the situation from a vague description.
    • Make your post readable: The forum uses a MarkDown format and offers you preview of your post. Please take a minute to read about it and format your post.
    • Following that, use fenced code block format to copy your input files. (this is similar to @stamoor’s remark)
    • Use tags and categories: When creating new posts, read all the sections and tags in the top menu. Question specific to LAMMPS usage go to the LAMMPS category. Generic scientific question concerning MD, physics/chemistry or general science should go to Science talk.
    • Keep it nice, be patient: Answers to your problem will be given by people taking on their time to provide insights or advices. Let’s keep it precise and gentle.
  2. Don’t
    • Expect a MD course: Like all scientific practice, molecular simulation is a complicated topic. Which is better learned through guidance from skilled advisor coupled with trial and error.
    • Ask for simulation design: You are the only person that knows what you try to achieve and the best way to found how to fill your needs is to go through the scientific literature and read from other peoples’ work.
    • Ask for tools other than LAMMPS: This is a LAMMPS forum. While VMD and other tools for MD are close to LAMMPS and have common developers, they are not LAMMPS. Go to the relevant places to ask questions about them. (OVITO for example has a dedicated section on the forum. VMD has its own mailing-list)
    • Make a post simply because you get an error: Error messages are often descriptive of what went wrong. Take time to read and understand them. See also the error section in LAMMPS documentation with more complete description of common errors and solutions.

I was thinking about how this kind of guidelines would look like so here is my shot at it for the moment. Some of those were based on peoples own recurrent comments here (I guess they will recognize themselves. :stuck_out_tongue: ) Hope it helps.

2 Likes

Always read the documentation of your commands in details, the notes on them, and related commands, and search the forums using different wording. Read the forum’s new topics title every day to learn more.

The LAMMPS forum is not Science Talk

This forum is dedicated to discussing LAMMPS, and the volunteers here focus on helping with LAMMPS, not general scientific queries. Here are some typical queries that are out of scope for this forum, with explanations:

  • “How do I turn mercury into gold with LAMMPS?” You need to do a literature review, and we don’t provide that service.
  • “I tried turning mercury into gold with LAMMPS, but then a “PPPM: Particles out of range” error happened!” You need to form a hypothesis about what happened and vary some variables to test it, and we don’t provide that service.
  • “I wrote a script to turn mercury into gold with LAMMPS, could anyone check it?” As above, and also see “We do not know your field”.
We do not know your field

We are typically not experts in your research. So if some detail of your research is important to the problem you are facing, you are responsible for explaining your area of expertise. Please do not use specialist terminology, abbreviations or initialisms without explaining them first – pretend you are giving a talk at a generalist conference.

As a very important corollary, we do not know what your system is supposed to do, and we do not know why your system is doing something else instead. I do not know enough about the molecular intricacies of water to know why it boils at 100 degC in real life, and if you want to know why it boils at 80 degC in your simulation I will mumble something about checking your force field. An important exception is that if you are trying to replicate an MD simulation reported in literature, I will usually be motivated to read through that paper and see what might be missing from your attempted replication, since replicability is central to science.

Start small before building complexity

You should (even before you run into errors) build small, simple systems that give straightforward results that you fully understand, before adding in complexity. For example, you should simulate a polymer at equilibrium before trying to shear it, and you should simulate a liquid at uniform temperature before trying a thermal gradient. You should not use polarisability, many-body potentials, or ReaxFF, unless you can clearly justify the extra accuracy compared to nonpolarisable, pair potential, or non-reactive simulations respectively.

Small systems (in terms of volume and particle number) are also very valuable because they run faster, crash faster, and are faster to visualise. They therefore save you lots of time. Also, fluctuation magnitudes (and thus, notably, diffusivities) change in interesting ways against system size, and the easiest way to convince yourself that a simulation is “big enough” is to simulate something slightly larger and see that there is no change in your (intensive) observable of interest.

Don't use ReaxFF if you're not studying a very reactive system

I know I just said it, but that’s how often it needs saying.

Your system just does what your force field and equations of motion say

The foundational inputs to LAMMPS are your force field – that is, given a set of coordinates, what the forces between particles are – and your equations of motion – that is, are particles’ velocities and positions altered in any way beyond Newton’s laws. Almost all LAMMPS (indeed, MD) problems boil down to either inappropriate force fields or inappropriate equations of motion.

Force fields are tricky beasts and you should tell us clearly what force fields you are using, with a reference if possible. Note that a force field is the complete description of all interactions between all particle types in a system, and mixing different coefficients from different publications creates an all-new force field. So, for example, MD simulations of DMSO with water show different miscibilities depending on whether SPC/E or TIP3P parameters are used (https://pubs.acs.org/doi/abs/10.1021/jp0007336).

Force fields are more than pair coefficients

A force field covers more than just the Lennard-Jones coefficients. You cannot fully specify the forces between particles without also stating:

  • Combination / mixing rules
  • Truncation / smoothing rules
  • Tail corrections presence / absence
  • Kspace algorithm and accuracy
  • Intramolecular / bonded exclusions (1-2, 1-3, etc)

In practical terms, you should report your pair_modify and special_bonds lines, or look up the defaults and report those if you haven’t changed them.

"fix nve" and similar are integrators, not ensembles

The fixes fix nve, fix nvt and so on are integrators – that is, they update particles’ positions based on the calculated forces. While these integrators can include thermostats or barostats, these -stat components do not ensure that your simulation samples a particular thermodynamic ensemble, unless no additional forces are imposed.

To drive this point home, consider the following script fragment:

fix 1 all setforce 0 0 0
fix 2 all nvt temp 300 300 100

The fix nvt integrator is used here, but clearly LAMMPS cannot sample the NVT ensemble using this script.

2 Likes

Is there any way we could make a default template that shows up when creating a new thread? Similar to an issue on Github. It could include a reminder to list LAMMPS version and anything else that needs reminding.

4 Likes

This required some digging around with google. I found this: Topic templates for categories and other alternatives - Site Management - Discourse Meta
It is not available to us, but requires full administrator permissions. So we would have to draft a suitable template and then ask to set it up for the LAMMPS category (and possibly for the sub-categories as well).

Same as with github, this may include HTML comments with instructions that would not show in the posted message. The following

<!-- Please state your exact LAMMPS version -->
LAMMPS version:  15 June 2023

Would render as:

LAMMPS version: 15 June 2023

2 Likes

@akohlmey, following your comment here I took the liberty to edit and complete your draft file taking both some content of the guidelines file and this forum responses as sources:
LAMMPS-forum-readme.txt (8.6 KB)

I think this adds some significant content already and goes over most of the issues that this thread aimed at addressing.

Please tell me what you think. IMO this makes it quite decent as a pinned post for newcomers already with only a bit of tweaking.

1 Like

Thanks. Much appreciated. I’ve made a few updates and will post this now.

I wonder if it may help to split the post up into several posts in one thread, rather than the current “details” arrangement. For example we could link people directly to a “How To Format LAMMPS Inputs” post instead of linking people to the whole post and hoping they expand the correct details section.

Let us keep the current post in place and monitor for a few months if it makes a significant difference.
If not, we can consider alternatives. It always takes some time until we notice the effect. It also matters how diligent and consistent we are in reminding people.

My preferred arrangement would be to have a post with just the minimum remarks and then links to pages on the LAMMPS homepage and also a more detailed guide (based on the current one) that also uses those references. In addition, we could have a common questions and answers section where we collect recurring questions and try to provide and edited response taking the best from the various responses over time. I had done that a loooong time ago for CPMD and they still have it as part of the manual https://github.com/CPMD-code/CPMD/blob/eaeb1a977fabe570e7a4e2ca1dca53e8f360b054/doc/manual/manual.tex#L10335

The main problem of doing things right now is time. It was much easier during the pandemic, where I had much more time. This is diminishing now, but actually the amount of work for managing the LAMMPS GitHub and the forum is (still) growing. …and there are still so many things that need to be done. You can always tell when I am feeling overwhelmed, because that is when I make my life even worse by going on a tangent and pour time into something else with a lot of “hack value™” (like the LAMMPS GUI thing currently). Because it is a small project, it is not as overwhelming and progress is comparatively fast, but it also needs a lot of figuring out (I have not programmed a GUI application from scratch in over a decade and not programmed with Qt for more than 20 years). And figuring out things is the fuel that (most) scientists run on.

2 Likes

I forgot that we already has such a thing in the manual at: 11.1. Common problems — LAMMPS documentation
But it is lacking structure and thus probably overlooked by many. So I am thinking that this may be the starting point for a common problems and answers section. But it would be important to first provide the information that describes the problem with sufficient detail (e.g. output) so that people can find it from a web search. There should be descriptive headlines for sections focusing on different aspects.

1 Like

A good way to give it structure might be to add titles containing generic questions we often see on the forum:

  • LAMMPS throws an error, what should I do?
  • Command XXX does not do what I want, there is probably a bug.
  • How do I convert lj units to real units?
    Etc…

It could then be linked in the read first post. I am a but busy a.t.m. but I might find some time in the coming week to write something and PR on Github if this is suitable.

I keep forgetting about this, but there is actually a stackexchange site that would be a complement matsci.org and where - among others - also LAMMPS questions are posted.

But it suffers from the same problem that the Science Talk - Materials Science Community Discourse category has: most posts go without a response. In theory, a stackexchange site would be the perfect complement to the discourse site.

I am a frequent poster there too – most of the active people there (besides me) seem to be DFT experts and less involved in statistical mechanics.