Changelog#

v1.7.0#

This release brings several long awaited features to OpenFE, including the SepTop and ABFE Protocols, as well as the adoption of more computationally efficient settings in the CLI and across the Python API.

The v1.7.0 release also comes with some API changes and breaks, including:

  • “CUDA” is now the default platform in the settings, you will need to change this if you run on a non-NVIDIA-powered platform.

  • The default solvation cutoff is now 1.5 nm, to avoid issues with small boxes when dealing with ligands in solvent. When calculating complexes using the MD or HybridTopology Protocols with the API, you will need to reduce this value to ~ 1 nm to avoid excessively large water boxes.

  • The API has fully migrated to Pydantic V2 and the GufeQuantity scheme. This only affects Protocol developers. If needed, please see the gufe typing documentation for more details.

Note that if you want to use NAGL to assign partial charges, you must use python >= 3.11. Python 3.10 support is no longer maintained according to SPEC 0 guidelines. The openfe lock file and docker and apptainer images use Python 3.12, and so charge assignment with NAGL will work without intervention.

Added:

Changed:

  • The default atom mapper used in the CLI has been changed from LomapAtomMapper to KartografAtomMapper in line with the recommended defaults from the industry benchmarking paper. Users who whish to continue to use LomapAtomMapper can do so via the YAML configuration file. See the documentation for details (PR #1530).

  • An improved error message is now shown when a mapping involving a changing constraint length cannot be fixed (PR #1529).

  • The default platform for OpenMM-based Protocols is now CUDA and will fail by default on a non-Nvidia GPU enabled system (PR #1576).

  • Remove unnecessary limit on residues ids (resids) when getting mappings from topology in topology_helpers.py utility module (PR #1539).

  • The relative hybrid topology protocol no longer runs the FIRE minimizer when dry=True (PR #1468).

  • Units must be explicitly assigned when defining Settings parameters, and values will be converted to match the default units for a given field. For example, use 1.0 * units.bar or "1 bar" for pressure, and 300 * unit.kelvin or "300 kelvin" for temperature.

  • For protocol developers: FloatQuantity is no longer supported. Instead, use GufeQuantity and specify_quantity_units() to make a TypeAlias. See the gufe typing documentation for more details.

  • The default time_per_iteration setting of the MultiStateSimulationSettings class has been increased from 1.0 ps to 2.5 ps as part of the fast settings update (PR #1523).

  • The default box_shape setting of the OpenMMSolvationSettings class has been changed from cubic to dodecahedron to improve simulation efficiency as part of the fast settings update (PR #1523).

  • The default solvent_padding settings of the OpenMMSolvationSettings class has been increased from 1.2 nm to 1.5 nm to be compatible with the new box_shape default as part of the fast settings update (PR #1523).

  • The default nonbonded_cutoff setting of the OpenMMSystemGeneratorFFSettings class has been decreased to 0.9 nm from 1.0 nm, in line with current force fields best practices and our newly validated fast settings (PR #1523).

  • When calling the CLI openfe plan_rbfe_network, the RelativeHybridTopologyProtocol settings now reflects the above “fast” settings updates. This includes;

    • Dodecahedron box solvation

    • Solvation cutoff of 1.5 nm in solvent-only legs, and 1.0 nm in complex legs

    • A replica exchange rate of 2.5 ps

    • A 0.9 nm nonbonded cutoff

Deprecated:

  • Deprecated openfe.utils.visualization_3D.view_mapping_3d(). Use the method LigandAtomMapping.view_3d() instead (PR #1592).

  • Deprecated openfe.utils.ligand_utils.get_alchemical_charge_difference(), which is replaced by LigandAtomMapping.get_alchemical_charge_difference() in gufe (PR #1479).

Fixed:

  • Charged molecules are now explicitly disallowed in the AbsoluteSolvationProtocol(PR #1572).

v1.6.1#

This release includes minor fixes and updates to tests.

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.

Added:

  • Added support for openmm 8.3.0 (benchmarking results at Issue #1377.

  • Added support for python 3.13 (we no longer guarantee support for python 3.10).

  • Adds a new internal API for defining alchemical restraints (PR #1043).

v1.5.0#

This release includes support for openmm 8.2 and numpy v2. Checkpoint interval default frequency has changed, resulting in much smaller file sizes. There are also a few minor changes as a result of migrating to use konnektor as the backend for many network generators.

Added:

  • Added support for openmm 8.2 (PR #1366)

  • Added optional n_processes (number of parallel processes to use when generating the network) arguments for network planners (PR #927).

  • Added optional progress (whether to show progress bar) for openfe.setup.ligand_network_planning.generate_radial_network (default= False, such that there is no default behavior change)(PR #927).

  • Added compatibility for numpy v2 (PR #1260).

Changed:

  • The checkpoint interval default frequency has been increased to every nanosecond. real_time_analysis_interval no longer needs to be divisible by the checkpoint interval, allowing users of the HybridTopologyProtocol and AbsoluteSolvationProtocol to write checkpoints less frequently and yielding smaller file sizes.

  • konnektor is now used as the backend for all network generation (PR #927).

  • openfe.setup.ligand_network_planning.generate_maximal_network now returns the best mapping for each edge, rather than all possible mappings for each edge. If multiple mappers are passed but no scorer, the first mapper passed will be used, and a warning will be raised (PR #927).

Fixed:

  • Absolute free energy calculations (e.g. AbsoluteSolvationProtocol) now correctly pass the equilibrated box vectors to the alchemical simulation. In the past default vectors were used, which in some cases led to random crashes due to an abrupt volume change. We do not believe that this significantly affected free energy results (PR #1275).

v1.4.0#

This release includes significant quality of life improvements for the CLI’s openfe gather command.

Added:

  • openfe gather now accepts any number of filepaths and/or directories containing results JSON files, instead of only accepting one results directory (PR #1212).

  • When running openfe gather --report=dg and result edges have fewer than 2 replicates, an error will be thrown up-front instead of failing downstream with a numpy.linalg.LinAlgError: SVD did not converge error (PR #1243).

  • openfe gather includes failed simulations in its output, with Error listed in place of a computed value, instead of simply omitting those results from the output table (PR #1227).

  • openfe gather --report=dg (the default) checks for connectivity of the results network and throws an error if the network is disconnected or has fewer than 3 edges (PR #1227).

  • openfe gather prints warnings for all results JSONs whose simulations have failed or are otherwise invalid (PR #1227 ).

  • openfe gather now throws an error up-front if no valid results are provided, instead of returning an empty table (PR #1245).

Changed:

  • Improved formatting of openfe gather output tables. Use --tsv to instead view the raw tsv formatted output (this was the default behavior as of v1.3.x) (PR #1246).

  • Improved responsiveness of several CLI commands (PR #1254).

v1.3.1#

Bugfix release - Improved error handling and code cleanup.

We are also dropping official support for MacOSX-x86_64. Any platform-specific bugs will be addressed when possible, but as a low priority.

Added:

  • openfe gather now detects failed simulations up-front and prints warnings to stdout (PR #1207).

Changed:

  • Temporarily disabled bootstrap uncertainties in forward/reverse analysis due to solver loop issues when dealing with too small a set of samples (PR #1174).

Removed:

  • Dropped official support for MacOSX-x86_64. Any platform-specific bugs will be addressed when possible, but as a low priority.

  • Unused trajectory handling code was removed from openfe.utils, please use openfe-analysis instead (PR #1182).

Fixed:

  • Fixed issue #1178 – The GPU system probe is now more robust to different ways the nvidia-smi command can fail (PR #1186)

  • Fixed bug where openmm protocols using default settings would re-load from JSON as a different gufe key due to unit name string representation discrepancies (PR #1210)

v1.3.0#

Added:

  • Added CLI support for generate_lomap_network. This option can be specified as a YAML-defined setting

  • Added --n-protocol-repeats CLI option to allow user-defined number of repeats per quickrun execution. This allows for parallelizing execution of repeats by setting --n-protocol-repeats=1 and calling quickrun on the same input file multiple times.

  • Added a new CLI command (charge-molecules) to bulk assign partial charges to molecules PR#1068

  • CLI setup will raise warnings for unsupported top-level YAML fields.

  • OpenMMEngineSettings now has a gpu_device_index attribute allowing users to pass through a list of ints to select the GPU devices to run their simulations on.

  • Add support for variable position/velocity trajectory writing.

  • openfe gather now supports replicates that have been submitted in parallel across separate directories.

Changed:

  • Networks planned using the CLI will now automatically use an extended protocol for transformations involving a net charge change PR#1053

  • The plan-rhfe-network and plan-rbfe-network CLI commands will now assign partial charges before planning the network if charges are not present, the charge assignment method can be controlled via the yaml settings file PR#1068

  • openfe.protocols.openmm_rfe._rfe_utils.compute has been moved to openfe.protocols.openmm_utils.omm_compute.

  • openfe gather now includes all edges with missing runs (instead of just the first failing edge) when raising a “missing runs” error.

  • openfe quickrun now creates the parent directory as-needed for user-defined output json paths (-o).

  • The MBAR bootstrap (1000 iterations) error is used to estimate protocol uncertainty instead of the statistical uncertainty (one standard deviation) and pymbar3 is no longer supported PR#1077

  • CLI network planners’ default names use prefixes rbfe_ or rhfe_ , instead of easy_rbfe or easy_rhfe, to simplify default transformation names.

Removed:

  • openfe is no longer tested against macos-12. macos support is, for now, limited to osx-arm64 (macos-14+).

Fixed:

  • openfe quickrun now creates the parent directory as-needed for user-defined output json paths (-o).

  • OpenMM CPU vacuum calculations now enforce the use of a single CPU to avoid large performance losses.

v1.2.0#

Added:

Fixed:

  • Improved responsiveness of CLI calls

  • Fixed bug where openfe gather –report raw was only including first replicates.

v1.1.0#

Added:

  • Extended system solvation tooling, including support for; non-cubic boxes, explicitly defining the number of waters added, the box vectors, and box size as supported by Modeller.addSolvent in OpenMM 8.0 and above.

Changed:

  • Improved documentation of the OpenMMSolvationSettings.

  • The PersesAtomMapper now uses openff.units inline with the rest of the package.

  • Structural analysis data is no longer written to structural_analysis.json but rather a 32bit numpy compressed file named structural_analysis.npz (PR #937).

  • Structural analysis array data is no longer directly returned in the RelativeHybridTopologyProtocol result dictionary. Instead it should be accessed from the serialized NPZ file structural_analysis.npz. The structural_analysis key now contains a path to the NPZ file, if the structural analysis did not fail (the structural_analysis_error key will instead be present on failure) (PR #937).

  • Add duecredit citations for pymbar when calling openfe.protocols.openmm_utils.multistate_analysis.

Fixed:

  • 2D RMSD plotting now allows for fewer than 5 states (PR #896).

  • 2D RMSD plotting no longer draws empty axes when the number of states - 1 is not divisible by 4 (PR #896).

  • The RelativeHybridTopologyProtocol result unit is now much smaller, due to the removal of structural analysis data (PR #937).

v1.0.1#

Added:

  • Debug script in devtools to test OpenMM installation.

  • Use rever to manage changelog.

Changed:

  • Updated docs to reference miniforge instead of mambaforge since they are the same now, see conda-forge/miniforge.

  • The LomapAtomMapper defaults have now changed to better reflect real-life usage. Key kwarg changes include; max3d=1.0 and shift=False.

Fixed:

  • Calling get_forward_and_reverse_energy_analysis in the RFE and AFE protocols now results a warning if any results are None due to MBAR convergence issues.

  • Checkpoint interval default value has been set to 250 ps instead of 1 ps. This better matches the previous default for openfe versions < 1.0rc (See issue #772 ).