Cooking with Yank Start

[Lnaden]

This is a very, very early start at the cookbook changes I want to propose. Since its going to be a large change (and a fair amount of tedious work), I wanted to propose this now so people can look at it before I sink the time in making it a reality.

The point of this is to show the layout and how the files will be organized. RST files in a cookbook like thing composed of 4 main chapters:

• Basics (repeated small blocks which will be used later)
• Binding recipes (full recipes comprised of basics blocks)
• Hydration recipes
• Cluster recipes (things to make cluster life easier)

This will fully make html so you can see what its doing.

@andrrizzi and @jchodera let me know your thoughts on this.

[andrrizzi]

I think I'd prefer to have at least some of the basic building blocks inside the correspondent pages (i.e. some concrete examples of usage of the samplers building blocks inside the samplers.rst page), but this sounds great either way.

[Lnaden]

I think I'd prefer to have at least some of the basic building blocks inside the correspondent pages

I had thought about that. In order to reduce the amount of space each individual block takes up (and minimize duplication on each page), I had only added in some small
"See these recipes for examples"
In the handful of YAML api pages (see the options: resume_simulation for example).

However, I also split the actual recipe code blocks into their own raw...yaml pages (e.g. the rawbasicnpt.yaml so they can be .. literalinclude:: file if we want without having to worry about maintaining the examples between the cookbook and the YAML options. So we can do what you suggest as well, which is why I wanted opinions.

That sort of sub-division though is part of why it will be a time sink, which is also why I wanted to throw out a small example first.

[jchodera]

Can you have readthedocs build this branch too so we can see it rendered online?

[Lnaden]

Can you have readthedocs build this branch too so we can see it rendered online?

Not really, because we don't deploy to readthedocs, we build it ourselves and just push to the S3 bucket.

[jchodera]

Got it. Will try to test locally then when I have stable network again then.

[jchodera]

Just took a look!

I like the idea, but I worry that users will really just want to cut-and-paste whole recipes that are close to what they want to do, and then tweak from there. By just specifying "basic blocks", I fear that, unless it is SUPER clear what building blocks are essential, it will be hard for them to copy exactly the right blocks to make a complete recipe. Also, nobody wants to copy a ton of different things just to get something that works, so they might lose patience, especially if they run into a few errors.

Finally, things like NPT simulations should be very common, but NVT should not be recommended. We don't want to make it easy to do things that are not recommended.

What would you think about just creating a few basic recipes pulled from the yank-examples or something, and annotating them?

If we wanted to do more of a building-block approach, something like the openmm input builder is what I would go with.

[Lnaden]

But the very simple blocks were going to be used in later blocks which are full copy/paste recipes. What I don't want to do is have 50 variants of full recipes for very slight changes because 1 setting is off. I can dig through the issue tracker, but my sense is there have been a number of issues where someone has copied a recipe, but it does not quite work for them because of one setting.

[Lnaden]

I fully figured people would just jump into the later, complete recipes; and would only return to the basic blocks when they want to tweak something.

Also, is NVT really that uncommon (implicit solvent)?

[andrrizzi]

I think both are valuable (i.e. the partial, short snippets and the whole script examples), but right now we're lacking more short snippets examples than fully fledged YAML scripts. I think the former examples are better to guide users to make changes to the latter, fully functional scripts.

[Lnaden]

right now we're lacking more short snippets examples than fully fledged YAML scripts

I would argue we are lacking both. The problem with the larger files is small subtle changes get missed, the problem with the larger files alone is that they are a pain to maintain and right now are not updated very easily or at all to keep up with the code changes. Its why I am proposing a total overhaul to fix both so we don't fix one now and have to circle back to fix the other, but then they diverge and it gets hard to maintain again.

[jchodera]

I think users would want to get started the quickest way possible. That means

• Quickly find a use case that is close to what I want to do. There probably are five common use cases, not fifty.
• Cut-and-paste something that works with recommended best practices.
• Start modifying or tweaking it to fit their application.

That's how I'd like this to work:

• First, direct the user to a small number of general use cases
• Give them a complete recipe to copy-and-paste
• Then get into details about which parts they might want to vary, where we can show small blocks that can replace parts of their recipe
• Finally, link to the actual documentation for each set of options when possible

Starting with the small blocks and building up to complete recipes is completely backwards in terms of getting users running quickly. By necessity, you would require them to get all the way to the end and absorb a great deal of irrelevant information to get to the point where they can run something. That's a recipe for turning users away.

Also, is NVT really that uncommon (implicit solvent)?

There is no V in implicit solvent.