Cookbook on exploring common RBFE protocol settings by jthorton · Pull Request #344 · OpenFreeEnergy/ExampleNotebooks

jthorton · 2026-10-22T10:43:32Z

Docs in response to OpenFreeEnergy/openfe#2278 this cookbook just explores the common settings users might want to change in the RBFE protocol.

Questions

Is this quite simple format okay to start with?
Are there any other settings we should add in this first pass?

review-notebook-app · 2026-10-22T10:43:37Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

github-actions · 2026-10-22T10:43:41Z

👈 Launch a Colab session on branch hytop_settings

IAlibay · 2026-10-23T09:32:29Z

@@ -0,0 +1,305 @@
+{


[nit] maybe we can put the line about "Choose and Configure a Protocol" inside one of those info boxes?
[nit] How about a table for the parameters list?
Thinking about thw iderr range of settings, maybe this should be "settings which impact sampling / performance", and then we could have "settings which affect the termodynamic state" and "settings that affect the model".

Reply via ReviewNB

Addressed all of these, for point 3 the main contents are now under the heading Sampling and performance settings with the idea of adding the other sections later, let me know what you think.

IAlibay · 2026-10-23T09:32:29Z

@@ -0,0 +1,305 @@
+{


"..., you may also need to consider increasing the number of lambda windows see the next section for more information." This sentence probably needs breaking into two sentences.

"Consider increasing the simulation length after running the simulation when:" Might be good to mention here that they'd have to run a new simulation (i.e. we can't extend at this time).

"Increasing the simulation length is not always the best solution...." This sentence is vague and maybe a bit a confusing. Technicaly you can just run a very long simulation to improve overlap - it might be good to say something like "increasing the number of windows can sometimes be more useful in increasing overlap". I.e. a combination of both would help, but think about lambda windows first.

Reply via ReviewNB

"A large number of samples are..": Maybe briefly mention where the user could find this information.
Do you have a citation for the kbT cutoff?

@IAlibay agreed, changed.

@hannahbaumann I think this might be best saved for the shared health check cookbook which could have a similar format and we can link to it there?

Added the citation for the kbT cutoff but maybe this would also be best put in the health check cookbook when describing what each diagnostic is showing?

For me this sentence still needs breaking up, but maybe I'm looking at a wrong commit?
you may also need to consider increasing the number of lambda windows see the next section for more information

+1 the two sentences with that statement could use breaking up into two sentences.

Thanks broken up and shortened.

IAlibay

Is this quite simple format okay to start with?

I think there's a lot of things here that could be generalized. As a first pass this is ok, but in follow-up work, it might be good to make this more abstract and make it cover multiple protocols.

Are there any other settings we should add in this first pass?

I left a comment above. I think it would be good to cover the broad "themes" of settings we have. E.g. things that control your model, things that control the thermodynamics, things that control sampling/convergence.

hannahbaumann · 2026-10-23T13:03:52Z

@@ -0,0 +1,305 @@
+{


Would we want a separate cookbook for SepTop/ABFE settings or could it make sense to showcase some difference here (mostly thinking of the lambda schedule).
Should we also highlight and explain adaptive_settings in this cookbook or should that be done elsewhere? (maybe wrt what happens to the user updated settings after calling adaptive_settings, meaning it wouldn't be changed back to default settings); maybe also mention them in the section that talks about net charge changes?

Reply via ReviewNB

I have tried to include the SepTop and ABFE settings changes as well as there is a lot of overlap let me know what you think; maybe the format could be cleaned up as its quite verbose right now, but I wanted each section to have a consistent flow.

_adaptive_settings is an awkward one as its related and is probably worth introducing the beginning after inspecting the defaults but maybe we should consider making it public first?

jthorton · 2026-10-26T11:26:27Z

@@ -0,0 +1,834 @@
+{


Do we want to advertise the private function, its helpful to validate the new schedule but its private and could change in future and break. Maybe this validation could be moved back onto the settings object so we can call model_validate ?

Reply via ReviewNB

Moving it back to model_validate sounds good - I wouldn't encourage exposing this private method. I would encourage adding a section at the end of the tutorial that calls validate as an example of "this is how you check that all your settings work well".

Changed to use the validate method, but this does require a system so its a little more complicated so having this in model_validate might be a good usability improvement.

Opened an issue to come back to this OpenFreeEnergy/openfe#2342

IAlibay · 2026-10-28T22:16:56Z

@@ -0,0 +1,1180 @@
+{


Thoughts about putting the default settings before getting into this sub-header?

There we could mention how default_settings is a common method across all Protocols.

Reply via ReviewNB

Added a bit to explain its common to all protocols but kept it under this heading as it might be easier to find when skimming the page?

It's not that it's common to all Protocols, but that the default settings have nothing specific to do to "sampling and performance settings". If you don't want to move out of this settings section, is there anything you could say on how it applies to other sections?

Ah, I misunderstood; I have now moved the default settings part to the first section of the notebook.

IAlibay · 2026-10-28T22:16:56Z

@@ -0,0 +1,1180 @@
+{


Would be good to make a statement about how generalized this is, i.e. that it applies to all multistate Protocols (e.g. HybridTop, SepTop, ABFE and AHFE).

Reply via ReviewNB

Added something on this.

The formula below for SepTop and ABFE is slightly different since you're also accounting for the end state equilibration, maybe mention that?

How about saying it's the "alchemical simulation cost"? And then mention that equilibration has its own cost (and then refer below)?

Changed to alchemical and added a note pointing to the other formula.

hannahbaumann · 2026-11-03T12:06:38Z

@@ -0,0 +1,1180 @@
+{


For a complete explanation of each setting and how to customize the object see Choose and Configure a Protocol.
That cookbook actually doesn't seem to have much additional detail, except the constructing settings manually, do we still want to keep that cookbook?

Reply via ReviewNB

True but it does show off changing all of the settings and explains what they mean with comments so I think its the best we have for now?

hannahbaumann · 2026-11-03T12:12:50Z

@@ -0,0 +1,759 @@
+{


These settings provide a good starting point to investigate the affect of additional sampling on the transformation under study however, but will also increase the computational cost of the simulation.
This sentence is a bit long and hard to understand, maybe rephrase or break it up into two?

Reply via ReviewNB

Reduced and simplified.

IAlibay

Couple of small things, but approving early!

atravitz

I did a quick read through and think it looks great overall. Some of it might be creeping into User Guide territory, so if we want to add any more detail we could consider splitting it.

hannahbaumann

Thanks @jthorton , lgtm!

exploring rbfe settings

97a0a28

jthorton added 4 commits October 22, 2026 11:46

small format update

5c447f3

clean up units and some text

4653a6e

more intro

ded8d29

more clean up

2987975

IAlibay self-requested a review October 22, 2026 14:08

atravitz assigned jthorton Oct 22, 2026

IAlibay reviewed Oct 23, 2026

View reviewed changes

IAlibay requested changes Oct 23, 2026

View reviewed changes

hannahbaumann reviewed Oct 23, 2026

View reviewed changes

other protocol details and PR feedback

ff6d4f2

jthorton commented Oct 26, 2026

View reviewed changes

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

jthorton added 3 commits October 26, 2026 11:45

more cleanup

f4207db

shorten some sections

70308bc

more cleanup

5d9d939

jthorton commented Oct 26, 2026

View reviewed changes

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

jthorton added 2 commits October 26, 2026 16:28

refactor to group other protocols at the end

b669049

add repeats and equilibration length updates

c1d1cd9

IAlibay reviewed Oct 28, 2026

View reviewed changes

hannahbaumann reviewed Oct 29, 2026

View reviewed changes

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

IAlibay reviewed Oct 30, 2026

View reviewed changes

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

Comment thread cookbook/exploring_protocol_settings.ipynb Resolved

Merge branch 'main' into hytop_settings

659a9e6

atravitz self-assigned this Nov 2, 2026

jthorton and others added 4 commits November 3, 2026 10:32

PR feedback, make other protocol section shorter

698f9d4

Merge branch 'main' into hytop_settings

fdf15b0

small edits

0adf60c

Merge remote-tracking branch 'origin/hytop_settings' into hytop_settings

0509b5e

jthorton requested review from IAlibay, atravitz and hannahbaumann November 3, 2026 10:55

hannahbaumann reviewed Nov 3, 2026

View reviewed changes

IAlibay approved these changes Nov 4, 2026

View reviewed changes

Merge branch 'main' into hytop_settings

b266384

atravitz approved these changes Nov 6, 2026

View reviewed changes

jthorton mentioned this pull request Nov 6, 2026

Move lambda settings validation to model_validate (SepTop and ABFE) OpenFreeEnergy/openfe#2342

Open

pr feedback

3afdc7a

jthorton requested a review from hannahbaumann November 6, 2026 13:56

hannahbaumann approved these changes Nov 6, 2026

View reviewed changes

jthorton and others added 7 commits November 6, 2026 16:49

rename file

d5a05c1

Merge branch 'main' into hytop_settings

1a13dfe

fix alert boxes

144ee0a

Merge branch 'main' into hytop_settings

482cbad

fix note and warning box rendering

8f8be8e

fix links in note boxes

945d4e0

update the link after the rename

6b0e4ee

jthorton enabled auto-merge November 9, 2026 12:54

jthorton merged commit f944a2b into main Nov 9, 2026
4 checks passed

jthorton deleted the hytop_settings branch November 9, 2026 13:12

Conversation

jthorton commented Oct 22, 2026

Questions

Uh oh!

review-notebook-app Bot commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

IAlibay Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IAlibay Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hannahbaumann Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IAlibay left a comment

Choose a reason for hiding this comment

Uh oh!

hannahbaumann Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jthorton Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

IAlibay Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IAlibay Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

IAlibay Oct 23, 2026 •

edited

Loading

IAlibay Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

jthorton Oct 26, 2026 •

edited

Loading

IAlibay Oct 28, 2026 •

edited

Loading

IAlibay Oct 28, 2026 •

edited

Loading

hannahbaumann Nov 3, 2026 •

edited

Loading

hannahbaumann Nov 3, 2026 •

edited

Loading