Systematically generate structures of two molecules based on discretisation of translational and rotational space.
Project description
molecularRotationalGrids
The python package molgri
has three main purposes: 1) generation of rotation grids, 2) analysis of
said grids and 3) generation of pseudotrajectories (PTs). PTs are files in .xtc or similar format
consisting of several timesteps in
which the interaction space of two molecules is systematically explored. We provide user-friendly,
one-line scripts for rotation grid generation and analysis as well as pseudotrajectory generation and
intutive visual inspection.
In this short tutorial, we also give instructions how to use PTS with external tools like
VMD and GROMACS for further analysis.
In the figures below, we show examples of rotation grids and pseudotrajectories as well as some analysis plots. All plots and animations are created
directly with the molgri
package, except the PT plot in the middle where the output of molgri
is drawn
using VMD.
Installation
This is a python library that can be easily installed using:
pip install molgri
Reproducing papers
To use the functionality of our 2022 paper
Zupan, Hana, Frederick Heinz, and Bettina G. Keller. "Grid-based state space exploration for molecular binding." Canadian Journal of Chemistry (2022)
please install an old version of molgri: pip install molgri==1.3.4
To use the functionality of our current work
[to be published]
please install the last available version of molgri. After installation and assuming you have GROMACS 2022 available on your system as command "gmx22" as well as VMD as command "vmd", you can replicate our computational experiments with:
snakemake --cores 10
(note that this process requires significant memory and time and may need to be run on a computer cluster)
If you want to modify the experiments or only run parts of the programs we have some suggestions below.
Using molgri
We offer three ways of using molgri, sorted here from easiest to use to most adaptable:
- running scripts
- running snakemake pipelines
- importing the package
Read on for details on each of the three user interfaces.
Running scrips
For quick and easy generation of spherical grids and/on pseudo-trajectories with systematically positioned pairs of molecules use the provided scripts molgri-grid
and molgri-pt
. The scripts are installed alongside the package (see Installation above).
To explore the capabilities of the package, the user is encouraged to run the following example commands (the commands should all be executed in the same directory, we recommend an initially empty directory).
molgri-io --examples
molgri-grid -N 250 -algo ico
molgri-pt -m1 H2O -m2 NH3 -o 15 -b 10 -t "range(1, 5, 2)"
The first-line command molgri-io
creates the 📂 input/ and
📂 output/ folder structure. This command should be run in each new
directory before running other commands. The optional
flag --examples
provides some sample input files that are used by the rest of the commands.
The second command molgri-grid
is used to generate rotation grids. It is
necessary to specify the number of grid points -N
and the algorithm
-algo
(select from: systemE, randomE, randomQ, cube4D, cube3D, ico; we
recommend ico). Other flags describe optional figures and animations to save. All
generated files can be found in output/grid_files/
, statistics in the
output/statistics_files/
and visualisations in output/figures/
and output/animations/
.
Note: you do not need to use this function if you are only interested in pseudotrajectories. All required
grids will be automatically generated when running the molgri-pt
command.
The third command molgri-pt
creates a pseudotrajectory. By default, this is a single
trajectory-like file containing
all frames. Alternatively, with an optional command --as_dir
a directory of single-frame files is
created. In addition, the first frame of the pseudo-trajectory is also written out as a structure file.
Default trajectory format is .xtc and default structure format .gro, user can change this behaviour with
optional commands --extension_trajectory
and --extension_structure
.
This scripts needs
two file inputs that should be provided in input/, each containing a single molecule. Standard formats
like .gro, .xyz, .pdb and others are accepted. In this example, due to the flag
-m1 H2O
the program will look for a file input/H2O with any standard extension
and use it as the fixed molecule in the pseudotrajectory. The flag -m2
gives the name of the file with the other molecule, which will be mobile
in the simulation. Finally, the user needs to specify the two rotational grids
in form -o algorithm_N
(for rotations around the origin) and
-b algorithm_N
, see algorithm names above. If you want to use the default algorithms (currently
icosahedron algorithm),
specify only the number of points, e.g. -o 15 -b 10
. Finally, the translational grid after the
flag -t
should be supplied in one of the
following formats: a list of distances (in nm), linspace(start, stop, num)
or range(start, stop, step). The argument should be surrounded by quotation
marks. Some acceptable translation grid arguments would be:
-t "(1, 3, 5)"
-> use distances 1nm, 3nm and 5nm
-t "linspace(1, 3, 5)"
-> use 5 equally spaced points
between 1nm and 3nm
-t "range(1, 3, 0.5)"
-> use distances between 1nm and 3nm
in 0.5nm increments
All flags starting with --
are optional and can be omitted for faster
calculations. Remember that you can always add the flag --help
to get
further instructions.
Using outputs
The pseudotrajectory .xtc and .gro files can be used as regularly generated trajectory files. We show how they can be displayed with VMD or used for GROMACS calculations, but the user is free to use them as inputs to any other tool.
Displaying pseudotrajectory
To display the example pseudotrajectory we created in the previous section with VMD, change to
directory output/pt_files
and run
vmd H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.gro H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.xtc
or on a windows computer
start vmd H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.gro H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.xtc
Then, to fully display a pseudotrajectory, it is often helpful to change the display style and to display several or all frames at once. We suggest using the following commands within the VMD command line:
mol modstyle 0 0 VDW
mol drawframes 0 0 0:1:300
The first one displays the molecules as spheres with van der Waals radii and the second draws frames of the pseudotrajectory in a form <start>:<step>:<stop>. A useful trick is to use the number of rotations as <step> (in this case that would be 15) - this displays one structure per mass point without considering internal rotations. This number is also written in the name of the .gro file. If you want to display all frames, you can use any large number for <num_frames>, it does not need to correspond exactly to the number of frames.
Calculating energy along a pseudotrajectory
Often, a pseudotrajectory is used to explore where regions of high and low energies lie when molecules
approach each other. Since a range of timesteps sampling important rotations and translations
is already provided in a PT, there is no need to run a real
simulation. Therefore, the flag -rerun
is always used while dealing with PTs in GROMACS. This
setting saves time that would else be used for running an integrator and propagating positions.
To use GROMACS with PTs, the user must also provide a topology file which includes both molecules used in a pseudotrajectory. We will assume that this file is named topol.top. Lastly, we need a GROMACS run file that we will name mdrun.mdp. This file records GROMACS parameters and can be used as in normal simulations, but note that some parameters (e.g. integrator, dt) are meaningless for a pseudotrajectory without actual dynamics. Then, the energy along a pseudotrajectory can be calculated as follows, using the molgri-generated <structure_file> (eg. H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.gro) and <trajectory_file> (eg. H2O_NH3_o_cube3D_15_b_ico_10_t_3203903466.xtc):
gmx22 grompp -f mdrun.mdp -c <structure_file> -p topol.top -o result.tpr
gmx22 mdrun -s result.tpr -rerun <trajectory_file>
gmx22 energy -f ener.edr -o full_energy.xvg
Using snakemake pipelines
The pre-requirements for fully functional pipelines are:
- python with correct packages (pip install -r requirements)
- GROMACS (the command gmx22 should be functional in the terminal where the pipeline is run)
- VMD (the command vmd should be functional in the terminal where the pipeline is run)
For reproducing the entire set of computational experiments om our publications see the section Reproducing papers.
To run your own computational experiment, prepare a configuration file and then run the appropriate one of pipeline files "run_sqra", "run_msm" or "run_grid", for example: snakemake --snakefile workflow/run_sqra --cores 4 --configfile input/default_configuration_file.yaml
Creating records
Records are useful to have an overview of experiments that have been set-up so far and their parameters. To obtain (or update) summary files run snakemake --snakefile workflow/run_records --cores 4 This creates an overview .csv file in each subfolder of experiments/
importing the package
Users who would like to build custom grids, pseudotrajectories or sets of rotations and enjoy more
flexibility with visualisation tools can import molgri
as a python package (following installation described above) and work with all provided modules. Documentation
of all modules is available online
via ReadTheDocs.
Citation
If this repository has helped you, please cite the following publication:
Zupan, Hana, Frederick Heinz, and Bettina G. Keller. "Grid-based state space exploration for molecular binding." Canadian Journal of Chemistry (2022)
arXiv preprint available at: https://arxiv.org/abs/2211.00566
Dependencies
This section is probably only useful for developers.
Dependencies of molgri are managed with poetry. Usage:
-
install pipx:
python3 -m pip install --user pipx python3 -m pipx ensurepath
And then open a new terminal. If there are problems, pipx reinstall-all is also useful.
-
install poetry in a separate environment with pipx:
pipx install poetry
-
now you add/remove dependencies via poetry:
poetry add <dependency>
poetry remove <dependency>
Or if dependency is only needed for a specific part of the process you can add --group <group_name> to both commands. Currently, there are groups ’notebooks’, ’test’ and ’workflows’. 3) To make sure no other dependencies are present in the environment, occasionally run
poetry install --sync --with notebooks,workflows,test
and to update to latest compatible versions occasionally run
poetry update package
- Now you can:
- run a specific module, e.g. poetry run python -m molgri.plotting.other_plots
- run tests, e.g. poetry run pytest
- run workflows, e.g. poetry run snakemake --snakefile workflow/run_grid --configfile input/default_configuration_file.yaml --cores 4
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file molgri-2.0.0.tar.gz
.
File metadata
- Download URL: molgri-2.0.0.tar.gz
- Upload date:
- Size: 407.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.4 CPython/3.11.8 Linux/6.1.0-26-amd64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | b4edfaa66c59c2e306ea29b8eb0e6c5ab3c67f81a2a55cc8ad0c515d2362ab15 |
|
MD5 | d9032088927719cd8c548eb9dbd815ed |
|
BLAKE2b-256 | 87325b494e322ef3134ad6038ced4dc86d822cf2755a20fe1dffac137cdbecb8 |
File details
Details for the file molgri-2.0.0-py3-none-any.whl
.
File metadata
- Download URL: molgri-2.0.0-py3-none-any.whl
- Upload date:
- Size: 413.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.4 CPython/3.11.8 Linux/6.1.0-26-amd64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2b52e24c6b6d5e7bf23e84a790e0e28146d3b90a769146fbb9277817c158aba5 |
|
MD5 | 579bba9592487f81e5654327cd2b53a8 |
|
BLAKE2b-256 | 3dcb368b65f0cafca5c53f59c1a281a33817693346290edd5fe30ac41951a331 |