Merge pull request #357 from OpenBioSim/release_2024.3.0

Release 2024.3.0

Author: lohedges

.github/workflows/Sandpit_exs.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Install dependency
         run: |
-          conda install -c conda-forge -c openbiosim/label/main biosimspace python=3.10 ambertools gromacs "sire=2024.1.0" "alchemlyb>=2.1" pytest openff-interchange pint=0.21 rdkit "jaxlib>0.3.7" tqdm
+          conda install -c conda-forge -c openbiosim/label/main biosimspace python=3.10 ambertools gromacs "sire=2024.2.0" "alchemlyb>=2.1" pytest openff-interchange pint=0.21 rdkit "jaxlib>0.3.7" tqdm
           python -m pip install git+https://github.com/Exscientia/MDRestraintsGenerator.git
           # For the testing of BSS.FreeEnergy.AlchemicalFreeEnergy.analysis
           python -m pip install https://github.com/alchemistry/alchemtest/archive/master.zip

README.rst

@@ -113,20 +113,20 @@ Conda environment.
 
    git clone https://github.com/openbiosim/biosimspace
    cd biosimspace/python
-   python setup.py install
+   pip install .
 
 If you plan to develop and want an editable install, use:
 
 .. code-block:: bash
 
-   python setup.py develop
+   pip install -e .
 
 If you want to skip the installation of BioSimSpace dependencies, e.g. if they
 are already installed, then you can use:
 
 .. code-block:: bash
 
-   BSS_SKIP_DEPENDENCIES=1 python setup.py develop
+   BSS_SKIP_DEPENDENCIES=1 pip install -e .
 
 Once finished, you can test the installation by running:
 
@@ -150,7 +150,7 @@ latest development code into that.
    conda activate openbiosim-dev
    git clone https://github.com/openbiosim/biosimspace
    cd biosimspace/python
-   BSS_SKIP_DEPENDENCIES=1 python setup.py develop
+   BSS_SKIP_DEPENDENCIES=1 pip install -e .
 
 (You may also want to install optional dependencies, such as ``ambertools`` and
 ``gromacs`` into your environment.)

doc/source/api/index_Align.rst

@@ -4,6 +4,12 @@ BioSimSpace.Align
 =================
 
 The *Align* package provides functionality for aligning and merging molecules.
+
+.. automodule:: BioSimSpace.Align
+
+.. toctree::
+   :maxdepth: 1
+
 Molecules are aligned using a Maximum Common Substructure (MCS) search, which
 is used to find mappings between atom indices in the two molecules.
 Functionality is provided for sorting the mappings according to a scoring
@@ -34,8 +40,3 @@ Some examples:
    # The resulting "merged-molecule" can be used in free energy perturbation
    # simulations.
    merged = BSS.Align.merge(mol0, mol1, mappings)
-
-.. automodule:: BioSimSpace.Align
-
-.. toctree::
-   :maxdepth: 1

doc/source/api/index_FreeEnergy.rst

@@ -6,6 +6,13 @@ BioSimSpace.FreeEnergy
 The *FreeEnergy* package contains tools to configure, run, and analyse
 *relative* free energy simulations.
 
+.. automodule:: BioSimSpace.FreeEnergy
+
+.. toctree::
+   :maxdepth: 1
+
+As well as the :class:`protocol <BioSimSpace.Protocol.FreeEnergy>` used for production
+
 Free-energy perturbation simulations require a
 :class:`System <BioSimSpace._SireWrappers.System>` containing a *merged*
 molecule that can be *perturbed* between two molecular end states by use
@@ -28,6 +35,9 @@ perturbable molecule created by merging two ligands, ``ligA`` and ``ligB``,
 perturbable molecule. We assume that each molecule/system has been
 appropriately minimised and equlibrated.
 
+Relative binding free-energy (RBFE)
+-----------------------------------
+
 To setup, run, and analyse a binding free-energy calculation:
 
 .. code-block:: python
@@ -130,16 +140,80 @@ the path to a working directory to :class:`FreeEnergy.Relative.analyse <BioSimSp
 
    pmf_vacuum, overlap_vacuum = BSS.FreeEnergy.Relative.analyse("ligA_ligB/vacuum")
 
-.. automodule:: BioSimSpace.FreeEnergy
-
-.. toctree::
-   :maxdepth: 1
-
-As well as the :class:`protocol <BioSimSpace.Protocol.FreeEnergy>` used for production
 simulations, it is also possible to use
 :class:`FreeEnergy.Relative <BioSimSpace.FreeEnergy.Relative>` to setup and run simulations
 for minimising or equilibrating structures for each lambda window. See the
 :class:`FreeEnergyMinimisation <BioSimSpace.Protocol.FreeEnergyMinimisation>` and
 :class:`FreeEnergyEquilibration <BioSimSpace.Protocol.FreeEnergyEquilibration>`
 protocols for details. At present, these protocols are only supported when not
 using :class:`SOMD <BioSimSpace.Process.Somd>` as the simulation engine.
+
+Alchemical Transfer Method (ATM)
+--------------------------------
+
+This package contains tools to configure, run, and analyse *relative* free
+energy simulations using the *alchemical transfer method*  developed by the
+`Gallicchio lab <https://www.compmolbiophysbc.org/atom-openmm>`.
+
+Only available in the *OpenMM* engine, the *alchemical transfer method*
+replaces the conventional notion of perturbing between two end states with
+a single system containing both the free and bound ligand. The relative free
+energy of binding is then associated with the swapping of the bound and free
+ligands.
+
+The *alchemical transfer method* has a few advantages over the conventional
+approach, mainly arising from its relative simplicity and flexibility. The
+method is particularly well-suited to the study of difficult ligand
+transformations, such as scaffold-hopping and charge change perturbations.
+The presence of both ligands in the same system also replaces the conventional
+idea of _legs_, combining free, bound, forward and reverse legs into a
+single simulation.
+
+In order to perform a relative free energy calculation using the
+*alchemical transfer method*, the user requires a protein and two ligands, as
+well as knowledge of any common core shared between the two ligands.
+ATM-compatible systems can be created from these elements using the
+:class:`FreeEnergy.ATM <BioSimSpace.FreeEnergy.ATMSetup>` class.
+
+.. code-block:: python
+
+   from BioSimSpace.FreeEnergy import ATMSetup
+
+   ...
+
+   # Create an ATM setup object. 'protein', 'ligand1' and 'ligand2' must be
+   # BioSimSpace Molecule objects.
+   # 'ligand1' is bound in the lambda=0 state, 'ligand2' is bound in the lambda=1 state.
+   atm_setup = ATMSetup(protein=protein, ligand1=ligand1, ligand2=ligand2)
+
+   # Now create the BioSimSpace system. Here is where knowledge of the common core is required.
+   # ligand1_rigid_core and ligand2_rigid_core are lists of integers, each of length three,
+   # which define the indices of the common core atoms in the ligands.
+   # Displacement is the desired distance between the centre of masses of the two ligands.
+   system, data = atm_setup.prepare(
+         ligand1_rigid_core=[1, 2, 3],
+         ligand2_rigid_core=[1, 2, 3],
+         displacement=22.0
+   )
+
+   # The prepare function returns two objects: a prepared BioSimSpace system that is ready
+   # for ATM simulation, and a data dictionary containing information relevant to ATM calculations.
+   # This dictionary does not need to be kept, as the information is also encoded in the system
+   # object, but it may be useful for debugging.
+
+
+Preparing the system for production runs is slightly more complex than in
+the conventional approach, as the system will need to be annealed to an
+intermediate lambda value, and then equilibrated at that value. The
+:ref:`protocol <ref_protocols>` sub-module contains functionality for
+equilibrating and annealing systems for ATM simulations.
+
+Once the production simulations have been completed, the user can analyse
+the data using the :func:`analyse <BioSimSpace.FreeEnergy.ATM.analyse>` function.
+
+.. code-block:: python
+
+   from BioSimSpace.FreeEnergy import ATM
+
+   # Analyse the simulation data to get the free energy difference and associated error.
+   ddg, error = ATM.analyse("path/to/working/directory")

doc/source/changelog.rst

@@ -9,14 +9,30 @@ company supporting open-source development of fostering academic/industrial coll
 within the biomolecular simulation community. Our software is hosted via the `OpenBioSim`
 `GitHub <https://github.com/OpenBioSim/biosimspace>`__ organisation.
 
+`2024.3.0 <https://github.com/openbiosim/biosimspace/compare/2024.2.0...2024.3.0>`_ - Oct 24 2024
+-------------------------------------------------------------------------------------------------
+
+* Fixed link in protein free-energy perturbation tutorial (`#310 <https://github.com/OpenBioSim/biosimspace/pull/310>`__).
+* Fixed alignment of monatomic molecules (`#313 <https://github.com/OpenBioSim/biosimspace/pull/313>`__ and (`#333 <https://github.com/OpenBioSim/biosimspace/pull/333>`__).
+* Expose missing ``extra_args`` keyword argument for the :class:`Process.Somd <BioSimSpace.Process.Somd>` class (`#319 <https://github.com/OpenBioSim/biosimspace/pull/319>`__).
+* Add support for the Alchemical Transfer Method (ATM) (`@mb2055 <https://github.com/mb2055>`_) (`#327 <https://github.com/OpenBioSim/biosimspace/pull/327>`__).
+* Fixed :meth:`system.updateMolecules <BioSimSpace._SireWrappers.System.updateMolecules>` method when updating multiple molecules at once (`#336 <https://github.com/OpenBioSim/biosimspace/pull/336>`__).
+* Added a new :meth:`system.removeBox <BioSimSpace._SireWrappers.System.removeBox>` method to remove the box from a system (`#338 <https://github.com/OpenBioSim/biosimspace/pull/338>`__).
+* Fixed bug when using position restraints with OpenMM for perturbable systems (`#341 <https://github.com/OpenBioSim/biosimspace/pull/341>`__).
+* Include both end states in the GROMACS restraint file when using position restraints with perturbable systems (`#342 <https://github.com/OpenBioSim/biosimspace/pull/342>`__).
+* Set end state connectivity properties when a perturbation involves a change in connectivity (`#345 <https://github.com/OpenBioSim/biosimspace/pull/345>`__).
+* Use direct Sire-to-RDKit conversion when parameterising with OpenFF to avoid issues with intermediate file formats (`#349 <https://github.com/OpenBioSim/biosimspace/pull/349>`__).
+* Preserve SMILES based molecular properties during parameterisation (`#352 <https://github.com/OpenBioSim/biosimspace/pull/352>`__).
+* Rotate perturbable and non-perturbable molecules independently when rotating box vectors (`#355 <https://github.com/OpenBioSim/biosimspace/pull/355>`__).
+
 `2024.2.0 <https://github.com/openbiosim/biosimspace/compare/2024.1.0...2024.2.0>`_ - Jul 09 2024
 -------------------------------------------------------------------------------------------------
 
 * Fixed incorect use of ``self`` in :func:`Trajectory.getFrame <BioSimSpace.Trajectory.getFrame>` function (`#281 <https://github.com/OpenBioSim/biosimspace/pull/281>`__).
 * Use SDF as an intermediate for ``antechamber`` if the original molecule was loaded from that format (`#287 <https://github.com/OpenBioSim/biosimspace/pull/287>`__).
 * Detect dummy atoms by checking ``element`` *and* ``ambertype`` properties when creating ``SOMD`` pert files (`#289 <https://github.com/OpenBioSim/biosimspace/pull/289>`__).
 * Add missing ``match_water`` kwarg to ``prepareFEP`` node (`#292 <https://github.com/OpenBioSim/biosimspace/pull/292>`__).
-* Add protein free-energy perturbation functionality (`@akalpokas <https://github.com/akalpokas (`#294 <https://github.com/OpenBioSim/biosimspace/pull/294>`__).
+* Add protein free-energy perturbation functionality (`@akalpokas <https://github.com/akalpokas`_) (`#294 <https://github.com/OpenBioSim/biosimspace/pull/294>`__).
 * Ensure that the LJ sigma parameter for perturbed atoms is non-zero (`#295 <https://github.com/OpenBioSim/biosimspace/pull/295>`__).
 * Fixed return type docstrings for functions in the :mod:`BioSimSpace.Parameters` module (`#298 <https://github.com/OpenBioSim/biosimspace/pull/298>`__).
 * Don't use ``sire.legacy.Base.wrap`` with the ``file_format`` property to avoid (incorrect) auto string to unit conversion of ``mol2`` to moles squared (`#300 <https://github.com/OpenBioSim/biosimspace/pull/300>`__).
@@ -35,7 +51,6 @@ within the biomolecular simulation community. Our software is hosted via the `Op
 * Add a ``getRestraintType`` method to the base protocol that returns ``None`` (`#276 <https://github.com/OpenBioSim/biosimspace/pull/276>`__).
 * Add missing ``themostat_time_constant`` kwarg to the :class:`Metadynamics <BioSimSpace.Protocol.Metdynamics>` protocol (`#276 <https://github.com/OpenBioSim/biosimspace/pull/276>`__).
 
-
 `2023.5.1 <https://github.com/openbiosim/biosimspace/compare/2023.5.0...2023.5.1>`_ - Mar 20 2024
 -------------------------------------------------------------------------------------------------
 
@@ -73,7 +88,6 @@ within the biomolecular simulation community. Our software is hosted via the `Op
 * Ensure all searches for disulphide bonds are convert to a ``SelectorBond`` object (`#224 <https://github.com/OpenBioSim/biosimspace/pull/224>`__).
 * Fix injection of custom commands into ``LEaP`` script (`#226 <https://github.com/OpenBioSim/biosimspace/pull/226>`__).
 
-
 `2023.4.0 <https://github.com/openbiosim/biosimspace/compare/2023.3.1...2023.4.0>`_ - Oct 13 2023
 -------------------------------------------------------------------------------------------------
 

doc/source/index.rst

@@ -63,15 +63,15 @@ Tutorials
 =========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    tutorials/index
 
 Detailed Guides
 ===============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    guides/index
 
@@ -93,7 +93,7 @@ Support
 Contributing
 ============
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    contributing/index
    contributors

doc/source/install.rst

@@ -219,20 +219,20 @@ Conda environment.
 
    git clone https://github.com/openbiosim/biosimspace
    cd biosimspace/python
-   python setup.py install
+   pip install .
 
 If you plan to develop and want an editable install, use:
 
 .. code-block:: bash
 
-   python setup.py develop
+   pip install -e .
 
 If you want to skip the installation of BioSimSpace dependencies, e.g. if they
 are already installed, then you can use:
 
 .. code-block:: bash
 
-   BSS_SKIP_DEPENDENCIES=1 python setup.py develop
+   BSS_SKIP_DEPENDENCIES=1 pip install -e .
 
 Once finished, you can test the installation by running:
 
@@ -256,7 +256,7 @@ latest development code into that.
    conda activate openbiosim-dev
    git clone https://github.com/openbiosim/biosimspace
    cd biosimspace/python
-   BSS_SKIP_DEPENDENCIES=1 python setup.py develop
+   BSS_SKIP_DEPENDENCIES=1 pip install -e .
 
 (You may also want to install optional dependencies, such as ``ambertools`` and
 ``gromacs`` into your environment.)