Package: rid-kit
Table of contentsAbout Rid-kitUse Rid-kit with Bohrium k8sQuick StartUse Rid-kit with Local k8sUse Rid-kit without k8s environmentMain procedure of RiDPreparing files in the input directoryConfigure simulationsConfigure machine resourcesDownload filesConfigure MCMC dimension reductionInstallation of environment on SlurmInstallation with DeepMD potential supportTroubleshootingAbout Rid-kitRid-kit is a package written in Python, designed to do enhanced sampling using reinforced dynamics. It aims to learn the free energy surface on the fly during MD run, and uses it as the bias potential during the next MD run. Its advantage is the ability to use a large number of CVs (100), thus can be used to simulate conformational changes of big molecules such as in the problem of protein folding.Rid-kit is based ondflow, one can decide whether to use a k8s environment to run a workflow. It is recommended to use k8s environment to run the workflow unless it is not doable anyway.For more information, check thedocumentation.Use Rid-kit with Bohrium k8sQuick startThe dflow team provide a community version of k8sdeepmodeling k8s, making the use of Rid-kit very convenient. To use the community version of k8s, one first need to register a Bohrium account inBohriumand learn a few concepts (job, jobgroup, project id) in the Bohrium website documents. Then the use of rid-kit is very easy.Set the environment variablesJust set the environment variables based on your personal Bohrium account information byexport DFLOW_HOST=https://workflows.deepmodeling.com
export DFLOW_K8S_API_SERVER=https://workflows.deepmodeling.com
export DFLOW_S3_REPO_KEY=oss-bohrium
export DFLOW_S3_STORAGE_CLIENT=dflow.plugins.bohrium.TiefblueClient
export BOHRIUM_USERNAME="<bohrium-email>"
export BOHRIUM_PASSWORD="<bohrium-password>"
export BOHRIUM_PROJECT_ID="<bohrium-project-id>"Notethat the "bohrium-project-id" is the specific ID related to your own Bohrium account, which can be created inBohrium Projectafter login into your own account. You can create multiple project IDs for your account.Install Rid-kitInstall the latest rid-kitpipinstallsetuptools_scm
pipinstall-Urid-kitRun an exampleChange to the rid-kit directorycdrid-kitRun a example of Ala-dipeptide on Bohrium using dihedral as CVs:In "machine_bohrium_k8s.json" file, set "email", "password" and "program_id" to your ownBohrium accountinformation.Notethat theprogram_idinformation in machine.json file should beinttype rather thanstringtype.Then run this command to submit the jobsridsubmit-i./tests/data/000-c./rid/template/rid_gmx_dih.json-m./rid/template/machine_bohrium_k8s.jsonAfter successful submission you can login into your Bohrium account atdeepmodeling k8sto monitor your job status, where the workflow is displayed using theArgoUI.If you want to run Rid-kit using your own customized CVs, an example is given (seeconfigure simulationsfor more details):Notethat the length ofangular_mask,weightsandkappaskeys in rid.json should all be equal to the length of your defined CV number.ridsubmit-i./tests/data/001-c./rid/template/rid_gmx_custom.json-m./rid/template/machine_bohrium_k8s.jsonYou can also run the example on a Slurm machine (But you need to configure a conda environment on the slurm, seeInstallation)ridsubmit-i./tests/data/000-c./rid/template/rid_gmx_dih.json-m./rid/template/machine_slurm_k8s.jsonYou can specify the workflow name by providing WORKFLOW_ID after "-d", for example:ridsubmit-i./tests/data/000-c./rid/template/rid_gmx_dih.json-m./rid/template/machine_bohrium_k8s.json-dala-dipeptide-1Note that the defined workflow-id should only contain lower case alphanumeric character, and specifal character "-".You can also specify other types of CVs such as distance or any customized CVs, for detailed explanation you can checkconfigure simulationsContinue from an old workflowUsingresubmitto continue from an old workflow# suppose the original workflow id is OLD_IDridresubmit-i./tests/data/000-c./rid/template/rid_gmx_dis.json-m./rid/template/machine_bohrium_k8s.jsonOLD_ID-dNEW_IDIf you want to resubmit from a particulariterationandstep:ridresubmit-iyour_dir-cpath_to_rid.json-mpath_to_machine.jsonOLD_ID-tITERATION-ID-pSTEP-KEY-dNEW_IDTheITERATION-ID(start from 1) is justnth iteration the workflow has been executed. TheSTEP-KEYin rid includes the following steps:prep-exploration,run-exploration,prep-select,run-select,prep-label,run-label,label-stats,collect-data,merge-data,train,model-devi.Download files from the workflowriddownloadWORKFLOW_ID-pSTEP-KEY-fFILE_NAME-aITERATION_START-eITERATION_END-oOUTPUT_DIRtypically we want the trajectories information from each exploration step, suppose we run a workflow for 20 iterations.riddownloadWORKFLOW_ID-prun-exploration-ftrajectory-a1-e20-omy_protein_outDetained explanation for other files in the Rid run can be found as follows:Download filesReduce the dimension of free energy modelAfter the Rid-kit Run, the workflow will generate several numbers of free energy models (.pb). The Rid-kit currently support MCMC to reduce the dimension of the free energy model, for example:ridredim-i./test/data/models-c./rid/template/rid_mcmc_cv_dih.json-m./rid/template/machine_bohrium_k8s_mcmc.jsonThen you will get the projected free energy surface for ala-dipeptideYou can also include .out file representing the CV output information inside the directory specified by-iparameter, this will plot the CV output upon the free energy surface.Use Rid-kit with Local k8sA tutorial on using Rid-kit with k8s environment configured by your own can be found as follows:TutorialUse Rid-kit without k8s environmentTo run the workflow without k8s environment, one can use theDebugmode ofDflow. In this mode however, one can not monitor the workflow in theArgoUI.Install the computation environmentIf you want to run Rid-kit on a local machine or server, withoutk8senviroment, you need to configure a conda environment on your machine, seeInstallation)Install the latest rid-kitpipinstallsetuptools_scm
pipinstall-Urid-kitRun an exampleIf one wants to run the workflow on theSlurmmachine locally, change to the rid-kit directory and type (change to your slurm configuration)DFLOW_DEBUG=1ridsubmit-i./tests/data/000-c./rid/template/rid_gmx_dih.json-m./rid/template/machine_slurm_local.json-dala-dipeptide-1Main procedure of RiDRiD will run in iterations. Every iteration contains tasks below:Biased MD;Restrained/Constrained MD;Training neural network.Biased MDJust like Metadynamics, RiD will sample based on a bias potential given by NN models. An uncertainty indicator will direct the process of adding bias potential.Restrained/Constrained MDThis procedure will calculate the mean force based on the sampling results of restrained MD or constrained MD, which can generate data set for training.Neural network trainingA fully connected NN will be trained via sampling data. This network will generate a map from selected CV to free energy.A more detailed description of RiD is published now, please see:[1]  Zhang, L., Wang, H., E, W.. Reinforced dynamics for enhanced sampling in large atomic and molecular systems[J]. The Journal of chemical physics, 2018, 148(12): 124113.[2]  Wang, D., Wang, Y., Chang, J., Zhang, L., & Wang, H. (2022). Efficient sampling of high-dimensional free energy landscapes using adaptive reinforced dynamics. Nature Computational Science, 2(1), 20-29.Preparing files in the input directoryRules for preparing files in the input directory can be found inPreparing filesConfigure simulationsconfigure simulationsConfigure machine resourcesconfigure machinesConfigure mcmcconfigure mcmc dimension reductionInstallation of environment on SlurmIf you sumit the RiD workflow to Bohrium, you do not need to install the enviroment yourself, rather Bohrium will pull the docker images to do the computation. But if you submit the workflow to Slurm machine, you will have to install the computation environment, details of the installation can be found inInstallationInstallation with DeepMD potential supportInstallation of the computation environment with DeepMD potential support on slurm machines can be found inInstallation of dpWorkflow SynopsisTroubleshootingInstallationMinikubeSubmit