Next steps for the OpenMM Cookbook and Tutorials

[jchodera]

@sef43 @peastman @raimis : Here's my proposal for next steps with the openmm-cookbooks repo:

• Change the colab link to be URL-aware: Currently, the google colab link that is generated is hard-wired to the gh-pages/dev path. Instead, we want this to automatically select the path being built [dev, PR#, latest].
• Cut a major release to deploy current working state: The release action should deploy a copy of the current working state to https://openmm.github.io/openmm-cookbook/latest, allowing us to continue development work at the current URL [https://openmm.github.io/openmm-cookbook/dev]. The OpenMM webpage currently points to https://openmm.github.io/openmm-cookbook, which redirects to dev/index.html.
• Update the index.html to redirect to latest: We will want to update the gh-pages branch index.html to redirect to latest instead of dev
• Clean up the tutorials one by one: I can help clean up and add back the tutorials one by one, facilitated by being able to test them in the PR# and dev URL paths while the latest remains stable.
• Cut a new release with working tutorials
• Update openmm.org link to tutorials: We can change the openmm.org tutorials link to link out to to https://openmm.github.io/openmm-cookbook/latest/index.html#tutorials

@sef43 : Would you be able to help with the first few steps? I can then work on updating and integrating the tutorials.

[sef43]

@jchodera
First item should be fixed by #15

The release action should work after #15 is merged. Do we want to call it v1.0.0 or v0.1.0 or something else?

[peastman]

Sounds like a good plan.

The version number doesn't matter much. It's just for our own use, not something users will see. Whatever seems convenient.

[sef43]

@jchodera this branch and PR contains the infrastructure for the tutorials: #16 I have put on the openmm-7 tutorials, in the same state as they are currently are here: https://openmm.org/tutorials, I have just made minor changes to make sure they actually run. If you can give me some ideas and guidance on how they can be cleaned-up/improved I can do it?

I have also added a new basic introduction tutorial as a place to start, and to act as a template for adding new tutorials.

[apayne97]

@peastman @sef43 @jchodera I'd like to finally fix the issues with the B2AR tutorial, which is in: notebooks/tutorials/Beta_2_adrenergic_receptor_B2AR_membrane_protein_simulation_with_CHARMM.ipynb

This would potentially close some previous issues, linked here:

• CHARMM-GUI Systems in OpenMM: Interoperability and Documentation openmm#3152
• Typo in the beta-2-adrenergic receptor tutorial openmm#3114
• Mistakes in tutorial input script (OpenMM 7) openmm#2343

I have a few questions related to doing this

1. What is the preferred system for including input files? seems like this would be necessary to test that the tutorials actually work
2. What's the difference between a tutorial and a cookbook in this context?
3. Should I make a PR to Add tutorials #16 or to main? Likely the branch would come from Add tutorials #16 as that is the one with the B2AR tutorial

I think @viktorbelay will make a tutorial/cookbook that extends this tutorial to a more complicated system.

EDIT: looks like you've fixed the main errors! Nice. I'll look for other ideas then.

[peastman]

What is the preferred system for including input files? seems like this would be necessary to test that the tutorials actually work

How large are the files? If they're fairly small we can just include them in the repository. If they're larger we may want to find somewhere else to host them.

What's the difference between a tutorial and a cookbook?

The way I think of it is that tutorials are educational tools. Their job is to help new users learn to use OpenMM. They should introduce and explain any important concepts for what they're doing. They may involve many steps. They often take you through a whole workflow.

The cookbook is a reference. It contains small, self contained pieces of code for performing specific tasks. They can assume you already know what you want to do, and you're just trying to find out how to do it.

Should I make a PR to #16 or to main?

That PR will hopefully be getting merged quite soon. It might be easiest to just wait for that, then open a new PR to main.

[sef43]

To add one more point the cookbook examples will be run through the CI in this repo to make sure they work with the latest and development versions of OpenMM. The tutorials will not be run through the CI, but should still be able to be run on Colab

PR#16 will be merged soon (end of this week/start of next), new tutorials can then be added by PRing to main, and it will hopefully be clearer how to add them!

[apayne97]

Great, thank you both!

How large are the files? If they're fairly small we can just include them in the repository. If they're larger we may want to find somewhere else to host them.

Typical input files for simulations? 5-25MB, 2-3 files

[peastman]

25 MB is pretty big for putting into the repository. If there are multiple files that size, they can start filling up space really quickly. And once a file is added, it's impossible ever to remove it. Even if you delete it from the head, it will still be there in the history taking up space on people's disks.

Is there somewhere else we could put them?

[apayne97]

Is there somewhere else we could put them?

I don't know if I'm the person to answer this question? I guess wherever this is hosted: https://openmm.org/tutorials_/b2ar_membrane/files/charmm-gui.zip

EDIT: https://github.com/openmm/openmm-org/tree/master/tutorials_/b2ar_membrane/files

I guess I could just zip a directory of files as inputs like this does and use that

[viktorbelay]

@peastman @apayne97 Since there is a B2AR tutorial already, I'm thinking of putting together a more general CHARMMGUI/CHARMM cookbook and/or tutorial for OpenMM. I've done a lot of work with various kinds of systems that were set up in CHARMMGUI and simulated with CHARMMFF (soluble, membrane-bound systems, ligand-protein, protein-protein, etc..), so I have a bunch of rough notes that I could translate into one big general cookbook/tutorial. What do you think?

[peastman]

I'm thinking of putting together a more general CHARMMGUI/CHARMM cookbook and/or tutorial for OpenMM.

That sounds great!

I guess I could just zip a directory of files as inputs like this does and use that

How big is the zip file?

[sef43]

I think the main remaining question for the tutorials is how we are going to handle hosting input files, as @peastman said above they can quickly fill up a git repo. There are two decisions:

• what will be the biggest file size we will allow to be added to the repo ?
• where will we put the files larger than this? could this be a new folder on the S3 bucket where the docs are hosted?