Adds ATM tutorial, along with livecomms update #30

mb2055 · 2024-11-18T14:54:02Z

Updates the tutorials with 04_fep/05_ATM, a tutorial for running alchemical transfer on TYK2 31<->43.
Also updates the livecomms tex file with a brief description of ATM, along with a rundown of what the tutorial covers.

Before any merging can be done, the PR needs to be squashed by @lohedges .

Adds notebook running through a full ATM run of tyk2 31<->43, includes pre-run results and an equilibrated system

Also moves ATM notebook into the 04_fep folder.

Also fixes spelling errors

jmichel80 · 2024-11-18T15:59:59Z

04_fep/05_ATM/01-ATM.ipynb

+ "ligand_bound = BSS.IO.readMolecules([f\"{url}/ejm_31.prm7\", f\"{url}/ejm_31.rst7\"])[0]\n",
+ "ligand_free = BSS.IO.readMolecules([f\"{url}/ejm_43.prm7\", f\"{url}/ejm_43.rst7\"])[0]"


this fails for when run on try.openbiosim.org with bss updated locally with this message

OSError: Failed to read molecules from: ['https://biosimspace.openbiosim.org/m/ejm_31.prm7',
'https://biosimspace.openbiosim.org/m/ejm_31.rst7']

Loading of the protein input seems to have worked

This is fixed now, the files were missing from the website

jmichel80 · 2024-11-18T16:00:29Z

04_fep/05_ATM/01-ATM.ipynb

+ "# We also need to download the example output files\n",
+ "from get_tutorial import download\n",
+ "\n",
+ "download(\"05\")"


could be download("01") for simplicity (with an update in get_tutorial.py)

Now changed to "01" along with updated get_tutorial.py

jmichel80 · 2024-11-18T16:12:17Z

04_fep/05_ATM/01-ATM.ipynb

+ "id": "56b04fa5-aa1e-4032-9ca6-e79a21240845",
+ "metadata": {},
+ "source": [
+ "This protocol can then be run using the BioSimSpace openMM runner."


update the comment to mention that this may take a few minutes to complete.
do we need to run by default for this tutorial with the default choice of step=10000?

Testing minimisation and it seems that ~200 steps is the minimum to give a system that is stable going forward. Added a comment to say it may take a few minutes.

jmichel80 · 2024-11-18T16:19:26Z

04_fep/05_ATM/01-ATM.ipynb

+ "id": "31954b81-0307-42d3-8c4c-489a62be74c1",
+ "metadata": {},
+ "source": [
+ "We will now run our first equilibration, including all of the forces we used in the minimisation. "


test if it is possible to reduce runtime for the tutorial to ~ 10 ps. If so explicitly mention in the comment cell that the values used here are lower than what would be used in a production setting to allow (near) interactive use of the notebook

I've done some testing both locally and on the server and it seems that this system is a lot more forgiving than some of the others I've tested, so we can get away with running for only ~1ps during each equilibration step. The issue is that the system is quite large, so even with these small runtimes the total minimisation/equilibration pipeline takes around 10 minutes.

I had originally designed the notebook to have all of the code that actually runs the simulation commented out, but somewhere along the line I must've uncommented them for testing and forgotten about it. This is why the notebook loads a pre-prepared system at the end of the pipeline, since it wasn't actually meant to run any simulations.

I can't guarantee that production simulations run with the output of such a short min/eq pipeline will be stable, so i think the ready_for_production.bss file will still be useful as this is from a fully prepared system that has been equilibrated for a total of 700 ps.

I'll reduce the runtimes in the notebook and add a note at the end that clarifies that, in a real production pipeline, users would need to run much longer minimisations and equilibrations in order to ensure stability.

The comment cell between equilibration and annealing is now longer in sync with the code

In this case we will use 10 annealing cycles with a total runtime of 100ps, meaning that the value of lambda is increased by a value of 0.05 every 10ps.
-->
In this case we will use 10 annealing cycles with a total runtime of 1ps, meaning that the value of lambda is increased by a value of 0.05 every 0.1ps. For production runs we recommend extending the runtime to at least 100 ps.

jmichel80 · 2024-11-18T16:20:21Z

04_fep/05_ATM/01-ATM.ipynb

+ "\n",
+ "We now need to introduce the ATMForce to the system; this introduction needs to be gradual, otherwise our simulations will crash.\n",
+ "\n",
+ "This gradual introduction can be done by annealing the system to a lambda value of 0.5. Starting from lambda=0, the annealing protocol simulates a series of windows in which the value of lambda is gradually increased. In this case we will use 10 annealing cycles with a total runtime of 100ps, meaning that the value of lambda is increased by a value of 0.05 every 10ps."


same comment as for equilibration (attempt to run with a shorter runtime for the purpose of the demo)

Now cut to 1ps

Update the comment cell to add

For production runs we recommend extending the runtime to at least 100 ps.

jmichel80 · 2024-11-18T16:22:01Z

04_fep/05_ATM/01-ATM.ipynb

+ " runtime=\"100ps\",\n",
+ " anneal_numcycles=10,\n",
+ ")\n",
+ "annealing_process = BSS.Process.OpenMM(equilibrated, annealing, platform=\"CUDA\")\n",


this assumes the code is executed on an instance with an available CUDA plaftorm. Update for the general case where the platform should be auto-detected

All instances of "CUDA" have now been removed

jmichel80 · 2024-11-18T16:22:13Z

04_fep/05_ATM/01-ATM.ipynb

+ " runtime=\"100ps\",\n",
+ ")\n",
+ "post_anneal_equilibration_process = BSS.Process.OpenMM(\n",
+ " annealed, post_anneal_equilibration, platform=\"CUDA\"\n",


same comments as above

remind users to use 100 ps if they want to adapt the demo for actual production :-)

jmichel80 · 2024-11-18T16:22:24Z

04_fep/05_ATM/01-ATM.ipynb

+ " use_atm_force=True,\n",
+ " lambda1=0.5,\n",
+ " lambda2=0.5,\n",
+ " runtime=\"100ps\",\n",


test shorter run time

jmichel80 · 2024-11-18T16:23:52Z

04_fep/05_ATM/get_tutorial.py

+import BioSimSpace as BSS
+
+links = {
+ "05": (


change to "01" ?

jmichel80 · 2024-11-18T16:30:28Z

04_fep/05_ATM/01-ATM.ipynb

+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "check = BSS.Stream.load(\"tyk2_atm/ready_for_production.bss\")\n",


load a bss file saved after the post_anneal_equilibration stage ? show how to load a precomputed one if this is not available. This will allow users running the above cells to compare their post annealed inputs with those provided with the tutorial.

This file is now used as a comparison for the output of the min/eq pipeline.
I could also be useful as a backup - the pipeline might not be stable, so this system can be used in the production step instead if things crash.

…tocols, allowing them to be run using minimal resources.

…mment telling the user that minimisation may take a few minutes

jmichel80

i suggest a few minor edits to the comment cells to remind readers throughout that the 1 ps runtime values should be updated to 100 ps if trying to adapt the demo for production

jmichel80 · 2024-11-19T16:21:06Z

i'm done with the review. @lohedges do you have further comments ? if not I think we can merge. The only outstanding task is to update the container .

lohedges · 2024-11-19T16:29:48Z

I'll have another read through before the social tomorrow and will update with any comments.

Also clarify comment at the start of min/eq pipeline to ensure users understand that production simulations should be equilibrated for a much larger amount of time

mb2055 · 2024-11-19T16:39:11Z

I've fixed the annealing description and added some text to the top of the minimisation/equilibration pipeline to clarify that the runtimes used are not appropriate for real production simulations.

lohedges · 2024-11-20T09:09:06Z

04_fep/05_ATM/01-ATM.ipynb

Can this be named with an underscore rather than a hyphen for consistency with the other notebooks.

Typo in the notebook:

... BioSimSpace openMM runner.

Should be:

... BioSimSpace OpenMM process.

lohedges · 2024-11-20T09:09:59Z

LIVECOMS/04_fep/livecoms.tex

+
+\subsection{Alchemical Transfer}
+
+The seventh notebook \href{https://github.com/OpenBioSim/biosimspace_tutorials/blob/main/04_fep/05_ATM/01-ATM.ipynb}{01-ATM} describes how to setup and run an RBFE calculation using the Alchemical Transfer Method (ATM) \cite{WU2021}. The specific example in this case is TYK2 31-43, taken from the benchmark set of Wang et al. \cite{Wang2015} 


Replace hyphen with underscore here too.

Also a typo, sytems instead of systems.

lohedges · 2024-11-20T09:28:03Z

Thanks, @mb2055, this is great.

Also fix a few spelling and text errors

mb2055 · 2024-11-20T11:28:07Z

Should all be fixed now @lohedges

mb2055 added 4 commits October 31, 2024 12:37

ATM tutorial

d011218

Adds notebook running through a full ATM run of tyk2 31<->43, includes pre-run results and an equilibrated system

Updates livecomms article with section on ATM.

c23c2a1

Also moves ATM notebook into the 04_fep folder.

Removes example outputs in preparation for switching to remote download

fa26a0a

Also fixes spelling errors

Adds remote download of example output folder

bc96880

mb2055 requested review from jmichel80 and lohedges November 18, 2024 14:54

jmichel80 requested changes Nov 18, 2024

View reviewed changes

mb2055 added 2 commits November 19, 2024 12:19

Updates ATM tutorial with cut-down minimisation and equilibration pro…

eb01633

…tocols, allowing them to be run using minimal resources.

Updates number of steps for minimisation to ensure stability, adds co…

87f958d

…mment telling the user that minimisation may take a few minutes

jmichel80 approved these changes Nov 19, 2024

View reviewed changes

Fix text before annealing step to mention proper runtime

6f2e4c6

Also clarify comment at the start of min/eq pipeline to ensure users understand that production simulations should be equilibrated for a much larger amount of time

lohedges reviewed Nov 20, 2024

View reviewed changes

Rename ATM notebook for consistency

6879af8

Also fix a few spelling and text errors

Trim empty cell from bottom of notebook

1902873

lohedges merged commit ac200df into main Nov 24, 2024

lohedges deleted the feature_ATM_tutorial branch November 24, 2024 08:05

		"ligand_bound = BSS.IO.readMolecules([f\"{url}/ejm_31.prm7\", f\"{url}/ejm_31.rst7\"])[0]\n",
		"ligand_free = BSS.IO.readMolecules([f\"{url}/ejm_43.prm7\", f\"{url}/ejm_43.rst7\"])[0]"


		\subsection{Alchemical Transfer}

		The seventh notebook \href{https://github.com/OpenBioSim/biosimspace_tutorials/blob/main/04_fep/05_ATM/01-ATM.ipynb}{01-ATM} describes how to setup and run an RBFE calculation using the Alchemical Transfer Method (ATM) \cite{WU2021}. The specific example in this case is TYK2 31-43, taken from the benchmark set of Wang et al. \cite{Wang2015}

Adds ATM tutorial, along with livecomms update #30

Adds ATM tutorial, along with livecomms update #30

Uh oh!

Conversation

mb2055 commented Nov 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmichel80 left a comment

Choose a reason for hiding this comment

jmichel80 commented Nov 19, 2024

lohedges commented Nov 19, 2024

mb2055 commented Nov 19, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lohedges commented Nov 20, 2024

mb2055 commented Nov 20, 2024

Labels

4 participants

mb2055 commented Nov 18, 2024 •

edited

Loading