(write|read)_restart flexibility

[Matthew-Whitlock]

Summary

Add an optional FileWriter-based write_restart and read_restart API to Fixes,

Related Issue(s)

Demo for #4899

Author(s)

Matthew Whitlock, Sandia National Laboratories, matthew@mwhitlo.dev

Licensing

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).

Artificial Intelligence (AI) Tools Usage

By submitting this pull request, I confirm that I did NOT use any AI tools to generate
all or parts of the code and modifications in this pull request.

Backward Compatibility

This should maintain backward compatibility.

Implementation Notes

There is a new Restartable class that restartable LAMMPS objects should extend. The Restartable class defines the global vs local restart functions, leaving the peratom functions as-is. Restartable also defines the default shims for callers using the old all-in-one FILE* api on objects that implement the new global/local restart functions.

There are four new "FileWriter" types:

1. A FileWriterSizer that just counts up the size of things "written" to it
2. A FileWriterBuffer that serialized to a provided buffer
3. A FileWriterWrapper that writes to a provided FILE* without taking owership
4. A FileWriterRootWrapper that works just a FileWriterWrapper but ignores writes from ranks other than rank 0, as a convenience.

FileWriter gained a few new functions. Two (very simple) template functions to simplify writing typed data, and two functions for writing the size of a given 'Restartable' object. Making virtual functions for writing the size of the objects is not entirely necessary (callers could just make a FileWriterSizer themselves), but it simplifies things for the typical caller and will help avoid problems with sizing the same object three times if sizing-then-writing an object with nested objects.

There are new "BufferReader" types:

1. BufferReader: Simply takes an input 'untyped' char* data array and offers convenience functions for reading consecutive typed data values from it
2. BufferReaderFile: Uses a file as the input data buffer, instead of an array.
3. BufferReaderRootFile: Rank 0 uses a file as the input data buffer and broadcasts each read to remote ranks.

Post Submission Checklist

• The feature or features in this pull request is complete
• Licensing information is complete
• Corresponding author information is complete
• The source code follows the LAMMPS formatting guidelines
• Suitable new documentation files and/or updates to the existing docs are included
• The added/updated documentation is integrated and tested with the documentation build system
• The feature has been verified to work with the CMake based build system

Further Information, Files, and Links

[Matthew-Whitlock]

This now looks like it requires a lot of changes, but most of them are not hard requirements. The majority of the changed lines of existing code are in read/write_restart - I rewrote their functions in terms of FileWriter and BufferReader to allow checkpoint modules to use those functions directly. That way checkpoint modules don't all need to be updated individually if new flags or features are added. I did the same for the restart functions for LabelMap and Group, for the same reason.

But if this is looking like too much code change all at once, I am happy to revert those changes and leave it to checkpoint modules to manage directly.

[akohlmey]

@athomps @sjplimp I think we should have a serious look at this together when I come over in a couple of weeks.

@Matthew-Whitlock Thanks for creating this branch to demonstrate what you have in mind. This will make it much easier to discuss. I like the concept and where this could be heading, but I am also concerned that this may be one step too far for us given that at the moment we are lacking workforce more than before. I don't want to have to get into a situation similar to what we have with supporting two build systems and having a very, very slow transition that makes life harder for everybody involved. I would rather prefer to have one big disruptive change and then move on. But then again, I am only one of many and we are always looking for as large a majority as possible when making big decisions.