Skip to content

Commit

Permalink
Remove dependence on parmed (#27)
Browse files Browse the repository at this point in the history
  • Loading branch information
@SimonBoothroyd
SimonBoothroyd authored Dec 12, 2024
1 parent 4023514 commit 2aa5c12
Show file tree
Hide file tree
Showing 83 changed files with 6,695 additions and 4,359 deletions.
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ The `femto` framework aims to offer not only a compact and comprehensive toolkit
using methods including `ATM` and `SepTop`, but also a full suite of utilities for running advanced simulations using
OpenMM, including support for HREMD and REST2.

_**Warning:** The ATM implementation was recently updated to make use of the new `ATMForce` shipped with OpenMM 8.1.
While every effort was made to ensure correctness, this was a major change that is still being tested and there may
be bugs. Please report any issues you encounter._
_**Warning:** From version 0.3.0 onwards, the codebase was re-written to completely remove the dependency on `parmed`,
allowing easy use of any force field parameters in OpenFF, Amber, and OpenMM FFXML formats. This re-write also introduced
a number of neccessary API changes. See the [migration guide for more details](https://psivant.github.io/femto/latest/migration/)._

_Further, the default protocols selected for the ATM and SepTop methods are still being tested and optimized, and may
not be optimal. It is recommended that you run a few test calculations to ensure that the results are reasonable._
Expand Down
7 changes: 4 additions & 3 deletions devtools/envs/base.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,17 @@ dependencies:
- networkx
- mdtraj

- ambertools
- openmm >=8.1.0
- openmmforcefields

- mdtop
- rdkit # ligand loading

# Optional packages
- seaborn-base
- tensorboardx

# Dev / Testing
- rdkit # creating mock test systems / topologies

- versioneer

- pre-commit
Expand Down
53 changes: 33 additions & 20 deletions docs/guide-atm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,32 +35,44 @@ config = femto.fe.atm.ATMConfig()
The setup procedure is responsible for combining the ligand(s) and receptor structures into a single complex, solvating
it, selecting any reference atoms if not provided, applying restraints, and finally creating the main OpenMM system.

It begins with the already prepared (correct binding pose, parameterized, etc.) structures of the ligand(s) and
receptor:
It begins with the already prepared (correct binding pose, protonation, etc.) structures of the ligand(s) and receptor:

```python
import pathlib

import femto.md.system
import femto.md.prepare

eralpha_dir = pathlib.Path("eralpha")

ligand_1, ligand_2 = femto.md.system.load_ligands(
ligand_1_coords=eralpha_dir / "forcefield/2d/vacuum.mol2",
ligand_1_params=eralpha_dir / "forcefield/2d/vacuum.parm7",
ligand_2_coords=eralpha_dir / "forcefield/2e/vacuum.mol2",
ligand_2_params=eralpha_dir / "forcefield/2e/vacuum.parm7",
ligand_1, ligand_2 = femto.md.prepare.load_ligands(
eralpha_dir / "forcefield/2d/vacuum.mol2",
eralpha_dir / "forcefield/2e/vacuum.mol2",
)
receptor = femto.md.system.load_receptor(
coord_path=eralpha_dir / "proteins/eralpha/protein.pdb",
param_path=None,
tleap_sources=config.setup.solvent.tleap_sources,
receptor = femto.md.prepare.load_receptor(
eralpha_dir / "proteins/eralpha/protein.pdb"
)
```

The ligands must **both** be in reasonable binding poses. The setup code will handle translating the ligands along the
displacement vector as required.

If the ligands / receptor has already been parameterized, the OpenMM XML or AMBER prmtop files can additionally be
specified:

```python
extra_parameters = [
eralpha_dir / "forcefield/2d/vacuum.parm7",
eralpha_dir / "forcefield/2e/vacuum.parm7",
]
```

If unspecified, an OpenFF force field will be used to parameterize the ligands. The
exact force field can be specified in the configuration.

???+ note
In previous versions of `femto`, the parameters were required. However in the current version, the parameters are
optional and will be automatically generated if not provided.

The vector along which the ligands will be translated must also be defined. `femto` provides an
[experimental utility][femto.fe.atm.select_displacement] to automatically compute this:

Expand All @@ -80,8 +92,8 @@ When running RBFE calculations, the ligand 'reference' atoms (i.e. those that wi
can be optionally specified:

```python
ligand_1_ref_query = ["@7", "@11", "@23"] # OR None
ligand_2_ref_query = ["@12", "@7", "@21"] # OR None
ligand_1_ref_query = ["idx. 7", "idx. 11", "idx. 23"] # OR None
ligand_2_ref_query = ["idx. 12", "idx. 7", "idx. 21"] # OR None
```

If not specified, these will be automatically selected. By default (`ligand_method='chen'`), the distance between each
Expand All @@ -95,21 +107,22 @@ Similarly, the receptor atoms that define the binding site can be optionally spe

```python
receptor_ref_query = [
":36,39,40,42,43,77,80,81,84,95,97,111,113,114,117,118,214,215,217,218 & @CA"
"resi 36+39+40+42+43+77+80+81+84+95+97+111+113+114+117+118+214+215+217+218 and name CA"
] # OR None
```

If not specified, these will be automatically selected. By default, these will include all alpha carbons within a
[defined cutoff][femto.fe.atm.ATMReferenceSelection.receptor_cutoff] from the ligand.

The full complex structure (ParmEd) and OpenMM system can then be created:
The full complex topology and OpenMM system can then be created:

```python
complex_structure, complex_system = femto.fe.atm.setup_system(
complex_topology, complex_system = femto.fe.atm.setup_system(
config.setup,
receptor,
ligand_1,
ligand_2,
[],
displacement,
receptor_ref_query,
ligand_1_ref_query,
Expand All @@ -129,7 +142,7 @@ If HMR or REST2 were enabled in the config, the system will also contain the app
The solvated system can be saved for easier inspection and checkpointing:

```python
complex_structure.save("system.pdb")
complex_topology.to_file("system.pdb")
```

### Equilibration
Expand All @@ -154,7 +167,7 @@ import femto.md.constants

coords = femto.fe.atm.equilibrate_states(
complex_system,
complex_structure,
complex_topology,
config.states,
config.equilibrate,
displacement,
Expand Down Expand Up @@ -183,7 +196,7 @@ config.sample.analysis_interval = 10

femto.fe.atm.run_hremd(
complex_system,
complex_structure,
complex_topology,
coords,
config.states,
config.sample,
Expand Down
22 changes: 11 additions & 11 deletions docs/guide-fe.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The easiest way to prepare the inputs for `femto`, especially when using the CLI
├─ forcefield/
│ ├─ <ligand 1>/
│ │ ├─ vacuum.mol2
│ │ └─ vacuum.parm7
│ │ └─ vacuum.xml
│ └─ ...
├─ proteins/
│ └─ <target>/
Expand All @@ -38,17 +38,17 @@ In particular, it should contain:
<td><b>forcefield</b></td>
<td>A subdirectory for each ligand of interest, which must include:
<ul>
<li><code>vacuum.[mol2,rst7]</code>: The ligand coordinate file. The ligand should already be in the correct docked pose, with the correct protonation state and tautomeric form.</li>
<li><code>vacuum.parm7</code>: The parameter file for the ligand.</li>
<li><code>vacuum.[mol2,sdf]</code>: The ligand file. The ligand should already be in the correct docked pose, with the correct protonation state and tautomeric form.</li>
<li><code>vacuum.[xml,parm7]</code> (optional): The parameter file for the ligand.</li>
</ul>
</td>
</tr>
<tr>
<td><b>proteins</b></td>
<td>A <em>single</em> subdirectory named after the protein target, which must include:
<ul>
<li><code>protein.[pdb,mol2,rst7]</code>: A file containing the target protein and any crystallographic waters in the correct pose.</li>
<li><code>protein.parm7</code> (optional): The parameter file for the protein.</li>
<li><code>protein.[pdb,mol2,sdf]</code>: A file containing the target protein and any crystallographic waters in the correct pose.</li>
<li><code>protein.[xml,parm7]</code> (optional): The parameter file for the protein.</li>
</ul>
</td>
</tr>
Expand Down Expand Up @@ -91,7 +91,7 @@ If running on a SLURM cluster, all the edges can be run using the `femto <method
=== "ATM"

```shell
femto atm --config "eralpha/config-atm.yaml" \
femto atm --config "eralpha/config-atm.yaml" \
\
submit-replicas --slurm-nodes 2 \
--slurm-tasks 8 \
Expand All @@ -109,7 +109,7 @@ If running on a SLURM cluster, all the edges can be run using the `femto <method
=== "SepTop"

```shell
femto septop --config "eralpha/config-septop.yaml" \
femto septop --config "eralpha/config-septop.yaml" \
\
submit-replicas --slurm-nodes 5 \
--slurm-tasks 19 \
Expand Down Expand Up @@ -151,7 +151,7 @@ instead run:
```shell
srun --mpi=pmix -n <N_LAMBDAS> \
\
femto atm --config "eralpha/config-atm.yaml" \
femto atm --config "eralpha/config-atm.yaml" \
\
run-workflow --ligand-1 "2d" \
--ligand-2 "2e" \
Expand All @@ -165,7 +165,7 @@ instead run:
```shell
srun --mpi=pmix -n <N_COMLEX_LAMBDAS> \
\
femto septop --config "eralpha/config-septop.yaml" \
femto septop --config "eralpha/config-septop.yaml" \
\
run-complex --ligand-1 "2d" \
--ligand-2 "2e" \
Expand All @@ -175,15 +175,15 @@ instead run:

srun --mpi=pmix -n <N_SOLUTION_LAMBDAS> \
\
femto septop --config "eralpha/config-septop.yaml" \
femto septop --config "eralpha/config-septop.yaml" \
\
run-solution --ligand-1 "2d" \
--ligand-2 "2e" \
--root-dir "eralpha" \
--output-dir "eralpha/outputs-septop/solution" \
--edges "eralpha/edges-septop.yaml"

femto septop --config "eralpha/config-septop.yaml" \
femto septop --config "eralpha/config-septop.yaml" \
\
analyze --complex-system eralpha/outputs-septop/complex/_setup/system.xml \
--complex-samples eralpha/outputs-septop/complex/_sample/samples.arrow \
Expand Down
Loading

0 comments on commit 2aa5c12

Please sign in to comment.