Feedback on OpenFE installation tutorial

[xyzmjf]

I have started to review the hands on tutorial presented at the symposium. I am sharing this with you as I see an opportunity for the documentation to be further improved.

[1] The installation part is great - very slick. I managed to get it all installed and ran the tests as indicated - 549 pass but 2 fail, as they did at the symposium.

I shared these on Slack.

[2] Fetching the files needed for the tutorial works a treat

------quote------
openfe fetch rbfe-tutorial
Fetching https://raw.githubusercontent.com/OpenFreeEnergy/ExampleNotebooks/master/rbfe_tutorial/tyk2_ligands.sdf
Fetching https://raw.githubusercontent.com/OpenFreeEnergy/ExampleNotebooks/master/rbfe_tutorial/tyk2_protein.pdb
Fetching https://raw.githubusercontent.com/OpenFreeEnergy/ExampleNotebooks/master/rbfe_tutorial/cli_tutorial.md
Fetching https://raw.githubusercontent.com/OpenFreeEnergy/ExampleNotebooks/master/rbfe_tutorial/python_tutorial.ipynb
------unquote------

[3.1] I then elected to run the tutorial on my local machine with this command
jupyter notebook => select file python_tutorial.ipynb in browser
http://localhost:8888/notebooks/python_tutorial.ipynb

[3.2]
One could also just follow the commands in the file.
cli_tutorial.md

[4] It is a little glitchy in that the network diagram does not display molecules when an edge is clicked in the browser. It does actually do this in the command line variant.

[5] In the browser the tutorial ends with this statement.
-----quote-----
Each of these individual .json files contains a Transformation, which contains all the information to run the calculation. These could be farmed out as individual jobs on a HPC cluster.
-----unquote----

This is very annoying as I do not have an HPC cluster and all I want to do is run one small edge and see the RBFE between 2 molecules.

My analogy - the lovely cake is almost within reach, but not quite , it is locked away behind the glass and I need a key called HPC to open this.

So these docs are good but not great.

[6] In the CLI version of the tutorial the hapless user (myself) hits quite a similar brick wall.

---quote---

# this will take a very long time! don't actually do it!
for file in network_setup/transformations/*.json; do
  relpath=${file:30}  # strip off "network_setup/transformations/"
  dirpath=${relpath%.*}  # strip off final ".json"
  openfe quickrun $file -o results/$relpath -d results/$dirpath
done
---unquote---

So again the magic of RBFE calculations remains just out of reach.
Irfan suggested that the JSON files could be written to disk allowing the 
user to run just 1 edge - which is a good idea, in fact I see it as needed. 

Oh can we have this in both the command line instance and the instance in the ipynb file. 

[7] Final comments
This is rather complex for a beginner to run through. 
I do accept that free energy calculations are complex, so maybe that is the 
nature of the beast. 

[dwhswenson]

Re: [1] (test failures): Transferring the relevant info from slack:

==================================================== short test summary info ======================================================
FAILED mambaforge/envs/openfe_env/lib/python3.10/site-packages/openfe/tests/protocols/test_openmm_equil_rfe_protocols.py::test_openmm_run_engine[CPU] - jaxlib.xla_extension.XlaRuntimeError: FAILED_PRECONDITION: Couldn't get ptxas/nvlink version string: INTERNAL: Couldn't invoke ...
FAILED mambaforge/envs/openfe_env/lib/python3.10/site-packages/openfe/tests/protocols/test_openmm_equil_rfe_protocols.py::test_openmm_run_engine[CUDA] - jaxlib.xla_extension.XlaRuntimeError: FAILED_PRECONDITION: Couldn't get ptxas/nvlink version string: INTERNAL: Couldn't invoke ...
ERROR mambaforge/envs/openfe_env/lib/python3.10/site-packages/openfecli/tests/test_cli.py::TestCLI::test_command_sections - UnicodeDecodeError: 'ascii' codec can't decode byte 0xc2 in position 3821: ordinal not in range(128)
ERROR mambaforge/envs/openfe_env/lib/python3.10/site-packages/openfecli/tests/test_cli.py::TestCLI::test_get_installed_plugins - UnicodeDecodeError: 'ascii' codec can't decode byte 0xc2 in position 3821: ordinal not in range(128)
========================== 2 failed, 549 passed, 21 skipped, 107 warnings, 2 errors in 255.73s (0:04:15) =======================

For the unicode errors, try setting an environment variable export PYTHONUTF8=1 in your shell config (.bashrc or similar). That should fix for now, by enforcing UTF-8 mode (assuming that I'm right and the issue is that you have set an ascii locale). Let me know if that fixes; if so, I can push a new version of plugcli that forces UTF-8 reading (will be default behavior in Python 3.15 anyway).

For the jax failures, could you report the traceback you get? Probably best to do that as a separate issue on the OpenFE repo, where it will be more visible to anyone else who has the same problem.

Re: [4]: The visualization isn't expected to be interactive in most notebooks. There was a particular matplotlib backend that at one point worked to give me interactivity, but now I can't figure out which one it was. Also, performance was atrocious in-notebook, so I wouldn't recommend it anyway.

Re: [5] and [6]: Handled in #68.

Re: [3] and [7]: The Python tutorial is intended to be a subset of the CLI tutorial. I've tried to make that more clear in #68. The entirety of the Python tutorial is just how to do the CLI command openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb from Python. So the simple version is the CLI; the Python version is necessarily more complex so you can customize things.