Repository files navigation

asyncmd is a library to writeconcurrent code to run and analyze molecular dynamics simulations using pythonsasync/await synthax.

Molecular dynamics simulations are fun and we can learn a lot about the simulated system. Running many molecular dynamics simulations of the same system concurrently is tedious, error-prone and boring but we can learn even more about the simulated system and are more efficient in doing so.This library addresses the tedious, error-prone and boring part of setting up many similar simulations, but it leaves you with the fun part of understanding the simulated system.

RunN gromacs engines concurently from configurations randomly picked up along a trajectory (traj.trr) forn_steps integration steps each, drawing random Maxwell-Boltzmann velocities for each configuration on the way. Finally turn the python functionfunc (which acts onTrajectory objects) into an asyncronous and cached function by wrapping it and apply it on all generated trajectories concurrently:

importasyncioimportnumpyasnpimportasyncmdimportasyncmd.gromacsasasyncgmxin_traj=asyncmd.Trajectory(trajectory_files="traj.trr",structure_file="conf.gro")# get a random number generator and draw N random frames (with replacement)rng=np.default_rng()frame_idxs=rng.choice(len(in_traj),size=N)# use the RandomVelocitiesFrameExtractor to directly get the frames with MB-velsextractor=asyncmd.trajectory.convert.RandomVelocitiesFrameExtractor(T=303)mdps= [asyncgmx.MDP("config.mdp")for_inrange(N)]# MDConfig objects (like MDP) behave like dictionaries and are easy to modifyfori,mdpinenumerate(mdps):# here we just modify the output frequency for every engine separately# but you can set any mdp option like this# Note how the values are in the correct types? I.e. that they are ints?mdp["nstxout"]*= (i+1)mdp["nstvout"]*= (i+1)# create N gromacs enginesengines= [asyncgmx.GmxEngine(mdp=mdp,gro_file="conf.gro",top_file="topol.top",# optional (can be omited or None), however naturally without an index file# you can not reference custom groups in the .mdp-file or MDP objectndx_file="index.ndx",                              )formdpinmdps]# extract starting configurations with MB-vels and save them to current directorystart_confs=awaitasyncio.gather(*(extractor.extract_async(outfile=f"start_conf{i}.trr",traj_in=in_traj,idx=idx)fori,idxinenumerate(frame_idxs)))# prepare the MD (for gromacs this is essentially a `grompp` call)awaitasyncio.gather(*(e.prepare(starting_configuration=conf,workdir=".",deffnm=f"engine{i}")fori, (conf,e)inenumerate(zip(start_confs,engines))                       )                     )# and run the molecular dynamicsout_trajs=awaitasyncio.gather(*(e.run_steps(nsteps=n_steps)foreinengines))# wrapp `func` and apply it on all output trajectories concurrentlywrapped_func=asyncmd.trajectory.PyTrajectoryFunctionWrapper(function=func)cv_vals=awaitasyncio.gather(*(wrapped_func(traj)fortrajinout_trajs))

Note that running via theSLURM queueing system is as easy as replacing theGmxEngine with aSlurmGmxEngine and thePyTrajectoryFunctionWrapper with aSlurmTrajectoryFunctionWrapper (and suppling them both with sbatch script skeletons).

For an in-depth introduction see also theexamples folder in this repository which contains jupyter notebooks on various topics.

Please note that you need to havegit-lfs (an open source git extension) setup to get all input files needed to run the notebooks in theexamples folder. However, nogit-lfs is needed to get a working version of the library.

git clone https://github.com/bio-phys/asyncmd.gitcd asyncmdpip install.

The documentation can be build withsphinx, use e.g. the following to build it in html format:

cd asyncmd# Need to be at the top folder of the repository for the next line to worksphinx-build -b html docs/source docs/build/html

Usepip install .\[docs\] to install the requirements needed to build the documentation.

Tests usepytest. To run them just install asycmd with the test requirements

git clone https://github.com/bio-phys/asyncmd.gitcd asyncmdpip install .\[tests\]

And then run the tests (against the installed version) as

pytest

If you discover any issues or want to propose a new feature please feel free to open anissue or apull request!

For the developer install I recommend:

git clone https://github.com/bio-phys/asyncmd.gitcd asyncmdpip install -e .\[dev\]

This will in addition to the requirements to run the tests and to build the documentation installcoverage and itspytest-cov plugin such that you have an idea of the test coverage for your newly added code. To get a nice html coverage report you can run the tests as

pytest --cov=asyncmd --cov-report=html

This project was originally conceived and started by Hendrik Jung in 2021/2022. For more check thepyproject.toml file. When you contribute code dont forget to add your name there to claim the credit for your work!

asyncmd is under the terms of the GNU general public license version 3 or later, i.e. SPDX identifier "GPL-3.0-or-later".

_{This README.md is printed from 100% recycled electrons.}