diff --git a/docs/reference/api/defining_and_executing_simulations.rst b/docs/reference/api/defining_and_executing_simulations.rst
index 6bbf76cdd..29d43287d 100644
--- a/docs/reference/api/defining_and_executing_simulations.rst
+++ b/docs/reference/api/defining_and_executing_simulations.rst
@@ -21,6 +21,7 @@ Executing Simulations
TaskStatusDB
get_task_df
get_dependency_df
+ update_max_tries
storage.FileSystemWarehouse
diff --git a/docs/reference/cli/index.rst b/docs/reference/cli/index.rst
index d2769e1db..7a2bdb714 100644
--- a/docs/reference/cli/index.rst
+++ b/docs/reference/cli/index.rst
@@ -21,6 +21,7 @@ Execution Commands
run_task
status
+ update_task_db
quickrun
Results Gathering Commands
diff --git a/docs/reference/cli/update_task_db.rst b/docs/reference/cli/update_task_db.rst
new file mode 100644
index 000000000..6838a791d
--- /dev/null
+++ b/docs/reference/cli/update_task_db.rst
@@ -0,0 +1,7 @@
+.. _cli_update_task_db:
+
+``openfe update-task-db``
+=========================
+
+.. click:: openfecli.commands.update_task_db:update_task_db
+ :prog: openfe update-task-db
\ No newline at end of file
diff --git a/news/max_tries.rst b/news/max_tries.rst
new file mode 100644
index 000000000..f1918037b
--- /dev/null
+++ b/news/max_tries.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* Added ``openfe.update_max_tries()`` for updating a ``TaskStatusDB`` (`PR #2227 `_).
+
+**Changed:**
+
+*
+
+**Deprecated:**
+
+*
+
+**Removed:**
+
+*
+
+**Fixed:**
+
+*
+
+**Security:**
+
+*
diff --git a/src/openfe/__init__.py b/src/openfe/__init__.py
index 210feb40e..d7ba46a46 100644
--- a/src/openfe/__init__.py
+++ b/src/openfe/__init__.py
@@ -73,7 +73,7 @@
)
from . import analysis, orchestration, setup, storage, utils
-from .orchestration import get_dependency_df, get_task_df, setup_task_campaign
+from .orchestration import get_dependency_df, get_task_df, setup_task_campaign, update_max_tries
from .orchestration.worker import Worker
from .setup import (
KartografAtomMapper,
diff --git a/src/openfe/orchestration/__init__.py b/src/openfe/orchestration/__init__.py
index 25b0e416d..0e61162d4 100644
--- a/src/openfe/orchestration/__init__.py
+++ b/src/openfe/orchestration/__init__.py
@@ -4,5 +4,6 @@
get_dependency_df,
get_task_df,
setup_task_campaign,
+ update_max_tries,
)
from .worker import Worker
diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py
index 0d430c760..42677b62f 100644
--- a/src/openfe/orchestration/exorcist_utils.py
+++ b/src/openfe/orchestration/exorcist_utils.py
@@ -4,11 +4,13 @@
structures and can initialize an Exorcist task database from that graph.
"""
+from datetime import datetime
from pathlib import Path
import exorcist
import networkx as nx
import pandas as pd
+from annotated_types import Annotated, Gt
from gufe import AlchemicalNetwork, ProtocolDAG
from ..storage.warehouse import FileSystemWarehouse, WarehouseBaseClass
@@ -153,3 +155,54 @@ def get_dependency_df(task_db: exorcist.TaskStatusDB) -> pd.DataFrame:
"""
return pd.read_sql_table("dependencies", task_db.engine)
+
+
+def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: Annotated[int, Gt(0)]):
+ """Update the "max_tries" column to `max_tries`.
+ Only rows that do _not_ have status=COMPLETED will be operated on.
+
+ Parameters
+ ----------
+ task_db : openfe.TaskStatusDB
+ The TaskStatusDB to update
+ max_tries : int
+ The positive integer value to assign as ``max_tries`` for the updated columns.
+
+ Raises
+ ------
+ ValueError: If max_tries is not a positive integer.
+
+ """
+
+ import sqlalchemy as sqla
+ from exorcist.models import TaskStatus
+
+ # TODO: select a single task_id?
+ if type(max_tries) is not int or max_tries <= 0:
+ raise ValueError("`max_tries` must be a positive integer.")
+
+ values = {"max_tries": max_tries, "last_modified": datetime.now()}
+
+ # on the rows that already hit TOO_MANY_RETRIES, only allow increasing max_tries,
+ # otherwise the state is invalid, and set to AVAILABLE
+ stmt_update_too_many_retries = (
+ sqla.update(task_db.tasks_table)
+ .where(task_db.tasks_table.c.status == TaskStatus.TOO_MANY_RETRIES.value)
+ .where(task_db.tasks_table.c.max_tries < max_tries)
+ .values(**values, status=TaskStatus.AVAILABLE.value)
+ )
+
+ # COMPLETED tasks should not be updated, and never allow max_tries to be less than
+ # the number of attempts already made (tries), otherwise the state is invalid.
+ stmt_update_uncompleted_tasks = (
+ sqla.update(task_db.tasks_table)
+ .where(task_db.tasks_table.c.status != TaskStatus.COMPLETED.value)
+ .where(task_db.tasks_table.c.tries < max_tries)
+ .where(task_db.tasks_table.c.max_tries != max_tries)
+ .values(**values)
+ )
+
+ with task_db.engine.begin() as conn:
+ # TODO: is there a better way than calling this twice?
+ conn.execute(stmt_update_too_many_retries)
+ conn.execute(stmt_update_uncompleted_tasks)
diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py
index 6f93e3f75..91e1f807f 100644
--- a/src/openfe/tests/orchestration/test_exorcist_utils.py
+++ b/src/openfe/tests/orchestration/test_exorcist_utils.py
@@ -14,7 +14,7 @@
get_task_df,
setup_task_campaign,
)
-from openfe.orchestration.exorcist_utils import _alchemical_network_to_task_graph
+from openfe.orchestration.exorcist_utils import _alchemical_network_to_task_graph, update_max_tries
from openfe.storage.warehouse import WarehouseBaseClass
@@ -268,3 +268,87 @@ def test_get_dependency_df(benzene_star_map_task_db):
assert isinstance(df, pd.DataFrame)
assert list(df.columns) == ["from", "to", "blocking"]
assert len(df) == 504
+
+
+# NOTE: pulled this fixture from exorcist, since I expect to upstream the tests below
+from datetime import datetime
+
+from exorcist import TaskStatus, TaskStatusDB
+
+_DEFAULT_DATETIME = datetime(1970, 1, 1)
+
+
+def patch_exorcist_datetime(with_datetime=_DEFAULT_DATETIME):
+ # turns out we can't patch just the now() method (datetime is immutable,
+ # probably C code?) so we have to patch the entire datetime module
+ loc = "exorcist.taskdb.datetime"
+ datetime_now = mock.Mock(now=mock.Mock(return_value=with_datetime))
+ return mock.patch(loc, datetime_now)
+
+
+def patch_openfe_datetime(with_datetime=_DEFAULT_DATETIME):
+ loc = "openfe.orchestration.exorcist_utils.datetime"
+ datetime_now = mock.Mock(now=mock.Mock(return_value=with_datetime))
+ return mock.patch(loc, datetime_now)
+
+
+def get_tasks_and_deps(db):
+ with db.engine.connect() as conn:
+ tasks = set(conn.execute(sqla.select(db.tasks_table)))
+ deps = set(conn.execute(sqla.select(db.dependencies_table)))
+ return tasks, deps
+
+
+def task_row(taskid, status, last_modified, tries, max_tries, task_type=""):
+ return (taskid, status.value, last_modified, tries, max_tries, task_type)
+
+
+@pytest.fixture
+def fresh_db():
+ # create an empty database
+ echo = False # switch this for debugging
+ engine = sqla.create_engine("sqlite://", echo=echo)
+
+ yield TaskStatusDB(engine)
+
+
+def test_update_max_tries(fresh_db):
+ task_db = fresh_db
+ task_db.add_task("task_a", requirements=[], max_tries=1)
+ task_db.add_task("task_b", requirements=["task_a"], max_tries=1)
+ task_db.add_task("task_c", requirements=[], max_tries=1)
+
+ with patch_exorcist_datetime():
+ taskid = task_db.check_out_task()
+ assert taskid == "task_a"
+ task_db.mark_task_completed(taskid, success=True)
+
+ taskid = task_db.check_out_task()
+ assert taskid == "task_b"
+ task_db.mark_task_completed(taskid, success=False)
+
+ tasks, deps = get_tasks_and_deps(task_db)
+
+ assert tasks == {
+ task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""),
+ task_row("task_b", TaskStatus.TOO_MANY_RETRIES, _DEFAULT_DATETIME, 1, 1, ""),
+ task_row("task_c", TaskStatus.AVAILABLE, None, 0, 1, ""),
+ }
+ assert deps == {("task_a", "task_b", False)}
+
+ datetime2 = datetime(1999, 1, 1)
+ with patch_openfe_datetime(datetime2):
+ update_max_tries(task_db=task_db, max_tries=18)
+ tasks, deps = get_tasks_and_deps(task_db)
+
+ assert tasks == {
+ task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""),
+ task_row("task_b", TaskStatus.AVAILABLE, datetime2, 1, 18, ""),
+ task_row("task_c", TaskStatus.AVAILABLE, datetime2, 0, 18, ""),
+ }
+
+
+@pytest.mark.parametrize("bad_value", ["1", -2, 3.0, 0, True])
+def test_update_max_tries_invalid_val(fresh_db, bad_value):
+ with pytest.raises(ValueError, match="must be a positive integer"):
+ update_max_tries(task_db=fresh_db, max_tries=bad_value)
diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py
new file mode 100644
index 000000000..fc242b2c9
--- /dev/null
+++ b/src/openfecli/commands/update_task_db.py
@@ -0,0 +1,106 @@
+# This code is part of OpenFE and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/openfe
+
+from pathlib import Path
+
+import click
+
+from openfecli import OFECommandPlugin
+from openfecli.utils import write
+
+
+def update_task_db_main(
+ task_db_path: Path,
+ max_tries: int,
+):
+ """
+ Parameters
+ ----------
+ task_db_path : pathlib.Path
+ Path to a task.db
+
+ max_tries: int
+ Value to update "max_tries" column to, for applicable rows
+
+
+ Example
+ -------
+ >>> openfe status --task-db task.db
+
+ ┌─────────────────────────────┬──────────────────┬─────────────────────┬───────┬───────────┐
+ │ task_id │ status │ last_modified │ tries │ max_tries │
+ ├─────────────────────────────┼──────────────────┼─────────────────────┼───────┼───────────┤
+ │ SetupUnit-d568ebe569b445c7… │ COMPLETED │ 2026-08-14 11:19:16 │ 1 │ 3 │
+ │ SetupUnit-17dc05e0d79747e7… │ COMPLETED │ 2026-08-14 11:19:21 │ 1 │ 3 │
+ │ SetupUnit-78321eda905c4c2c… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │
+ │ SetupUnit-0238f65b55044b1e… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-2… │ COMPLETED │ 2026-08-14 11:25:10 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-1… │ COMPLETED │ 2026-08-14 11:25:34 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-f… │ COMPLETED │ 2026-08-14 11:26:22 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-c… │ TOO_MANY_RETRIES │ 2026-08-14 11:26:24 │ 3 │ 3 │
+ │ MultiStateAnalysisUnit-a72… │ COMPLETED │ 2026-08-14 11:26:51 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-e44… │ COMPLETED │ 2026-08-14 11:26:26 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-7e9… │ COMPLETED │ 2026-08-14 11:29:07 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-72c… │ BLOCKED │ NaT │ 0 │ 3 │
+ └─────────────────────────────┴──────────────────┴─────────────────────┴───────┴───────────┘
+
+ >>> openfe update-task-db task.db --max-tries=6
+ ┌─────────────────────────────┬──────────────────┬─────────────────────┬───────┬───────────┐
+ │ task_id │ status │ last_modified │ tries │ max_tries │
+ ├─────────────────────────────┼──────────────────┼─────────────────────┼───────┼───────────┤
+ │ SetupUnit-d568ebe569b445c7… │ COMPLETED │ 2026-08-14 11:19:16 │ 1 │ 3 │
+ │ SetupUnit-17dc05e0d79747e7… │ COMPLETED │ 2026-08-14 11:19:21 │ 1 │ 3 │
+ │ SetupUnit-78321eda905c4c2c… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │
+ │ SetupUnit-0238f65b55044b1e… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-2… │ COMPLETED │ 2026-08-14 11:25:10 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-1… │ COMPLETED │ 2026-08-14 11:25:34 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-f… │ COMPLETED │ 2026-08-14 11:26:22 │ 1 │ 3 │
+ │ MultiStateSimulationUnit-c… │ AVAILABLE │ 2026-08-14 11:27:24 │ 3 │ 6 │
+ │ MultiStateAnalysisUnit-a72… │ COMPLETED │ 2026-08-14 11:26:51 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-e44… │ COMPLETED │ 2026-08-14 11:26:26 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-7e9… │ COMPLETED │ 2026-08-14 11:29:07 │ 1 │ 3 │
+ │ MultiStateAnalysisUnit-72c… │ BLOCKED │ NaT │ 0 │ 6 │
+ └─────────────────────────────┴──────────────────┴─────────────────────┴───────┴───────────┘
+
+ """
+
+ from exorcist import TaskStatusDB
+
+ from openfe.orchestration.exorcist_utils import update_max_tries
+
+ task_db = TaskStatusDB.from_filename(task_db_path)
+ update_max_tries(task_db, max_tries)
+
+
+@click.command("update-task-db", short_help="Update the 'max_tries' column.")
+@click.option(
+ "--task-db",
+ type=click.Path(
+ exists=True,
+ readable=True,
+ file_okay=True,
+ dir_okay=False,
+ path_type=Path,
+ ),
+ required=True,
+ help="Path to a TaskDB file.",
+)
+@click.option(
+ "--max-tries",
+ type=click.IntRange(min=1),
+ required=True,
+ help="The positive integer value to assign as 'max_tries' for the updated columns.",
+)
+# NOTE: this is named intentionally broad so that we can add "update_task_type" in a future version
+def update_task_db(task_db: Path, max_tries: int):
+ """
+ Update the 'max_tries' column for applicable tasks. COMPLETED tasks and tasks with tries > the input 'max-tries' will not be updated.
+
+ """
+
+ # TODO: add loading bar
+ write("Loading task db ...")
+ update_task_db_main(task_db_path=task_db, max_tries=max_tries)
+
+
+PLUGIN = OFECommandPlugin(command=update_task_db, section="Execution", requires_ofe=(1, 13))
diff --git a/src/openfecli/tests/commands/test_update_task_db.py b/src/openfecli/tests/commands/test_update_task_db.py
new file mode 100644
index 000000000..362165ee1
--- /dev/null
+++ b/src/openfecli/tests/commands/test_update_task_db.py
@@ -0,0 +1,40 @@
+import exorcist
+import networkx as nx
+import pytest
+import sqlalchemy as sqla
+from click.testing import CliRunner
+
+from openfecli.commands.update_task_db import update_task_db
+
+from ..utils import assert_click_success
+
+
+@pytest.fixture
+def simple_task_graph():
+ task_graph = nx.DiGraph()
+ node_ids = ["HybridTopologySetupUnit-123", "HybridTopologySetupUnit-456"]
+
+ for id in node_ids:
+ task_graph.add_node(id)
+
+ return task_graph, node_ids
+
+
+def test_update_task_db(simple_task_graph):
+ runner = CliRunner()
+ with runner.isolated_filesystem():
+ task_graph, _ = simple_task_graph
+ db_path = "test.db"
+ db = exorcist.TaskStatusDB.from_filename(db_path)
+ db.add_task_network(task_graph, max_tries=2)
+ input_max_tries = 7
+ result = runner.invoke(
+ update_task_db, ["--task-db", db_path, "--max-tries", str(input_max_tries)]
+ )
+ assert_click_success(result)
+
+ # just make sure the table is actually modified. all edge cases etc. are handled in the Python API tests
+ with db.engine.connect() as conn:
+ new_max_tries = set(conn.execute(sqla.select(db.tasks_table.c.max_tries)))
+
+ assert new_max_tries == {(input_max_tries,)}