exorcist user-facing docs by atravitz · Pull Request #2076 · OpenFreeEnergy/openfe

atravitz · 2026-07-14T20:39:38Z

resolves #2075

LLM / AI generated code disclosure

LLMs or other AI-powered tools (beyond simple IDE use cases) were used in this contribution: no

Checklist

All new code is appropriately documented (user-facing code must have complete docstrings).
Added a news entry, or the changes are not user-facing.
Ran pre-commit: you can run pre-commit locally or comment on this PR with pre-commit.ci autofix.
Filled in the AI generated code disclosure.

Manual Tests: these are slow so don't need to be run every commit, only before merging and when relevant changes are made (generally at reviewer-discretion).

GPU integration tests
example notebook testing
packaging tests: run this for any large feature PRs or PRs that add test data.

Developers certificate of origin

I certify that this contribution is covered by the MIT License here and the Developer Certificate of Origin at https://developercertificate.org/.

github-actions · 2026-07-14T20:40:16Z

🚨 API breaking changes detected! 🚨

View workflow run

Griffe output

$ griffe check "openfe" -s src --no-inspection --no-color --verbose -a origin/main
src/openfe/storage/metadatastore.py:0: <module>:
Public object was removed

src/openfe/storage/resultserver.py:0: <module>:
Public object was removed

src/openfe/storage/resultclient.py:0: <module>:
Public object was removed

src/openfe/tests/storage/test_metadatastore.py:0: <module>:
Public object was removed

src/openfe/tests/storage/test_resultclient.py:0: <module>:
Public object was removed

src/openfe/tests/storage/test_resultserver.py:0: <module>:
Public object was removed


$ griffe check "openfecli" -s src --no-inspection --no-color --verbose -a origin/main
src/openfecli/commands/plan_rbfe_network.py:121: plan_rbfe_network(warehouse):
Parameter was added as required

codecov · 2026-07-23T19:00:34Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.57%. Comparing base (cc8edd5) to head (66f27cd).

Additional details and impacted files

@@                     Coverage Diff                      @@
##           epic/execution_improvements    #2076   +/-   ##
============================================================
  Coverage                        90.57%   90.57%           
============================================================
  Files                              217      217           
  Lines                            21522    21522           
============================================================
  Hits                             19494    19494           
  Misses                            2028     2028

Flag	Coverage Δ
fast-tests	`90.57% <100.00%> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ethanholz

Just a few comments but nothing blocking merge.

ethanholz · 2026-07-23T20:34:27Z

+
+The following is an example script that runs up to 4 workers at a time, with each automatically picking up the next valid unit to be executed.
+
+.. code:: bash


I wonder if it might be worth adapting this to Python because it is not pleasant to read (even though it is my code lol)

I think that makes sense given our target audience!

ethanholz · 2026-07-23T20:35:46Z

+
+        db.mark_task_completed(taskid, success=result.ok())
+        # 4. output result to warehouse
+        # TODO: we may need to end up handling namespacing on the warehouse side for tokenizables


Are there any questions on this piece?

yes, but we should probably move that to the warehouse PR

IAlibay · 2026-07-28T12:55:13Z

+
+.. code:: bash
+
+    openfe plan-rbfe-network ... --warehouse


As a user, it's not immediately clear to me what --warehouse would do, would I not want to call plan-rbfe-network to get the AlchemicalNetwork and then use that as the input to my execution?

I.e. this section needs a "what arre we doing in each of these calls" explanation.

IAlibay · 2026-07-28T13:05:09Z

+import click
+from plugcli.params import Option
+
+WAREHOUSE = Option("--warehouse", type=click.BOOL, help="Use a warehouse", default=False)


This needs more detail in the help field.

IAlibay · 2026-07-28T13:06:05Z

@@ -0,0 +1,105 @@
+.. userguide_exorcist:
+
+Execution with Exorcist Workers


This is missing user centric information on the why of Exorcist. I.e. what is the advantage of using this over the old quickrun, etc...

IAlibay · 2026-07-28T13:06:32Z

+You can execute the network of simulation units defined by an ``AlchemicalNetwork`` (see `create_alchemical_network`) using ``openfe.orchestration``:
+
+
+First, we build a graph of tasks to be executed from the ``AlchemicalNetwork``:


Might be good to define tasks here - is that each individual unit that needs to be executed?

IAlibay · 2026-07-28T13:14:34Z

+
+    openfe worker warehouse/
+
+To run a single task to completion.


What if it doesn't complete? What should users be doing in that instance?

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

atravitz changed the base branch from main to feat/warehouse July 14, 2026 20:54

atravitz requested a review from ethanholz July 23, 2026 19:30

ethanholz reviewed Jul 23, 2026

View reviewed changes

atravitz self-assigned this Jul 27, 2026

atravitz changed the title ~~[WIP] exorcist docs~~ exorcist user-facing docs Jul 27, 2026

atravitz linked an issue Jul 27, 2026 that may be closed by this pull request

exorcist user-facing docs #2075

Open

IAlibay reviewed Jul 28, 2026

View reviewed changes

Base automatically changed from feat/warehouse to epic/execution_improvements July 30, 2026 21:58

atravitz mentioned this pull request Jul 30, 2026

feat: filesystem exorcist worker #1833

Merged

7 tasks

atravitz force-pushed the exorcist-docs branch from ab6a7d3 to 27c9775 Compare July 30, 2026 23:33

atravitz force-pushed the epic/execution_improvements branch 2 times, most recently from 6fc30c6 to a07f1c8 Compare August 7, 2026 19:51

atravitz force-pushed the epic/execution_improvements branch 2 times, most recently from a6fd672 to cc8edd5 Compare August 14, 2026 16:01

atravitz and others added 8 commits August 17, 2026 13:45

re-org index to include exorcist execution

34fc236

copy/paste in example exorcist execution code

c188e93

brain dump for exorcist example

2741ebd

clean up example

0b55297

fix docs build

17c89d4

Apply suggestions from code review

cbad6a8

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

Apply suggestions from code review

22f278b

Co-authored-by: Irfan Alibay <IAlibay@users.noreply.github.com>

add type hints for me

66f27cd

atravitz force-pushed the exorcist-docs branch from 27c9775 to 66f27cd Compare August 17, 2026 20:50


		The following is an example script that runs up to 4 workers at a time, with each automatically picking up the next valid unit to be executed.

		.. code:: bash

		@@ -0,0 +1,105 @@
		.. userguide_exorcist:

		Execution with Exorcist Workers

		You can execute the network of simulation units defined by an ``AlchemicalNetwork`` (see `create_alchemical_network`) using ``openfe.orchestration``:


		First, we build a graph of tasks to be executed from the ``AlchemicalNetwork``:

Uh oh!

Conversation

atravitz commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LLM / AI generated code disclosure

Developers certificate of origin

Uh oh!

github-actions Bot commented Jul 14, 2026

Uh oh!

codecov Bot commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ethanholz left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

atravitz commented Jul 14, 2026 •

edited

Loading

codecov Bot commented Jul 23, 2026 •

edited

Loading