LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Mailing List Archives
Re: [lammps-users] making LAMMPS error messages more elaborative
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [lammps-users] making LAMMPS error messages more elaborative

From: Quang Ha <quang.t.ha.20@...24...>
Date: Sat, 21 Apr 2018 15:17:56 -0400

Thanks Axel - I am making my first move now. I don't know how I could start helping with reorganizing and improving the documentation. I do get a bit discouraged when reading through LAMMPS documentation, but over time I have gotten used to it... so I don't know where to get going around that.

On the other hand, I have been trying to modify some error messages. Just to ask for some clarification: the error is triggered by:

error->all(FLERR, "Illegal foo command");

inside foo.cpp. So if I change this inside foo.cpp, should I change something in foo.h as well? Say I was looking at read_dump.cpp, my interpretation is adding the following syntax at the ERROR/WARNING messages comment:

E: Update new illegal foo command - the command is really illegal

Pretty self-explanatory. This is just complimentary text. 

That should be all that need to be changed - am I correct?


On 19 April 2018 at 17:21, Axel Kohlmeyer <akohlmey@...92......> wrote:
On Thu, Apr 19, 2018 at 4:05 PM, Quang Ha <quang.t.ha.20@...24...> wrote:
> Hi all,
> Thanks for all your responses - I guess I underestimate how much of a job
> this would be. Even though Steve said the workload could be pedantic, I
> guess for most commonly-used commands (dump, force, write_restart, etc)
> where non-3rd-party packages are used, this could be improved a bit. As
> these are more or less backbone of LAMMPS, I guess it wouldn't need *that*
> much extra effort to maintain it that way. But, again, this could just me
> being overly naive here.
> Yet I agree with Axel's point - after all (personally) my learning
> experience with LAMMPS have been trying to print out messages where errors
> could have been and debugging around it. So I will leave my naive thought
> here open until there are more willing voices saying we should go forward
> with this. If that shall be the case in a near future, I can humbly offer my
> effort.

from my 20+ years of dealing with open source software projects: if
*you* want to get something done, *you* have to start it, specifically
in a situation where people are not immediately extremely enthused
about a suggestion. nothing is more convincing than a demonstration.
yet, if you would rather want to wait for somebody else to join and
support you, don't waste your time and move on.

mind you, nothing needs to be done completely; often working in small
increments is a better way to get a big task done. using git makes
this particularly easy: create a fork, make a feature branch, modify
just one pair of  .cpp and .h files along the lines of what you think
would be an improvement and submit it as a pull request.

that keeps your initial effort small, you get feedback, and you may be
able to encourage others to join in (e.g. the ones that have
contributed code to LAMMPS). then you can each work on more feature
branches adding more improvements and so on. ...and if your initial
pull request doesn't inspire overwhelmingly positive feedback. you can
just ditch the whole things and move on.

as mentioned before. i personally believe, there is a larger potential
for improvement in reorganizing and improving the documentation.


> Thanks,
> Quang
> On 19 April 2018 at 09:27, Steve Plimpton <sjplimp@...24...> wrote:
>> As Axel indicates, there are trade-offs in how detailed to make
>> error messages.  I think the generic ones you are frustrated
>> wtih are the ones like "Illegal velocity command".
>> The challenge is that for a command with many, many options,
>> there could be 50 variants of that error message, one for each
>> param or whether the param is too big or too small or not a number, etc.
>> Not only would it be tedious to add them all to the code, but as Axel
>> mentioned they also need to be added to the *.h files so
>> the Section_errors portion of the manual can be auto-generated.
>> Personally, when I get that message and can't quickly figure
>> out by staring at the input scriipt line, what i messed up,
>> then I simply look at the line of source code indicated in the
>> error message.  That quickly tells me what portion of the
>> input parsing failed.
>> Steve
>> On Wed, Apr 18, 2018 at 4:06 PM, Axel Kohlmeyer <akohlmey@...24...>
>> wrote:
>>> On Wed, Apr 18, 2018 at 5:30 PM, Quang Ha <quang.t.ha.20@...24...>
>>> wrote:
>>> > Hi,
>>> >
>>> > Since I have gotten better at using LAMMPS (or so I thought) I kinda
>>> > want to
>>> > improve the some error messages - rather than the current 'Illegal foo
>>> > command' ones.
>>> >
>>> > I wonder if this would be a good help on the project - and if there has
>>> > already been other plans on this?
>>> please have a discussion with steve on this subject before you start
>>> anything. he is the best person to tell you what is considered helpful
>>> and what not.
>>> there is a reason why many error messages are so generic: making them
>>> more specific will significantly increase the maintenance effort, and
>>> LAMMPS is already a project that - due to its size and growing
>>> complexity - requires a substantial effort to keep everything
>>> consistent and synchronized. another source of vague or missing error
>>> messages is that they are part of contributed code (e.g. user
>>> packages), so the maintenance effort and the burden to write
>>> meaningful error messages, is on the people contributing the code.
>>> often people contribute something to LAMMPS and then move on and then
>>> maintenance duties fall back on the core developers or the package is
>>> considered abandoned  and will be removed, if the effort to keep it in
>>> sync is larger than the benefit of having it included. final reason
>>> for vague error messages is, that due to the highly modular structure
>>> of LAMMPS, for some code constructs it is very difficult to report
>>> specific errors, since it cannot be reported where it originates or
>>> the behavior is that something is an error unless some optional piece
>>> of code is installed, but the code flagging the error has no simple
>>> way to know what is there.
>>> the LAMMPS developers are regularly discussing how to improve the
>>> situation, but most ideas require more workforce, than what is
>>> currently available.
>>> ...and a final comment: a long time ago, i read through a discussion
>>> on the Linux kernel mailing list, where somebody was suggesting to
>>> implement a more "user friendly" behavior.
>>> the discussion ended with the remark: if you try to idiot-proof a
>>> software, the universe will create better idiots.
>>> in trying to apply this to LAMMPS, i think that a lot of the problems
>>> would be reduced when not the error messages are improved, but rather
>>> the documentation re-organized. that way users are more likely to
>>> spend time studying it, or more easily find the relevant parts. so
>>> that in the end, we get smarter users instead of smarter error
>>> messages. ;-)
>>> cheers,
>>>       axel.
>>> >
>>> > Thanks,
>>> > Quang
>>> >
>>> >
>>> > ------------------------------------------------------------------------------
>>> > Check out the vibrant tech community on one of the world's most
>>> > engaging tech sites,!
>>> > _______________________________________________
>>> > lammps-users mailing list
>>> >
>>> >
>>> >
>>> --
>>> Dr. Axel Kohlmeyer  akohlmey@...24...
>>> College of Science & Technology, Temple University, Philadelphia PA, USA
>>> International Centre for Theoretical Physics, Trieste. Italy.

Dr. Axel Kohlmeyer  akohlmey@...43...4...
College of Science & Technology, Temple University, Philadelphia PA, USA
International Centre for Theoretical Physics, Trieste. Italy.