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?

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?

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

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


Equilibration length and protocol repeats are mentioned here, but not discussed below. Would it make sense to also add some more details for those (when one would want to change them, what the default is,..)?

Reply via ReviewNB

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

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


Could it make sense to generally have a section/table somewhere that has all the simulations diagnostics listed and then the possible settings changes, as a summary/overview?

Reply via ReviewNB

Yeah that could be a good idea, the plan is to add a general health check page which would be related to this maybe there we should include examples of good and bad outputs of the simulation diagnostic and then link to the sections of this cookbook which control a setting which should influence that output?

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

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


Line #14. new_total_sim_time = n_repeats * n_windows * (protocol.settings.simulation_settings.production_length + protocol.settings.simulation_settings.equilibration_length)
Since the times are per leg, maybe we could call it *_sim_time_per_leg?

Reply via ReviewNB

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

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


Line #5. # The number of replicas must be increased to match the number of lambda windows Maybe change this to must since it would raise an error

Reply via ReviewNB

Changed to must.

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

jthorton · 2026-10-26T13:21:55Z

@@ -0,0 +1,830 @@
+{


Does this break the flow of the notebook? Maybe it would be better to do it from the view of RBFE and have a section at the bottom showing how to change these values for the others grouped by protocol so users can click on that specific protocol and follow the steps for it?

Reply via ReviewNB

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_rbfe_settings.ipynb

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

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!

jthorton Oct 23, 2026

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!

jthorton Oct 23, 2026

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!

jthorton Oct 26, 2026

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!

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!

jthorton Oct 23, 2026

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!

jthorton Oct 23, 2026

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!

jthorton Oct 23, 2026

Choose a reason for hiding this comment

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!

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!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

IAlibay Oct 23, 2026 •

edited

Loading

IAlibay Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

hannahbaumann Oct 23, 2026 •

edited

Loading

jthorton Oct 26, 2026 •

edited

Loading

jthorton Oct 26, 2026 •

edited

Loading