Join GitHub today
GitHub is home to over 36 million developers working together to host and review code, manage projects, and build software together.Sign up
Improved error messages when a style is not found #1419
The error messages of the type "unknown XXX style" seem to be confusing a number of users, when looking at how often this is asked about on the lammps-users mailing list. This PR tries to address this.
none so far
Axel Kohlmeyer (Temple U)
By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).
The error message now starts with "Unrecognized xxx style" instead of "Unknown xxx style", which seems more appropriate to me.
To achieve checking against which styles are available in non-installed packages, header files similar to the (installed) styles headers are created, but the contain all styles and only styles from packages. This is done by utilizing similar code constructs and implemented for both, conventional and CMake based, build schemes.
Post Submission Checklist
Please check the fields below as they are completed after the pull request has been submitted. Delete lines that don't apply
Further Information, Files, and Links
Put any additional information here, attach relevant text or image files, and URLs to external sites (e.g. DOIs or webpages)
sorry, not seeing the value of this. If a user gets the error message
@sjplimp you are looking at this from the perspective of a developer and a person that is familiar with how to find documentation. most of the LAMMPS users do not fall into that category anymore.
please recall, that one of the most persistent kind of inquiries on lammps-users is that people are completely taken aback by the "unknown xxx style" error message and have no clue what to do next. please keep in mind, that many of them did not compile LAMMPS, or are using some automated, minimal effort scheme, so they are rarely even aware of the fact that there are "packages" in LAMMPS and that not all commands are always available. i attribute part of the confusion to the use of the word "unknown" which is not very indicative of what is going on. most of the times the style is "known", it is not just available. linking those unrecognized styles to their respective packages in the error message helps to separate the two cases, that you mention (is see that as a significant plus for an inexperienced "i am just a user" kind of person; but even have been stumped myself on occasion). and it can also tell about the even more confusing situation, that a package is installed, but the corresponding style is not available, because it is derived from a style in a package that is not installed. please note, that i am not try to auto-correct something here, but provide context to a rather vague error message. as a bonus, we can provide more specific answer when people report those errors on the mailing list.
i agree, that making suggestions for misspellings is probably not worth the effort and trying to correct them on the fly would be a very, very bad idea (anybody using auto-correct on the phone or word processing program can tell what embarrassing and meaningless changes can happen without noticing). but this change can help to reduce a significant amount of frustration and confusion, especially in new LAMMPS users.
i don't want to start a discussion about what has been or is or is going to be a sinkhole in LAMMPS. that is better done in person. but i strongly believe, that having more specific and descriptive error message, for some even with a reference where to look for more info, is as much an improvement to LAMMPS as are improvements to the algorithms and source code. and i believe i am not the only person that is unhappy with the many too generic error messages in LAMMPS, and the fact that many parts of the code are assuming, that a user only creates meaningful inputs or gets everything right the first time (even worse is on the programmer level, but that is another can of worms. and one too big to open now). i have some ideas how to improve the situation, but this is not the place to discuss them.
I think that suggesting the package is a nice formality since the act of recognition provides more integration with the whole code if it is a package mismanagement. Definitely shouldn't spend time trying to identify close misspellings however, that becomes a very cumbersome block of code with strings, since that's already the only possibility. Even if its not done for every message at this point it seems like a case of the more the merrier.
This is not necessarily true. Every line of code has a cost of maintenance, and the burden will be passed on to other developers in the future (no developer works on the code forever).
A few more thoughts ...
I'm trying to balance user needs with code volume and complexity. Basically I don't want
More generally if a user doesn't know how to find/use the command doc pages, I'm not really
So we could make a more wordy generic error message, e.g. unknown vs unrecogznized,
Or we could tell them what package the command is in. For all styles, for
Re: non-satisfied dependency. I think that's a build problem, not a run-time problem.
On Mon, Apr 8, 2019 at 3:56 PM Steve Plimpton ***@***.***> wrote: A few more thoughts ... I'm trying to balance user needs with code volume and complexity. Basically I don't want to add code for things that don't provide enough value to the user. I'm not clear which side of the line this is on. The examples given in the PR header don't seem to me to be of much value. The current code already does the first case. The other 2 for /gpu and /omp seem obvious. If a user doesn't know those files are in the GPU and OMP packages, how are they going to run LAMMPS with those packages enabled with their various options?
those are just illustrations of what the error messages look like under different conditions, they are not meant to be representative. more common is for for example, people using fix shake without the RIGID package.
More generally if a user doesn't know how to find/use the command doc pages, I'm not really seeing how they can write interesting input scripts. E.g. how to use a new pair
a lot of them, especially beginners, are not writing them. they are hand-me-downs from other people, with the occasional edit and change of data file and potential parameters.
style w/out looking at the docs for the pair coeff args. Ditto for using a fix or compute and their options. So telling them to look at the command's doc page to find the package it's in doesn't seem onerous. If a new user doesn't know how to do that yet, helping them learn how is a good thing.
then you should keep in mind, that this will result in more e-mails that need answering on the mailing list, and the kind that somebody else than me has to answer (which is not happening as much as it used to, i might add), as they are starting to drive me nuts.
So we could make a more wordy generic error message, e.g. unknown vs unrecogznized, you either misspelled it of look on the command's doc page to fine the package, etc. Or we could tell them what package the command is in.
but this is what this change does!
For all styles, for both make and CMake. Is that what this code does? I'm not seeing how it works for make, since the new packages() command in Make.sh looks similar to style() which only searches installed files. Are you also somehow searching thru all the un-installed files?
yes. you are overlooking that the script now calls $cmd, which is set to styles for Make.sh styles and to packages for Make.sh packages. The packages functions loops over all headers in all sub-directories, and thus collects *all* styles from all packages installed or not. while the styles function only looks in the src folder and thus only finds installed styles.
If that's what this code does (or where you're headed), I could see that being useful. Re: non-satisfied dependency. I think that's a build problem, not a run-time problem.
no, that is the build system working correctly!! if you install the USER-OMP package, but not the KSPACE package, then you have, e.g. lj/cut/omp, but not coul/long/omp. yet the USER-OMP package is installed. so if the error message says: you don't have coul/long/omp which is in USER-OMP, the user can say, but i *do* have USER-OMP installed, hence i wrote the message for this case, that the style is not installed, because a dependency is not satisfied (coul/long). i am open to use a different text, if this is misleading.
Building with make never does that, correct? The dependencies get enforced each time you include/exclude a package. Does CMake not do that? If so, I think that's something that should be enforced by the CMake build, not by run-time error checking.
the point of the error message and the fact that it gets triggered shows that the dependency tracking is working. —…
You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#1419 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARp45biPCxCiqCEfKfVtw07pzzeV7Haks5ve57wgaJpZM4ch4qf> .
On Mon, Apr 8, 2019 at 1:41 PM Stan Moore ***@***.***> wrote: you should not worry about this causing effort, because it is not causing effort to you This is not necessarily true. Every line of code has a cost of maintenance, and the burden will be passed on to other developers in the future (no developer works on the code forever).
then you should (at least to a large part) welcome my change, because the changes in force.cpp and modify.cpp and so on, make the code there more maintainable and put the more nasty assembly of the error message and the checking of the styles into the utils:: namespace function. i've tried to maximize code reuse in Make.sh (up to the point, where it confuses @sjplimp apparently) and in CMake (with less success). if somebody has a simpler and cleaner way to assemble the same information, i am all ears. i'm not happy with all the files it generates, but i thought, that this would be more familiar and thus easier to maintain, because it is so similar to the processing of style headers.…
— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#1419 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARp40YwnO08p8W3Bnswwb0ZeciBGr-3ks5ve386gaJpZM4ch4qf> .
On Mon, Apr 8, 2019 at 4:56 PM Stan Moore ***@***.***> wrote: then you should (at least to a large part) welcome my change It is more the attitude of "I'm going to do whatever I want because it doesn't affect you" that concerns me. Because it does affect me!
you are misreading me.…
— You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#1419 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARp40hZR18wT52SpuLZX9_jmI-6mP43ks5ve6z6gaJpZM4ch4qf> .
I agree that this error is too vague and comes up too often on the mail list. One time a
@akohlmey Unfortunately misreading someone’s words online isn’t hard to do when there is no tone of voice or non-verbal cues. To me, this:
“you should not worry about this causing effort, because it is not causing effort to you and is as much automated and in need of maintenance as the system creating the style files. and you should not worry about wasting time, since it is my time that went into this. and i don't mind.””
sort of sounds like this:
“I'm going to do whatever I want because it doesn't affect you”
Anyways, I just wanted to make sure that we are not adding complex code to core LAMMPS without considering that some other developer will have to maintain it in the future.
i was trying to point out, that i tried my best to keep the maintenance effort low, by following what is already done for the style_xxx.h files and trying to re-use as much code as possible. this part of LAMMPS has been extremely stable and with rather few changes over the years.
the changes to the force.cpp and modify.cpp and so on with the utility function, i consider a genuine improvement, so i would want to keep that, even if we cannot agree on storing and printing out the package name, if a style is missing in the executable because of a missing package or a missing package, the style depends on.
the rest is a one time effort of doing the implementation and testing it. it was more effort that i expected, but for a helpful (i think) improvement, i didn't mind that extra effort.
since this PR has had more concerns and questions than usual, i am not going to merge it until there are more approvals than we usually require. so please request changes to block the merge until your concerns are (mostly?) addressed or approve if you are (mostly?) OK with it.