Tutorial notebook demonstrating functionality implemented in MuPT-hub/mupt#22

[joelaforet]

Description

This PR adds a tutorial notebook demonstrating the hierarchical export pipeline implemented in MuPT-hub/mupt#22.

The notebook (Random_CoPolymer_Quickstart.ipynb) provides a complete end-to-end workflow:

1. Build – Define polymer chemistry via SMILES and construct a random copolymer system using build_copolymer_system()
2. Export – Demonstrate the three-layer export pipeline:
   • primitive_to_rdkit_hierarchical() → RDKit with AtomPDBResidueInfo
   • primitive_to_openff_molecules() → OpenFF with hierarchy schemes
   • primitive_to_mdanalysis() → MDAnalysis Universe with topology attributes
3. Serialize – Save/load systems using save_openff_system() / load_openff_system()
4. Simulate – Run NPT molecular dynamics with OpenMM via OpenFF Interchange

Related PRs

• Depends on: Hierarchical Exporters: RDKit, OpenFF, and MDAnalysis with residue/chain metadata mupt#22 (hierarchical export pipeline implementation)

Notes

• Requires the release-env conda environment with OpenMM GPU support for the MD simulation section
• The notebook validates that chain/residue metadata is preserved through each export layer

Status

• Ready for review

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[joelaforet]

@timbernat @mrshirts Is there anything blocking this tutorial from being merged? @gitsirsha walked through the notebook and found it to be a useful example.

[joelaforet]

The spirit of this notebook is useful, but the actual code it depends on will likely not be merged into main. How should I change this tutorial so more people have access to it?

[timbernat]

Is there anything blocking this tutorial from being merged?

• The usage of primitive_to_rdkit_hierarchical()/primitive_to_openff_molecules(), the former of which will be superceded by RDKit converter rewrites and the latter we had decided was too specific and dependency-heavy to include in main
• The huge amount of duplication from other notebooks, namely all but section 5 is a rehash of either multiscale_chain_placements or mdfiles_with_openff. This complicates maintainability and discards the modularity those source tutorials were originally designed with (e.g. build and simulation don't need to know the details of one-another). I say that with the tacit understanding that some pending Issues could make information transfer more streamlined.

gitsirsha walked through the notebook and found it to be a useful example.

That's great! It seems he was able to run the notebook, which is perfectly fine for development within analysis subgroup. There's nothing wrong with sharing branches with extra features, or indeed modifying the extant notebooks as you please locally, so long as you don't overwrite the version in main.

The spirit of this notebook is useful, but the actual code it depends on will likely not be merged into main

That seems reasonable

How should I change this tutorial so more people have access to it?

More access to it how? If they've cloned this repo, they already have access to it just by changing branch (i.e. git switch MDAexport).