From b814d16c2590a54f9214de786b7c73bb230a8016 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Thu, 11 Sep 2025 07:17:17 -0700 Subject: [PATCH 01/16] update partial charge tests now that a production NAGL model is available (#1506) * update tests now that a production NAGL model is available * fix mock * clean up mocking --- .../openmm_utils/charge_generation.py | 7 ++-- openfe/tests/protocols/test_openmmutils.py | 36 +++++++++++++------ 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/openfe/protocols/openmm_utils/charge_generation.py b/openfe/protocols/openmm_utils/charge_generation.py index d35518ced..92a345104 100644 --- a/openfe/protocols/openmm_utils/charge_generation.py +++ b/openfe/protocols/openmm_utils/charge_generation.py @@ -41,7 +41,7 @@ try: from openff.toolkit.utils.nagl_wrapper import NAGLToolkitWrapper from openff.nagl_models import ( - get_models_by_type, validate_nagl_model_path + get_models_by_type, validate_nagl_model_path, ) except ImportError: HAS_NAGL = False @@ -142,12 +142,11 @@ def assign_offmol_nagl_charges( prod_models = get_models_by_type( model_type='am1bcc', production_only=True ) - # Currently there are no production models so expect an IndexError try: nagl_model = prod_models[-1] except IndexError: - errmsg = ("No production am1bcc NAGL models are current available " - "please manually select a candidate release model") + errmsg = ("No production am1bcc NAGL models were found, " + "please manually select a candidate release model.") raise ValueError(errmsg) model_path = validate_nagl_model_path(nagl_model) diff --git a/openfe/tests/protocols/test_openmmutils.py b/openfe/tests/protocols/test_openmmutils.py index 062ed5f4b..35255862e 100644 --- a/openfe/tests/protocols/test_openmmutils.py +++ b/openfe/tests/protocols/test_openmmutils.py @@ -793,18 +793,32 @@ def test_am1bcc_conformer_nochange(self, eg5_ligands): # but the charges should have assert not np.allclose(charges, lig.partial_charges) - @pytest.mark.skipif(not HAS_NAGL, reason='NAGL is not available') - def test_no_production_nagl(self, uncharged_mol): + @pytest.mark.skipif(not HAS_NAGL, reason="NAGL is not available") + def test_latest_production_nagl(self, uncharged_mol): + """We expect to find a NAGL model and be able to generate partial charges with it.""" + charge_generation.assign_offmol_partial_charges( + uncharged_mol, + overwrite=False, + method="nagl", + toolkit_backend="rdkit", + generate_n_conformers=None, + nagl_model=None, + ) + assert uncharged_mol.partial_charges.units == "elementary_charge" - with pytest.raises(ValueError, match='No production am1bcc NAGL'): - charge_generation.assign_offmol_partial_charges( - uncharged_mol, - overwrite=False, - method='nagl', - toolkit_backend='rdkit', - generate_n_conformers=None, - nagl_model=None, - ) + @pytest.mark.skipif(not HAS_NAGL, reason="NAGL is not available") + def test_no_production_nagl(self, uncharged_mol): + """Cleanly handle the case where a NAGL model isn't found.""" + with mock.patch("openfe.protocols.openmm_utils.charge_generation.get_models_by_type", return_value=[]): + with pytest.raises(ValueError, match="No production am1bcc NAGL"): + charge_generation.assign_offmol_partial_charges( + uncharged_mol, + overwrite=False, + method="nagl", + toolkit_backend="rdkit", + generate_n_conformers=None, + nagl_model=None, + ) # Note: skipping nagl tests on macos/darwin due to known issues # see: https://github.com/openforcefield/openff-nagl/issues/78 From 47c7d698128c0273ac677747ea34beff13a78ca9 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 23 Sep 2025 15:12:41 -0700 Subject: [PATCH 02/16] add nagl test news item --- news/expect_nagl.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/expect_nagl.rst diff --git a/news/expect_nagl.rst b/news/expect_nagl.rst new file mode 100644 index 000000000..9f2dd75cb --- /dev/null +++ b/news/expect_nagl.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* Updated tests to expect to find NAGL, now that it is supported. + +**Security:** + +* From e1328abead51b48e7a763a6fb4fba425c91c0999 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Wed, 13 Aug 2025 15:43:02 -0700 Subject: [PATCH 03/16] debug slow python 3.13 tests (#1468) * Turn off minimization when we do a dry run --------- Co-authored-by: IAlibay --- news/no_fire_dryrun.rst | 23 +++++++++++++++++++ .../protocols/openmm_rfe/equil_rfe_methods.py | 3 +++ .../openmm_rfe/test_hybrid_top_protocol.py | 14 ++++++----- 3 files changed, 34 insertions(+), 6 deletions(-) create mode 100644 news/no_fire_dryrun.rst diff --git a/news/no_fire_dryrun.rst b/news/no_fire_dryrun.rst new file mode 100644 index 000000000..abadfa6c7 --- /dev/null +++ b/news/no_fire_dryrun.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* The relative hybrid topology protocol no longer runs the FIRE minimizer when ``dry=True``. + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/openfe/protocols/openmm_rfe/equil_rfe_methods.py b/openfe/protocols/openmm_rfe/equil_rfe_methods.py index 4d8b58eae..c7786f732 100644 --- a/openfe/protocols/openmm_rfe/equil_rfe_methods.py +++ b/openfe/protocols/openmm_rfe/equil_rfe_methods.py @@ -1043,6 +1043,9 @@ def run(self, *, dry=False, verbose=True, temperature=to_openmm(thermo_settings.temperature), endstates=alchem_settings.endstate_dispersion_correction, minimization_platform=platform.getName(), + # Turns off minimization when running in dry mode + # otherwise do a very small one to avoid NaNs + minimization_steps=100 if not dry else 0 ) try: diff --git a/openfe/tests/protocols/openmm_rfe/test_hybrid_top_protocol.py b/openfe/tests/protocols/openmm_rfe/test_hybrid_top_protocol.py index 75f27792f..ec17dd206 100644 --- a/openfe/tests/protocols/openmm_rfe/test_hybrid_top_protocol.py +++ b/openfe/tests/protocols/openmm_rfe/test_hybrid_top_protocol.py @@ -2067,24 +2067,26 @@ def test_dry_run_complex_alchemwater_totcharge( mapping_name, chgA, chgB, correction, core_atoms, new_uniq, old_uniq, tmpdir, request, T4_protein_component, ): - mapping = request.getfixturevalue(mapping_name) + solvent = openfe.SolventComponent() stateA_system = openfe.ChemicalSystem( {'ligand': mapping.componentA, - 'solvent': openfe.SolventComponent(), + 'solvent': solvent, 'protein': T4_protein_component} ) stateB_system = openfe.ChemicalSystem( {'ligand': mapping.componentB, - 'solvent': openfe.SolventComponent(), + 'solvent': solvent, 'protein': T4_protein_component} ) - solv_settings = openmm_rfe.RelativeHybridTopologyProtocol.default_settings() - solv_settings.alchemical_settings.explicit_charge_correction = correction + settings = openmm_rfe.RelativeHybridTopologyProtocol.default_settings() + settings.solvation_settings.solvent_padding="0.9 nm" + settings.solvation_settings.box_shape="dodecahedron" + settings.alchemical_settings.explicit_charge_correction = correction protocol = openmm_rfe.RelativeHybridTopologyProtocol( - settings=solv_settings, + settings=settings, ) # create DAG from protocol and take first (and only) work unit from within From 1a3591e3c17f541f935c719c2794aafd9f9fab3f Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Thu, 21 Aug 2025 08:52:37 -0700 Subject: [PATCH 04/16] update quickrun execution docs and add MPS link (#1483) --- docs/guide/execution/quickrun_execution.rst | 53 ++++++++++----------- 1 file changed, 24 insertions(+), 29 deletions(-) diff --git a/docs/guide/execution/quickrun_execution.rst b/docs/guide/execution/quickrun_execution.rst index 23ebe51dc..3af553cc2 100644 --- a/docs/guide/execution/quickrun_execution.rst +++ b/docs/guide/execution/quickrun_execution.rst @@ -3,34 +3,25 @@ Execution with Quickrun ======================= -The planning and preparation of a campaign of alchemical simulations using the ``openfe`` package is intended to be -achievable on a local workstation in a matter of minutes. -The **execution** of these simulations however requires a large amount of computational power, -and beyond running single calculations locally, -is intended to be distributed across a HPC environment. -Doing this requires storing and sending the details of the simulation from the local workstation to a HPC environment, -this can be done via the :func:`.Transformation.dump` function which -:ref:`creates a saved "json" version of the data`. -These serialised "json" files are the currency of executing a campaign of simulations, -and contain all the information required to execute a single simulation. - -To read this information and execute the simulation, the command line interface provides a ``quickrun`` command, -the full details of which are given in :ref:`the CLI reference section`. -Briefly, this command takes a "json" simulation as an input and will then execute the simulation contained within, -therefore this command would execute a simulation saved to a file called "transformation.json". +The planning and preparation of a campaign of alchemical simulations using ``openfe`` is intended to be achievable on a local workstation in a matter of minutes. +The *execution* of these simulations however requires a large amount of computational power, and beyond running single calculations locally, is intended to be distributed across a HPC environment. +Doing this requires storing and sending the details of the simulation from the local workstation to a HPC environment, which can be done via the :func:`.Transformation.to_json` function which :ref:`creates a saved JSON version of the data`. +These serialized JSON files are the currency of executing a campaign of simulations and contain all the information required to execute a single simulation. + +To read the ``Transformation`` information and execute the simulation, the command line interface provides the ``openfe quickrun`` command, the full details of which are given in :ref:`the CLI reference section`. +Briefly, this command takes in the ``Transformation`` information represented as JSON, then executes a simulation according to those specifications. +For example, the following command executes a simulation defined by ``transformation.json`` and produces a results file named ``results.json``. :: openfe quickrun transformation.json -o results.json -Which will produce a results file called ``results.json``. - Executing within a job submission script ---------------------------------------- -It is likely that computational jobs will be submitted to a queueing engine, such as slurm. -The ``quickrun`` command can be integrated into as: +You may need to submit computational jobs to a queueing engine, such as Slurm. +The ``openfe quickrun`` command can be used within a submission script as follows: :: @@ -44,24 +35,22 @@ The ``quickrun`` command can be integrated into as: openfe quickrun transformation.json -o results.json + Parallel execution of repeats with Quickrun =========================================== Serial execution of multiple repeats of a transformation can be inefficient when simulation times are long. -Higher throughput can be achieved with parallel execution by running one repeat per HPC job. Most protocols are set up to -run three repeats in serial by default, but this can be changed by either: - +Higher throughput can be achieved with parallel execution by running one repeat per HPC job. +Most protocols are set up to run three repeats in serial by default, but this can be changed by either: + 1. Defining the protocol setting ``protocol_repeats`` - see the :ref:`protocol configuration guide ` for more details. 2. Using the ``openfe plan-rhfe-network`` (or ``plan-rbfe-network``) command line flag ``--n-protocol-repeats``. -Each transformation can then be executed multiple times via the -``openfe quickrun`` command to produce a set of repeats, however, you need to ensure to use unique results -files for each repeat to ensure they don't overwrite each other. We recommend using folders named ``results_x`` where x is 0-2 -to store the repeated calculations as our :ref:`openfe gather ` command also supports this file structure. +Each transformation can then be executed multiple times via the ``openfe quickrun`` command to produce a set of repeats. +However, **you must use unique results files for each repeat to ensure they don't overwrite each other**. +We recommend using folders named ``results_x`` where x is 0-2 to store the repeated calculations as our :ref:`openfe gather ` command also supports this file structure. -Here is an example of a simple script that will create and submit a separate job script (``\*.job`` named file) -for every alchemical transformation (for the simplest SLURM use case) in a network running each repeat in parallel and writing the -results to a unique folder: +Below is an example of a simple script that will create and submit a separate job script (``\*.job`` named file) for every alchemical transformation (for the simplest SLURM use case) in a network running each repeat in parallel and writing the results to a unique folder: .. code-block:: bash @@ -111,6 +100,12 @@ it to the root directory which includes the repeat results and it will automatic openfe gather results_parallel +Optimizing GPU performance with NVIDIA MPS +========================================== + +You can further optimize execution of ``openfe quickrun`` using NVIDIA's Multi-Process Service (MPS). +See NVIDIA's documentation on `MPS for OpenFE free energy calculations `_ for details. + See Also -------- From c26fd09ef6ad088185f917f2f08a27e4ed210f8d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Mon, 25 Aug 2025 10:25:52 -0700 Subject: [PATCH 05/16] add jq cookbook (#1488) * add jq code blocks * use tutorial data * news --- docs/cookbook/index.rst | 1 + docs/cookbook/jq_inspection.rst | 61 +++++++++++++++++++++++++++++++++ news/add_jq_docs.rst | 23 +++++++++++++ 3 files changed, 85 insertions(+) create mode 100644 docs/cookbook/jq_inspection.rst create mode 100644 news/add_jq_docs.rst diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst index 30ba7b591..84f0996b4 100644 --- a/docs/cookbook/index.rst +++ b/docs/cookbook/index.rst @@ -153,6 +153,7 @@ List of Cookbooks loading_molecules dumping_transformation + jq_inspection choose_protocol generate_ligand_network rfe_alchemical_planners diff --git a/docs/cookbook/jq_inspection.rst b/docs/cookbook/jq_inspection.rst new file mode 100644 index 000000000..f779c89fe --- /dev/null +++ b/docs/cookbook/jq_inspection.rst @@ -0,0 +1,61 @@ +.. _jq_inspection: + +Using ``jq`` to inspect OpenFE JSONs +============================================== +Sometimes you may want to get a sense of the contents of JSON files, but the files are too unwieldy to inspect one-by-one in a code editor. + +`jq `_ is a helpful command-line tool that we recommend for for quickly inspecting JSON files. + +Below is a common use-case to get you started, but you can do much more by checking out the `jq manual `_. + +To view all the top-level JSON keys, use ``jq "keys" filename.json``, for example with a results JSON from the tutorial: + +.. code:: bash + + $ jq "keys" rbfe_lig_ejm_46_solvent_lig_jmc_28_solvent.json + [ + "estimate", + "protocol_result", + "uncertainty", + "unit_results" + ] + +.. note:: + + You can use ``"keys[]"`` instead of ``"keys"`` for a cleaner output. + +Now that we know ``estimate`` is at the top-level of the JSON, we can use the following command to see all the values for the ``estimate`` key: + +.. code:: bash + + $ jq ".estimate" rbfe_lig_ejm_46_solvent_lig_jmc_28_solvent.json + { + "magnitude": 23.347074789078682, + "unit": "kilocalorie / mole", + ":is_custom:": true, + "pint_unit_registry": "openff_units" + } + +This can be very helpful for quickly checking results for many files, for example: + +.. code:: bash + + $ jq ".estimate.magnitude" rbfe*.json + -14.925911852820793 + -40.72063957254803 + -27.76541486479537 + -16.023754604070007 + -57.38608716292447 + -15.748326155729705 + -39.933880531487326 + -27.780933075807425 + -16.76023951588401 + -58.36294851896545 + -19.038006312251575 + -20.26856586311034 + 17.338257573349775 + 15.775784163095102 + 23.134622420900932 + 17.071712542470248 + 15.873122071409249 + 23.347074789078682 diff --git a/news/add_jq_docs.rst b/news/add_jq_docs.rst new file mode 100644 index 000000000..b1a8c34b0 --- /dev/null +++ b/news/add_jq_docs.rst @@ -0,0 +1,23 @@ +**Added:** + +* Added a cookbook for using ``jq`` to inspect JSON files. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* From a811a81cd1900062f4105549e0a9c66f2af99268 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Tue, 26 Aug 2025 07:34:40 -0700 Subject: [PATCH 06/16] debug docs build (#1489) * don't build openmm * mambaforge->miniconda for rtd * artifically small build for debugging * dont build env * just build python * add channels * add sphinx packages to env * add all non-openfe-ecosystem deps * remove shim channel * add openfe package * add everything except openmm and toolkit * add openmm * add openff-toolkit * only openff-toolkit * try openff-toolkit-base * try latest openff * everybody back in * build without openmm * build with openff-toolkit-base * bump rtd * add pip build * remove any openff-toolkit * build w/o openmm * add pip install * build everything without pip install * try no deps * try custom build * only python and pip * try openfe-toolkit-base * add temp deps for build with openff-toolkit-base * add temp deps for build with openff-toolkit-base * mock imports * dont mock with toolkit base * bump toolkit version * Revert "bump toolkit version" This reverts commit 6e3108a836666deed87c8d98145d2d1b7fda07b1. * add mocks * try pinnint to toolkit-base 0.13.0, no mocks * back to >= 0.13.0 toolkit to make sure it wasn't a fluke * mock imports --- .readthedocs.yaml | 4 ++-- docs/conf.py | 3 +++ docs/environment.yaml | 47 ++++++++++++++++++++++--------------------- 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 1275754bc..501592fc2 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,9 +1,9 @@ version: 2 build: - os: "ubuntu-20.04" + os: "ubuntu-24.04" tools: - python: "mambaforge-4.10" + python: "miniconda3-3.12-24.9" sphinx: configuration: docs/conf.py diff --git a/docs/conf.py b/docs/conf.py index 428b5b0b0..d7c9942df 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -107,6 +107,9 @@ "openmmforcefields", "openmmtools", "pymbar", + "openff.interchange", + "openmmforcefields", + "psutil" ] # Extensions for the myst parser diff --git a/docs/environment.yaml b/docs/environment.yaml index be3ed075b..e320becce 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -1,30 +1,31 @@ name: openfe-docs channels: -- https://conda.anaconda.org/jaimergp/label/unsupported-cudatoolkit-shim - https://conda.anaconda.org/conda-forge + +# explicit pins to speed up build: dependencies: -- autodoc-pydantic <2.0 -- gitpython -- kartograf >=1.0.0 -- konnektor >=0.2.0 -- libsass -- lomap2 >=3.0.0 -- myst-parser -- nbsphinx -- nbsphinx-link -- openff-toolkit >=0.13.0 -- openff-units -- openmm -- packaging -- pip -- plugcli -- python=3.11 -- sphinx <7.3 -- sphinx-click -- sphinx-design -- sphinx-toolbox -- threadpoolctl -- tqdm +- autodoc-pydantic == 1.9.0 +- gitpython == 3.1.45 +- kartograf == 1.2.0 +- konnektor == 0.2.0 +- libsass == 0.22.0 +- lomap2 == 3.2.1 +- myst-parser == 4.0.1 +- nbsphinx == 0.9.7 +- nbsphinx-link == 1.3.0 +- openff-toolkit-base >= 0.13.0 +- openff-units == 0.3.1 +- openmm == 8.3.1 +- packaging == 25.0 +- pip == 25.2 +- plugcli == 0.2.1 +- python == 3.11.13 +- sphinx == 7.2.6 +- sphinx-click == 6.0.0 +- sphinx-design == 0.6.1 +- sphinx-toolbox == 4.0.0 +- threadpoolctl == 3.6.0 +- tqdm == 4.67.1 - pip: - git+https://github.com/OpenFreeEnergy/gufe@main - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.2.0 From 59787cd88aee27a0dc081ce0c26392032c7dc39d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Fri, 12 Sep 2025 13:12:56 -0700 Subject: [PATCH 07/16] add pipe example for jq (#1505) * add pipe example for jq * pin to docutil 0.20 * try to avoid memory error --- docs/cookbook/jq_inspection.rst | 16 +++++++++++++++- docs/environment.yaml | 11 ++++++----- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/cookbook/jq_inspection.rst b/docs/cookbook/jq_inspection.rst index f779c89fe..3df27299a 100644 --- a/docs/cookbook/jq_inspection.rst +++ b/docs/cookbook/jq_inspection.rst @@ -24,7 +24,20 @@ To view all the top-level JSON keys, use ``jq "keys" filename.json``, for exampl You can use ``"keys[]"`` instead of ``"keys"`` for a cleaner output. -Now that we know ``estimate`` is at the top-level of the JSON, we can use the following command to see all the values for the ``estimate`` key: +Now that you know ``estimate`` is at the top-level of the JSON, you can use the following pattern to see the next level of keys: + +.. code:: bash + + $ jq ".estimate | keys " rbfe_lig_ejm_46_solvent_lig_jmc_28_solvent.json + { + "magnitude", + "unit":, + ":is_custom:":, + "pint_unit_registry": + } + + +If you want to show all the keys _and_ their values, simply omit ``| key`` from the query: .. code:: bash @@ -36,6 +49,7 @@ Now that we know ``estimate`` is at the top-level of the JSON, we can use the fo "pint_unit_registry": "openff_units" } + This can be very helpful for quickly checking results for many files, for example: .. code:: bash diff --git a/docs/environment.yaml b/docs/environment.yaml index e320becce..1da231556 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -5,6 +5,7 @@ channels: # explicit pins to speed up build: dependencies: - autodoc-pydantic == 1.9.0 +- docutils == 0.20 - gitpython == 3.1.45 - kartograf == 1.2.0 - konnektor == 0.2.0 @@ -13,7 +14,7 @@ dependencies: - myst-parser == 4.0.1 - nbsphinx == 0.9.7 - nbsphinx-link == 1.3.0 -- openff-toolkit-base >= 0.13.0 +- openff-toolkit-base == 0.17.0 - openff-units == 0.3.1 - openmm == 8.3.1 - packaging == 25.0 @@ -32,7 +33,7 @@ dependencies: # These are added automatically by RTD, so we include them here # for a consistent environment. -- mock -- pillow -- sphinx -- sphinx_rtd_theme +- mock==5.2.0 +- pillow==11.3.0 +# - sphinx +# - sphinx_rtd_theme From 3e706297cb00a849517093d53afc81263258467e Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Mon, 15 Sep 2025 13:32:22 -0700 Subject: [PATCH 08/16] debug rtd build memory error (#1510) * try mambaforge build * Revert "try mambaforge build" This reverts commit 683e07f1eaf4b6f16dfc253df02f2087dbf897ac. * try explicit build * try removing ambertools * use the right env * just add gufe pip install back * add back openfe eco packages * mock py3dmol * add note for pip installs * fix quote * temporarily resort to SettingsBaseModel to get build * specific imports * dont use base settings placeholder --- docs/conf.py | 3 ++- docs/environment.yaml | 8 +++++--- docs/reference/api/openmm_rfe.rst | 12 +++++------- docs/reference/api/openmm_solvation_afe.rst | 11 ++++------- 4 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d7c9942df..8a4240c5f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -109,7 +109,8 @@ "pymbar", "openff.interchange", "openmmforcefields", - "psutil" + "psutil", + "py3Dmol", ] # Extensions for the myst parser diff --git a/docs/environment.yaml b/docs/environment.yaml index 1da231556..8dbc33aa7 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -7,10 +7,7 @@ dependencies: - autodoc-pydantic == 1.9.0 - docutils == 0.20 - gitpython == 3.1.45 -- kartograf == 1.2.0 -- konnektor == 0.2.0 - libsass == 0.22.0 -- lomap2 == 3.2.1 - myst-parser == 4.0.1 - nbsphinx == 0.9.7 - nbsphinx-link == 1.3.0 @@ -30,6 +27,11 @@ dependencies: - pip: - git+https://github.com/OpenFreeEnergy/gufe@main - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.2.0 + # pip install these so that conda-forge gufe doesn't pull in ambertools and cause a memory error + - git+https://github.com/OpenFreeEnergy/kartograf@main + - git+https://github.com/OpenFreeEnergy/konnektor@main + - git+https://github.com/OpenFreeEnergy/lomap@main + # These are added automatically by RTD, so we include them here # for a consistent environment. diff --git a/docs/reference/api/openmm_rfe.rst b/docs/reference/api/openmm_rfe.rst index 085c06c10..8e03d1d36 100644 --- a/docs/reference/api/openmm_rfe.rst +++ b/docs/reference/api/openmm_rfe.rst @@ -9,7 +9,7 @@ implemented in OpenFE. Protocol API specification -------------------------- -.. module:: openfe.protocols.openmm_rfe +.. module:: openfe.protocols.openmm_rfe.equil_rfe_methods .. autosummary:: :nosignatures: @@ -25,7 +25,7 @@ Protocol Settings Below are the settings which can be tweaked in the protocol. The default settings (accessed using :meth:`RelativeHybridTopologyProtocol.default_settings`) will automatically populate a settings which we have found to be useful for running relative binding free energies using explicit solvent. There will however be some cases (such as when doing gas phase calculations) where you will need to tweak some of the following settings. -.. autopydantic_model:: RelativeHybridTopologyProtocolSettings +.. autopydantic_model:: openfe.protocols.openmm_rfe.equil_rfe_settings.RelativeHybridTopologyProtocolSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False @@ -41,11 +41,9 @@ Below are the settings which can be tweaked in the protocol. The default setting Protocol Specific Settings Classes ---------------------------------- -Below are Settings classes which are unique to the `RelativeHybridTopologyProtocol`. +Below are Settings classes which are unique to the ``RelativeHybridTopologyProtocol``. -.. module:: openfe.protocols.openmm_rfe.equil_rfe_settings - -.. autopydantic_model:: AlchemicalSettings +.. autopydantic_model:: openfe.protocols.openmm_rfe.equil_rfe_settings.AlchemicalSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False @@ -56,7 +54,7 @@ Below are Settings classes which are unique to the `RelativeHybridTopologyProtoc :inherited-members: SettingsBaseModel :member-order: bysource -.. autopydantic_model:: LambdaSettings +.. autopydantic_model:: openfe.protocols.openmm_rfe.equil_rfe_settings.LambdaSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False diff --git a/docs/reference/api/openmm_solvation_afe.rst b/docs/reference/api/openmm_solvation_afe.rst index 928fb3c53..de8ef1181 100644 --- a/docs/reference/api/openmm_solvation_afe.rst +++ b/docs/reference/api/openmm_solvation_afe.rst @@ -27,9 +27,7 @@ Protocol Settings Below are the settings which can be tweaked in the protocol. The default settings (accessed using :meth:`AbsoluteSolvationProtocol.default_settings`) will automatically populate settings which we have found to be useful for running solvation free energy calculations. There will however be some cases (such as when calculating difficult to converge systems) where you will need to tweak some of the following settings. -.. module:: openfe.protocols.openmm_afe.equil_afe_settings - -.. autopydantic_model:: AbsoluteSolvationSettings +.. autopydantic_model:: openfe.protocols.openmm_afe.equil_afe_settings.AbsoluteSolvationSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False @@ -45,10 +43,9 @@ Below are the settings which can be tweaked in the protocol. The default setting Protocol Specific Settings Classes ---------------------------------- -Below are Settings classes which are unique to the `AbsoluteSolvationProtocol`. - +Below are Settings classes which are unique to the ``AbsoluteSolvationProtocol``. -.. autopydantic_model:: AlchemicalSettings +.. autopydantic_model:: openfe.protocols.openmm_afe.equil_afe_settings.AlchemicalSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False @@ -59,7 +56,7 @@ Below are Settings classes which are unique to the `AbsoluteSolvationProtocol`. :inherited-members: SettingsBaseModel :member-order: bysource -.. autopydantic_model:: LambdaSettings +.. autopydantic_model:: openfe.protocols.openmm_afe.equil_afe_settings.LambdaSettings :model-show-json: False :model-show-field-summary: False :model-show-config-member: False From 500e215291998a63225dfbe1132d9a9276c0d3d4 Mon Sep 17 00:00:00 2001 From: Irfan Alibay Date: Mon, 29 Sep 2025 12:55:21 +0100 Subject: [PATCH 09/16] temp pin numpy (#1542) --- environment.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/environment.yml b/environment.yml index acd85e538..d9fee6136 100644 --- a/environment.yml +++ b/environment.yml @@ -10,7 +10,7 @@ dependencies: - konnektor~=0.2.0 - lomap2>=3.2.1 - networkx - - numpy + - numpy<2.3 - openfe-analysis>=0.3.1 - openff-interchange-base - openff-nagl-base >=0.3.3 From a18feedf886224f94e9b646d35f7f88014d216dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Iv=C3=A1n=20Pulido?= <2949729+ijpulidos@users.noreply.github.com> Date: Mon, 29 Sep 2025 09:23:27 -0400 Subject: [PATCH 10/16] Removing unnecessary limit on resids (#1539) * Removing unnecessary limit on resids indices gathering --- news/no-resids-limit-from-topology.rst | 23 +++++++++++++++++++ .../openmm_rfe/_rfe_utils/topologyhelpers.py | 9 +++----- 2 files changed, 26 insertions(+), 6 deletions(-) create mode 100644 news/no-resids-limit-from-topology.rst diff --git a/news/no-resids-limit-from-topology.rst b/news/no-resids-limit-from-topology.rst new file mode 100644 index 000000000..b0e860ad6 --- /dev/null +++ b/news/no-resids-limit-from-topology.rst @@ -0,0 +1,23 @@ +**Added:** + +* + +**Changed:** + +* Remove unnecessary limit on residues ids (``resids``) when getting mappings from topology in ``topology_helpers.py`` utility module. + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/openfe/protocols/openmm_rfe/_rfe_utils/topologyhelpers.py b/openfe/protocols/openmm_rfe/_rfe_utils/topologyhelpers.py index c8831439b..57aec6f86 100644 --- a/openfe/protocols/openmm_rfe/_rfe_utils/topologyhelpers.py +++ b/openfe/protocols/openmm_rfe/_rfe_utils/topologyhelpers.py @@ -387,13 +387,10 @@ def _get_indices(topology, resids): ---------- topology : openmm.app.Topology Topology to search from. - residue_name : str - Name of the residue to get the indices for. + resids : npt.NDArrayLike + An array of residue indices which match the residues we want to get + atom indices for. """ - # TODO: remove, this shouldn't be necessary anymore - if len(resids) > 1: - raise ValueError("multiple residues were found") - # create list of openmm residues top_res = [r for r in topology.residues() if r.index in resids] From 6890751a2583fec36b3d69e278d9d2af3ee768a3 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 30 Sep 2025 14:05:19 -0400 Subject: [PATCH 11/16] Updated CHANGELOG for 1.6.1 --- docs/CHANGELOG.rst | 18 ++++++++++++++++++ news/add_jq_docs.rst | 23 ----------------------- news/expect_nagl.rst | 23 ----------------------- news/no-resids-limit-from-topology.rst | 23 ----------------------- news/no_fire_dryrun.rst | 23 ----------------------- 5 files changed, 18 insertions(+), 92 deletions(-) delete mode 100644 news/add_jq_docs.rst delete mode 100644 news/expect_nagl.rst delete mode 100644 news/no-resids-limit-from-topology.rst delete mode 100644 news/no_fire_dryrun.rst diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index 110afde35..51f83c6ed 100644 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -4,6 +4,24 @@ Changelog .. current developments +v1.6.1 +==================== + +**Added:** + +* Added a cookbook for using ``jq`` to inspect JSON files. + +**Changed:** + +* Remove unnecessary limit on residues ids (``resids``) when getting mappings from topology in ``topology_helpers.py`` utility module. +* The relative hybrid topology protocol no longer runs the FIRE minimizer when ``dry=True``. + +**Fixed:** + +* Updated tests to expect to find NAGL, now that it is supported. + + + v1.6.0 ==================== This release adds support for OpenMM 8.3.0 and Python 3.13. diff --git a/news/add_jq_docs.rst b/news/add_jq_docs.rst deleted file mode 100644 index b1a8c34b0..000000000 --- a/news/add_jq_docs.rst +++ /dev/null @@ -1,23 +0,0 @@ -**Added:** - -* Added a cookbook for using ``jq`` to inspect JSON files. - -**Changed:** - -* - -**Deprecated:** - -* - -**Removed:** - -* - -**Fixed:** - -* - -**Security:** - -* diff --git a/news/expect_nagl.rst b/news/expect_nagl.rst deleted file mode 100644 index 9f2dd75cb..000000000 --- a/news/expect_nagl.rst +++ /dev/null @@ -1,23 +0,0 @@ -**Added:** - -* - -**Changed:** - -* - -**Deprecated:** - -* - -**Removed:** - -* - -**Fixed:** - -* Updated tests to expect to find NAGL, now that it is supported. - -**Security:** - -* diff --git a/news/no-resids-limit-from-topology.rst b/news/no-resids-limit-from-topology.rst deleted file mode 100644 index b0e860ad6..000000000 --- a/news/no-resids-limit-from-topology.rst +++ /dev/null @@ -1,23 +0,0 @@ -**Added:** - -* - -**Changed:** - -* Remove unnecessary limit on residues ids (``resids``) when getting mappings from topology in ``topology_helpers.py`` utility module. - -**Deprecated:** - -* - -**Removed:** - -* - -**Fixed:** - -* - -**Security:** - -* diff --git a/news/no_fire_dryrun.rst b/news/no_fire_dryrun.rst deleted file mode 100644 index abadfa6c7..000000000 --- a/news/no_fire_dryrun.rst +++ /dev/null @@ -1,23 +0,0 @@ -**Added:** - -* - -**Changed:** - -* The relative hybrid topology protocol no longer runs the FIRE minimizer when ``dry=True``. - -**Deprecated:** - -* - -**Removed:** - -* - -**Fixed:** - -* - -**Security:** - -* From 8dd0f4486347a1dfc571c92107bb8c1044be6833 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 30 Sep 2025 14:06:18 -0400 Subject: [PATCH 12/16] add summary --- docs/CHANGELOG.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst index 51f83c6ed..8032df6cd 100644 --- a/docs/CHANGELOG.rst +++ b/docs/CHANGELOG.rst @@ -6,6 +6,7 @@ Changelog v1.6.1 ==================== +This release includes minor fixes and updates to tests. **Added:** From b0719eb7fa9cf2a9226410549c63b0f9f66e79cc Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Thu, 2 Oct 2025 10:13:25 -0400 Subject: [PATCH 13/16] update docs theme (#1545) * adding new branding assets * remove images * update theme branch * CantinaPurple accent * lowercase convention * updating text * remove dark mode for now * fix sidebars * fix formatting * capitalization * don't break spaces * bump ci * favicon! * whitespace :( * pin to sphinx release --- docs/_static/OFE-color-icon.svg | 12 +++++++ docs/_static/Squaredcircle.svg | 21 ----------- docs/conf.py | 17 ++++++--- docs/environment.yaml | 4 +-- docs/guide/index.rst | 7 ++-- docs/index.rst | 64 +++++++++++++-------------------- 6 files changed, 56 insertions(+), 69 deletions(-) create mode 100644 docs/_static/OFE-color-icon.svg delete mode 100644 docs/_static/Squaredcircle.svg diff --git a/docs/_static/OFE-color-icon.svg b/docs/_static/OFE-color-icon.svg new file mode 100644 index 000000000..0a58ca515 --- /dev/null +++ b/docs/_static/OFE-color-icon.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/docs/_static/Squaredcircle.svg b/docs/_static/Squaredcircle.svg deleted file mode 100644 index a8fea245e..000000000 --- a/docs/_static/Squaredcircle.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - image/svg+xml - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 8a4240c5f..5ee206fad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -131,7 +131,7 @@ # html_theme = "ofe_sphinx_theme" html_theme_options = { - "logo": {"text": "OpenFE Documentation"}, + "logo": {"text": "OpenFE docs"}, "icon_links": [ { "name": "GitHub", @@ -140,11 +140,20 @@ "type": "fontawesome", } ], - "accent_color": "DarkGoldenYellow", + "accent_color": "cantina-purple", "navigation_with_keys": False, + "navbar_end": ["navbar-icon-links"], # TODO: add "theme-switcher" to add back dark mode toggle +} +html_logo = "_static/OFE-color-icon.svg" +html_favicon = '_static/OFE-color-icon.svg' +html_context = { + "default_mode": "light" +} +# temporary fix, see https://github.com/pydata/pydata-sphinx-theme/issues/1662 +html_sidebars = { + "installation": [], + "CHANGELOG":[], } -html_logo = "_static/Squaredcircle.svg" - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/environment.yaml b/docs/environment.yaml index 8dbc33aa7..016f8316e 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -25,8 +25,8 @@ dependencies: - threadpoolctl == 3.6.0 - tqdm == 4.67.1 - pip: - - git+https://github.com/OpenFreeEnergy/gufe@main - - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.2.0 + - git+https://github.com/OpenFreeEnergy/gufe@0e4d69a137c750136b3b2473bf6da9a34c28cb60 + - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.3.0 # pip install these so that conda-forge gufe doesn't pull in ambertools and cause a memory error - git+https://github.com/OpenFreeEnergy/kartograf@main - git+https://github.com/OpenFreeEnergy/konnektor@main diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 82db2830d..0f2acee81 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -1,5 +1,5 @@ -User Guide -========== +User\ |nbsp|\ Guide +=================== .. toctree:: :maxdepth: 2 @@ -12,3 +12,6 @@ User Guide protocols/index under_the_hood troubleshooting + +.. |nbsp| unicode:: 0xA0 .. copyright sign + :trim: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index e38f8d0fb..361befd7d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,87 +9,71 @@ Welcome to the OpenFE documentation! The **OpenFE** toolkit provides a free and open-source framework for alchemical free energy calculations. Using this toolkit you can plan, execute and analyse free energy calculations using a variety of methods. -The Documentation serves as a rapid initiation, offering a brief overview of the software, -including an introduction to the OpenFE Showcase and installation instructions. -For a more in-depth understanding, -the Tutorials illustrate the application of the package, -while the User Guide describe the theoretical framework and structure of the package. -The Cookbook supplies snippets of code for various minor tasks, -and lastly, the API Reference provides a direct technical explanation of our code. - **Useful Links**: `OpenFE Website `__ | `Example Tutorial notebooks `__ | `Source Repository `__ | `Issues & Ideas `__ -.. grid:: 1 2 3 4 +.. grid:: 1 2 2 4 :gutter: 3 - .. grid-item-card:: Try it out - :img-top: _static/Rocket.svg + .. grid-item-card:: :fas:`laptop-code` Try openfe in your browser :text-align: center :link: http://try.openfree.energy :link-type: url - New to *OpenFE*? Start here and try it from your browser + Curious about **openfe**? Start here and run the openfe showcase notebook in your browser. - .. grid-item-card:: Installing OpenFE - :img-top: _static/Download.svg + .. grid-item-card:: :fas:`download` Install openfe :text-align: center :link: installation :link-type: doc - Check out our installation guide to get it working on your machine! + Follow our installation guide to get **openfe** running on your machine! + - .. grid-item-card:: Available Protocols - :img-top: _static/CLI.svg + .. grid-item-card:: :fas:`person-chalkboard` Tutorials :text-align: center - :link: guide/protocols/index + :link: tutorials/index :link-type: doc - Documentation on available methods included in the openfe package + Step-by-step examples showing how to use the OpenFE toolkit. - .. grid-item-card:: Changelog - :img-top: _static/Showcase.svg + .. grid-item-card:: :fas:`book-open-reader` User Guide :text-align: center - :link: CHANGELOG + :link: guide/index :link-type: doc - Any notable changes in the package for each released version + Explanations of key concept underlying the OpenFE toolkit. - .. grid-item-card:: Tutorials - :img-top: _static/Tutorial.svg + .. grid-item-card:: :fas:`table-list` Cookbooks :text-align: center - :link: tutorials/index + :link: cookbook/index :link-type: doc - Worked through examples of how to use the OpenFE toolkit + How-to guides for common tasks. - .. grid-item-card:: User Guide - :img-top: _static/UserGuide.svg + .. grid-item-card:: :fas:`code` API Reference :text-align: center - :link: guide/index + :link: reference/index :link-type: doc - Explanations of the underlying concepts behind the OpenFE toolkit + Comprehensive details of both the **openfe** CLI and Python API. - .. grid-item-card:: Cookbook - :img-top: _static/Cookbook.svg + .. grid-item-card:: :fas:`gears` Protocols :text-align: center - :link: cookbook/index + :link: guide/protocols/index :link-type: doc - How-to guides for toolkit components + Details of the specific Free Energy Protocols included in **openfe**. - .. grid-item-card:: API Reference - :img-top: _static/API.svg + .. grid-item-card:: :fas:`clock-rotate-left` Changelog :text-align: center - :link: reference/index + :link: CHANGELOG :link-type: doc - Technical details on the toolkit's core methods and classes - + A history of **openfe** releases. .. toctree:: :maxdepth: 2 From 5e7e20e8b15992a1012792fd5fbc27ad9b405c80 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Thu, 2 Oct 2025 17:13:26 -0400 Subject: [PATCH 14/16] pin to gufe 1.6.1 --- docs/environment.yaml | 2 +- environment.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/environment.yaml b/docs/environment.yaml index 016f8316e..4748f8663 100644 --- a/docs/environment.yaml +++ b/docs/environment.yaml @@ -25,7 +25,7 @@ dependencies: - threadpoolctl == 3.6.0 - tqdm == 4.67.1 - pip: - - git+https://github.com/OpenFreeEnergy/gufe@0e4d69a137c750136b3b2473bf6da9a34c28cb60 + - git+https://github.com/OpenFreeEnergy/gufe@v1.6.1 - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.3.0 # pip install these so that conda-forge gufe doesn't pull in ambertools and cause a memory error - git+https://github.com/OpenFreeEnergy/kartograf@main diff --git a/environment.yml b/environment.yml index d9fee6136..36ba22da5 100644 --- a/environment.yml +++ b/environment.yml @@ -51,4 +51,4 @@ dependencies: # Control blas/openmp threads - threadpoolctl - pip: - - git+https://github.com/OpenFreeEnergy/gufe@main + - git+https://github.com/OpenFreeEnergy/gufe@v1.6.1 From 41cf14fb3ed580267a6ff04404ef8bad30b4b5a5 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Thu, 2 Oct 2025 19:05:39 -0400 Subject: [PATCH 15/16] move env info before test imports --- .github/workflows/ci.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index e5526db34..7bb32a176 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -86,17 +86,17 @@ jobs: - name: "Install" run: python -m pip install --no-deps -e . - - name: "Test imports" - run: | - # if we add more to this, consider changing to for + env vars - python -Ic "import openfe; print(openfe.__version__)" - - name: "Environment Information" run: | micromamba info micromamba list pip list + - name: "Test imports" + run: | + # if we add more to this, consider changing to for + env vars + python -Ic "import openfe; print(openfe.__version__)" + - name: "Run tests" env: # Set the OFE_SLOW_TESTS to True if running a Cron job From 09afb5103d3d3a356b4ad562e4ab42acaa628fb7 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Fri, 3 Oct 2025 10:12:34 -0400 Subject: [PATCH 16/16] bump single file installer to 3.12.11 to match colab --- devtools/installer/construct.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devtools/installer/construct.yaml b/devtools/installer/construct.yaml index c863c1d2e..755add0fc 100644 --- a/devtools/installer/construct.yaml +++ b/devtools/installer/construct.yaml @@ -21,7 +21,7 @@ specs: - pytest-xdist # python needs to match https://github.com/googlecolab/backend-info/blob/main/os-info.txt # until colab pushes a fix - - python 3.11.12 + - python 3.12.11 # Not building an .exe for windows or a .pkg for macOS installer_type: sh