Add snapshot to mbuild Compound backmapping method

[chrisjonesBSU]

Right now, finegrain.py has a method that performs back mapping on an mBuild compound. This PR adds a method that performs the back mapping on a gsd.hoomd.Frame (i.e. Snapshot) and returns an mBuild compound.

Still a couple of things left to do:

• Add doc strings
• Add unit tests
• Figure out if the in-situ energy minimization is working as expected, if not we can take it out
• Add an example to the documentation.

[chrisjonesBSU]

After chatting with @StephMcCallum there was some discussion about how to handle cases where two atoms need to be removed to form monomer-monomer bonds during fine-graining. A common example would be removing the -OH group from something like in polyalanine.

I suggested we keep the behavior as explicit as possible, so that it only ever removes particles you tell it to. To support removing multiple particles when needed, bond_head_index and bond_tail_index need to work if multiple indices are passed in. Then, to make this approach easier, we begin adding a library/database of common chemistries.

If we want to be less strict, we could add a check that if the particle given by one of the bond_x_index parameters is not a hydrogen, then automatically remove only any hydrogens that were also bonded to it.

[chrisjonesBSU]

We need to be careful here. We should iterate through particle.direct_bonds() and make sure we are ony removing ones that are hydrogens.

[StephMcCallum]

I think that my most recent push addresses this. I added a library parameter as suggested above and adjusted the code so that bond_head_index and bond_tail_index are lists. The user can input a list of indices to remove and the first listed index will be the polymerization bond. Or they can give the library key which I put a few examples but the key points to a nested dictionary.

I removed the code above, but we can add element specific checks if needed. I think it may be better to keep it general at this point and have the user control the removed elements through the list inputs.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[chrisjonesBSU]

Nice job getting started on the doc strings. For consistency, try to follow the examples in the numpy style-guide: https://numpydoc.readthedocs.io/en/latest/format.html

You can also see the doc strings in coarsegrain.py as an example.

Parameters
-----------------
parameter : type, default=default value if there is one
     Quick description of what this parameter does.

Here is an example from CG_Compound

    Parameters
    ----------
    compound : mbuild.Compound
        Fine-grain structure to be coarse-grained
    beads : dict, default None
        Dictionary with keys containing desired bead name and values containing
        SMARTS string specification of that bead. For example::

            beads = {"_B": "c1sccc1", "_S": "CCC"}

        would map a ``"_B"`` bead to any thiophene moiety (``"c1sccc1"``) found
        in the compound and an ``"_S"`` bead to a propyl moiety (``"CCC"``).
        User must provide only one of beads or mapping.
    mapping : dict or path, default None
        Either a dictionary or path to a json file of a dictionary. Dictionary
        keys contain desired bead name and SMARTS string specification of that
        bead and values containing list of tuples of atom indices::

            mapping = {"_B...c1sccc1": [(0, 4, 3, 2, 1), ...]}

        User must provide only one of beads or mapping.
    allow_overlap : bool, default False
        Whether to allow beads representing ring structures to share atoms.
    add_hydrogens : bool, default False
        Whether to add hydrogens. Useful for united-atom models.
    aniso_beads : bool, default False
        Whether to calculate orientations for anisotropic beads.
        Note: Bead sizes should be fitted during paramaterization.
        Only Gay-Berne major axis orientations are calculated here.

[StephMcCallum]

I'm working on adding a few more enhancements to this PR:

• unique chain end chemistries with additional hydrogen
• optional rotation by quaternion instead of vector
• back-mapping for flowerMD ellipsoids

[StephMcCallum]

I'm working on adding a few more enhancements to this PR:

• unique chain end chemistries with additional hydrogen
• optional rotation by quaternion instead of vector
• back-mapping for flowerMD ellipsoids

Note: I'm going to move these to a new PR after merging this one