Add back-mapping and coarse-graining modules using integraiton with CGSmiles

[chrisjonesBSU]

Summary:

This revamps the old coarse-graining module, and adds a back mapping capabilities as well. The workflow utilizies CGSmiles to provide a useable API/interface to mapping between different resolutions. It also provides an interface to mapping directly with mBuild compounds (rather than CGSmiles strings). I also pulled in the latest upstream/main changes here. The primary motivation for adding this was to have a more streamlined and robust API for backmapping paths to atomistic compounds. Before, most workflows involved using Polymer.build_from_path() which worked great for linear chains. These new modules still work for linear chains, but also for branched chains, as well as non-polymer systems.

Here are some examples:

Back-mapping a linear path to an atomistic polymer

path = straight_line(spacing=0.35, N=10, bead_name="PEO")
compound = path.backmap("{#PEO=[>]COC[<]}")

Back-mapping with multiple monomer types

diblock = straight_line(
    spacing=0.35, N=8, bead_name=CyclicNamer([("PE", 4), ("PEO", 4)])
)
comp = diblock.backmap("{#PE=[>]CC[<],#PEO=[>]COC[<]}")

Fine-graining a box of water and ethanol system

bead_a = mb.Compound(name="Water")
bead_b = mb.Compound(name="Ethanol")
box = mb.fill_box(compound=[bead_a, bead_b], n_compounds=[50, 50], box=[3, 3, 3])
all_atom = box.backmap("{#Water=O,#Ethanol=CCO}")

Using mBuild compound templating instead of CGSMILES strings

bead_a = mb.Compound(name="Water")
bead_b = mb.Compound(name="Ethanol")
box = mb.fill_box(compound=[bead_a, bead_b], n_compounds=[50, 50], box=[3, 3, 3])
all_atom = box.backmap(templates={
    "Water": mb.load("O", smiles=True),
    "Ethanol": mb.load("CCO", smiles=True)}
)

PR Checklist

---

• Includes appropriate unit test(s)
• Appropriate docstring(s) are added/updated
• Code is (approximately) PEP8 compliant
• Issue(s) raised/addressed?

[codecov]

Codecov Report

❌ Patch coverage is 92.98246% with 44 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.02%. Comparing base (52a0897) to head (0db2c9f).

Files with missing lines	Patch %	Lines
mbuild/coarse_graining/cg_map.py	92.91%	17 Missing ⚠️
mbuild/coarse_graining/placement.py	91.94%	12 Missing ⚠️
mbuild/coarse_graining/backmap.py	92.72%	8 Missing ⚠️
mbuild/coarse_graining/fragments.py	94.23%	3 Missing ⚠️
mbuild/coarse_graining/convert.py	95.12%	2 Missing ⚠️
mbuild/periodic_kdtree.py	0.00%	1 Missing ⚠️
mbuild/utils/visualize.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1352      +/-   ##
===========================================
- Coverage    82.37%   80.02%   -2.35%     
===========================================
  Files           64       69       +5     
  Lines         6977     7483     +506     
===========================================
+ Hits          5747     5988     +241     
- Misses        1230     1495     +265     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.