Extend support for fix_modify to remaining script API commands

[giacomofiorin]

This PR extends the interface introduced in #216 while taking advantage of the scripting API enhancements from #316.

The LAMMPS command fix_modify is used as the main command, which behaves much in the same way as the cv command in the Tcl codes (VMD and NAMD). Compared to Tcl, however, functionality is more limited: the commands' string output cannot be captured and used as-is in conditionals (only printed to a separate log file).

An additional LAMMPS-specific limitation is that full initialization of the module is done upon the first run command, due to how the LAMMPS data structures are initialized. The associated tests reflect this by assigning a configuration file to the fix upon definition, running run 0 and then loading additional configuration (i.e. adding a restraint).

To properly document the feature, I introduced a distinction in the manual between scripting API and callbacks, which are separate (at the moment, we support only the former in LAMMPS).

I'm opening it as draft, since I still need to check or work on the following:

• [ ] Requesting additional atoms after those that were requested when the fix was initialized.
• [ ] Double check the doc (this change was fairly intrusive), e.g. identify all remaining scripting commands that would not be supported.
• [ ] Allow to modify internal parameters of the fix object consistently with those of the module (the script API currently ignores the fix object).

[akohlmey]

Compared to Tcl, however, functionality is more limited: the commands' string output cannot be captured and used as-is in conditionals (only printed to a separate log file).

There are ways around this limitation. You could have a "variable" or "output" keyword that takes a variable name as argument and then can have the return value/text/string/whatever assigned to that variable. Check out what the KIM package in LAMMPS does with e.g. kim query.

[akohlmey]

On top of using fix_modify you could also have a custom colvars wrapper function in the library interface. While that doesn't give you access to library functionality in LAMMPS input files, but you could make it available from Python (or other script languages including Tcl (via swig)).

[giacomofiorin]

Yes, passing a LAMMPS variable as argument is one of the option I was thinking about. Thanks for pointing out the kim example! And of course, the library interface (C and Python) is the optimal way to go in general. Now that you and @rbberger have streamlined a lot the installation process, wrappers would be much easier to add.

At the moment I'd like to have all use cases that don't need the deeper library interface sorted out this way.

If possible I would like to have the fix initialized after the fix command, so that subsequent uses of fix_modify can operate on it immediately. Is there any case when a fix's setup() function is called before the next run command?

[akohlmey]

If possible I would like to have the fix initialized after the fix command, so that subsequent uses of fix_modify can operate on it immediately. Is there any case when a fix's setup() function is called before the next run command?

No. Any such initialization would have to be called from either the constructor or - if it needs access to the virtual function tables somehow - from the post_constructor() function.

[giacomofiorin]

Ok, so what I guess we can do is create both the fix and the module at the same time, but only initialize the latter as empty, and wait until setup() to fully initialize it.

The advantage would be that we can allow multiple calls to fix_modify supply multiple configuration parameters and/or files, which would help when some of those parameters/files are given upon certain conditions only.

[giacomofiorin]

@akohlmey After further testing, the changes seem to work okay for me. However, given that the LAMMPS Summer 2023 stable release is due this week, it seems easier to not submit it at this time. Including these and other improvements together in the next patch release seems like the best option.

[akohlmey]

However, given that the LAMMPS Summer 2023 stable release is due this week

I have to push that date. Probably to mid-July. Nevertheless, this seems better done after the stable.