Add granular surfaces built from triangles (3d) or line segments (2d)

[sjplimp]

Summary

Add capability for granular surfaces to be used in conjunction with granular particle models. Surface in this context mean a collection of triangles (3d) or line segments (2d). This is to allow more geometrically complex objects and boundary conditions to be represented within granular models.

Two flavors of surfaces are planned.

(1) Global surfaces, where a copy of the collection of (large) triangles is stored by every processor.
(2) Local surfaces, where the collection of (small, roughly particle-sized) triangles is distributed across processors
in the same way that particles are.

Related Issue(s)

N/A

Author(s)

Steve, Joel Clemmer (SNL), Dan Bolintineanu (SNL)

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

Backward Compatibility

N/A

Implementation Notes

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 conventional build system
• The feature has been verified to work with the CMake based build system
• Suitable tests have been added to the unittest tree.
• A package specific README file has been included or updated
• One or more example input decks are included

Further Information, Files, and Links

[akohlmey]

FYI, translating the manual results in the following reported issues:

Fix style entry surface/global is missing or incomplete in Commands_fix.rst
Fix style entry surface/global is missing or incomplete in fix.rst
Found 2 issue(s) with style lists
fix index entry surface/global is missing
Found 1 issue(s) with style index
Found 92 packages
Package GRANSURF missing in Packages_list.rst
Package GRANSURF missing in Packages_details.rst
Found 2 issue(s) with package lists

[akohlmey]

All doc pages for new commands should have a .. versionadded:: TBD so that they'll list the version where this feature appeared. For new sections to existing commands, e.g. molecule, the tag should be added with the new paragraph describing the added feature.

[akohlmey]

@sjplimp FYI, I updated the failing death test for the molecule command to check for the modified error message.

[akohlmey]

I would expect that support for reading triangles from STL files (or converting them to a molecule file?) would be highly desirable by users of this feature. The file format is quite simple and may be text or binary. A simple reader is in tools/std_bin2text.cpp and also in create_atoms.cpp.

[sjplimp]

@akohlmey - responses to your comments
yes, I haven't started working on doc pages yet
re: STL, I agree this is a good idea, I'll add it to the to-do list

[akohlmey]

@sjplimp You should merge with upstream now so you have the enhanced tokenizer class for more specific pattern matching of molecule file keywords.
Because of these changes, there is now a merge conflict. I you would prefer to have me do the merge and resolve the conflict, just let me know.

[sjplimp]

@akohlmey done - thanks for the updated Molecule class

[akohlmey]

Here is an attempt for using LAMMPS' graphics facilities with the second demo system.
The added command lines for dump image are:

dump viz all image 1000 myimage-*.png diameter diameter tri index 1 1.0 size 800 600 zoom 3.1 &
   shiny 0.1 fsaa yes view 80 -20 box no 0.0 fix 1 const 2 0.5 center s 0.49883 0.55 0.495547 &
   ssao no 13251 0.3

dump_modify viz pad 9 backcolor black backcolor2 white lights 0.2 0.8 0.6 0.9 fcolor 1 silver &
   color map1 0.282 0.129 0.451 color map2 0.435 0.435 0.556 color map3 0.161 0.686 0.498 &
   color map4 0.741 0.875 0.149 amap min 20 cf 0.0 4 min map1 0.333 map2 0.667 map3 max map4

itokawa.webm

[akohlmey]

The one thing I am realizing that we could add to dump image is an option to limit additional graphics elements with a region so you can "cut an STL object open". For the first example this can work already because you have typed tri particles.

[jtclemm]

The one thing I am realizing that we could add to dump image is an option to limit additional graphics elements with a region so you can "cut an STL object open". For the first example this can work already because you have typed tri particles.

That would be a nice little option. Particularly for containers. Does that exist for fix wall/region with geometric primitives?

And nice images/videos! I'm thinking there might be value using your images in the doc files since they are all-lammps. Thoughts @sjplimp?

Edit: I don't think the asteroid makes for a good LAMMPS example since it's a bit expensive and complicated, but should I add the screw feeder with the dump image commands as an example?

[sjplimp]

All the new images look nice, both from @jtclemm and @akohlmey I like the screw feeder from Joel best, b/c it shows the triangulation of the feeder more clearly. Maybe that is a setting for the in situ graphics. For the asteroid, both Joel's and Axel's (the one with colored particles) are good. I think the "cut STL open" as in Joel's pic can be done simply by using a geometric region to limit the dump image graphics? Which may be what Joel has done with OVITO? For the images added to the doc page, we should say what graphics tool produced them.

Adding the screw feeder as a LAMMPS example would be good, so that the Howto page pics could point to it.
It could include the dump image commands from Axel.

Finally, I don't think any of this needs to be perfect, we can just go with what you have. It is more important to have the PR released and we can add better or newer images later.

[sjplimp]

Re: cut the image - what I mean is, doesn't dump_modify region already work with dump image? I thought it did at least for particles.

[jtclemm]

Finally, I don't think any of this needs to be perfect, we can just go with what you have. It is more important to have the PR released and we can add better or newer images later.

Agreed. I'll opt for Axel's current images and include the example with the dump image command. The other Ovito images I generated for the granular paper so those will be used there. As you say, can always improve the dump commands to slice regions later.

I'll work on those updates. In the meantime I also replied to your comments above to fix some issues.

Edit: added the new examples, please let me know what you think.

[akohlmey]

Re: cut the image - what I mean is, doesn't dump_modify region already work with dump image? I thought it did at least for particles.

for particles, you can already control what is output by defining the dump group.
but that would be different by graphics objects that are added through a fix or compute.
I have to review the code.

To answer the question about fix wall/gran/region. We don't have a fix visualization for that but you can visualize the region directly and region visualizations are a totally different beast. I have to re-read the code about how this would work.

Bottom line: the feeder example should be able to "slice" the surfaces with creative definition of the dump group, but the other example not.

I will investigate. It certainly is not something that belongs in this pull request but is a later add-on. Right now everything seems to work well enough for using dump image as it is. Another later option to explore would be to add an option to compute a gradient map as an additional option for smoother surfaces.

[sjplimp]

@jtclemm new feeder example looks good including adding commented-out in situ graphics
@akohlmey per previous email, from my POV this is ready to merge when Joel approves the PR

[jtclemm]

@akohlmey per previous email, from my POV this is ready to merge when Joel approves the PR

I made a few more final clean ups and think the PR is ready to be merged (assuming I didn't break any tests). There's undoubtedly more work that could be done, but this PR is big enough so best to save that for later.

[akohlmey]

but this PR is big enough so best to save that for later.

There is one annoying detail. This adds the third STL file reader/parser and I would like to consolidate that and use the safer/cleaner text processing tools/classes we have available in LAMMPS.

[jtclemm]

There is one annoying detail. This adds the third STL file reader/parser and I would like to consolidate that and use the safer/cleaner text processing tools/classes we have available in LAMMPS.

Oof that is annoying, I didn't know that. Thanks for cleaning up! Nice to finally have this off my plate.

For now...