# Table of contents
- [About Rid-kit](#about-rid-kit)
- [Use Rid-kit with Bohrium k8s](#use-rid-kit-with-bohrium-k8s)
- [Quick Start](#quick-start)
- [Use Rid-kit with Local k8s](#use-rid-kit-with-local-k8s)
- [Use Rid-kit without k8s environment](#use-rid-kit-without-k8s-environment)
- [Main procedure of RiD](#main-procedure-of-rid)
- [Preparing files in the input directory](#preparing-files-in-the-input-directory)
- [Configure simulations](#configure-simulations)
- [Configure machine resources](#configure-machine-resources)
- [Download files](#download-files-from-the-workflow)
- [Configure MCMC dimension reduction](#configure-mcmc)
- [Installation of environment on Slurm](#installation-of-environment-on-slurm)
- [Installation with DeepMD potential support](#installation-with-deepmd-potential-support)
- [Troubleshooting](#troubleshooting)
# About Rid-kit
Rid-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 on [dflow](https://github.com/deepmodeling/dflow), 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 the [documentation](https://rid-kit-dflow.readthedocs.io/en/latest/).
# Use Rid-kit with Bohrium k8s
## Quick start
The dflow team provide a community version of k8s [deepmodeling k8s](https://workflows.deepmodeling.com/), making the use of Rid-kit very convenient. To use the community version of k8s, one first need to register a Bohrium account in [Bohrium](https://bohrium.dp.tech/login) and 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 variables
Just set the environment variables based on your personal Bohrium account information by
```
export 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>"
```
**Note** that the "bohrium-project-id" is the specific ID related to your own Bohrium account, which can be created in [Bohrium Project](https://bohrium.dp.tech/projects) after login into your own account. You can create multiple project IDs for your account.
### Install Rid-kit
Install the latest rid-kit
```bash
pip install setuptools_scm
pip install -U rid-kit
```
### Run an example
Change to the rid-kit directory
```bash
cd rid-kit
```
Run 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 own **Bohrium account** information.
**Note** that the **program_id** information in machine.json file should be **int** type rather than **string** type.
Then run this command to submit the jobs
```bash
rid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_bohrium_k8s.json
```
After successful submission you can login into your Bohrium account at [deepmodeling k8s](https://workflows.deepmodeling.com/) to monitor your job status, where the workflow is displayed using the `Argo` UI.
If you want to run Rid-kit using your own customized CVs, an example is given (see [configure simulations](docs/source/rid_configuration.md) for more details):
**Note** that the length of **angular_mask**, **weights** and **kappas** keys in rid.json should all be equal to the length of your defined CV number.
```bash
rid submit -i ./tests/data/001 -c ./rid/template/rid_gmx_custom.json -m ./rid/template/machine_bohrium_k8s.json
```
You can also run the example on a Slurm machine (But you need to configure a conda environment on the slurm, see [Installation](docs/source/install.md))
```bash
rid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_slurm_k8s.json
```
You can specify the workflow name by providing WORKFLOW_ID after "-d", for example:
```bash
rid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_bohrium_k8s.json -d ala-dipeptide-1
```
**Note 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 check
- [configure simulations](docs/source/rid_configuration.md)
### Continue from an old workflow
Using `resubmit` to continue from an old workflow
```bash
# suppose the original workflow id is OLD_ID
rid resubmit -i ./tests/data/000 -c ./rid/template/rid_gmx_dis.json -m ./rid/template/machine_bohrium_k8s.json OLD_ID -d NEW_ID
```
If you want to resubmit from a particular `iteration` and `step`:
```bash
rid resubmit -i your_dir -c path_to_rid.json -m path_to_machine.json OLD_ID -t ITERATION-ID -p STEP-KEY -d NEW_ID
```
The `ITERATION-ID`(start from 1) is just `n`th iteration the workflow has been executed. The `STEP-KEY` in 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 workflow
```bash
rid download WORKFLOW_ID -p STEP-KEY -f FILE_NAME -a ITERATION_START -e ITERATION_END -o OUTPUT_DIR
```
typically we want the trajectories information from each exploration step, suppose we run a workflow for 20 iterations.
```bash
rid download WORKFLOW_ID -p run-exploration -f trajectory -a 1 -e 20 -o my_protein_out
```
Detained explanation for other files in the Rid run can be found as follows:
- [Download files](docs/source/rid_download.md)
### Reduce the dimension of free energy model
After 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:
```bash
rid redim -i ./test/data/models -c ./rid/template/rid_mcmc_cv_dih.json -m ./rid/template/machine_bohrium_k8s_mcmc.json
```
Then you will get the projected free energy surface for ala-dipeptide
 | 
---|---
You can also include .out file representing the CV output information inside the directory specified by `-i` parameter, this will plot the CV output upon the free energy surface.
# Use Rid-kit with Local k8s
A tutorial on using Rid-kit with k8s environment configured by your own can be found as follows:
- [Tutorial](docs/source/tutorial.md)
# Use Rid-kit without k8s environment
To run the workflow without k8s environment, one can use the `Debug` mode of `Dflow`. In this mode however, one can not monitor the workflow in the `Argo` UI.
## Install the computation environment
If you want to run Rid-kit on a local machine or server, without `k8s` enviroment, you need to configure a conda environment on your machine, see [Installation](docs/source/install.md))
## Install the latest rid-kit
```bash
pip install setuptools_scm
pip install -U rid-kit
```
## Run an example
If one wants to run the workflow on the `Slurm` machine locally, change to the rid-kit directory and type (change to your slurm configuration)
```bash
DFLOW_DEBUG=1 rid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_slurm_local.json -d ala-dipeptide-1
```
# Main procedure of RiD
RiD will run in iterations. Every iteration contains tasks below:
1. Biased MD;
2. Restrained/Constrained MD;
3. Training neural network.
## Biased MD
Just 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 MD
This 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 training
A 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 directory
Rules for preparing files in the input directory can be found in
- [Preparing files](docs/source/prepare_files.md)
# Configure simulations
- [configure simulations](docs/source/rid_configuration.md)
# Configure machine resources
- [configure machines](docs/source/rid_machine.md)
# Configure mcmc
- [configure mcmc dimension reduction](docs/source/mcmc_configuration.md)
# Installation of environment on Slurm
If 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 in
- [Installation](docs/source/install.md)
# Installation with DeepMD potential support
Installation of the computation environment with DeepMD potential support on slurm machines can be found in
- [Installation of dp](docs/source/install_dp.md)
# Workflow Synopsis
- 
# Troubleshooting
- [Installation](docs/source/troubleshooting/installation.md)
- [Minikube](docs/source/troubleshooting/minikube.md)
- [Submit](docs/source/troubleshooting/submit.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/deepmodeling/rid-kit",
"name": "rid-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "enhanced sampling reinforced dynamics RiD",
"author": "Yanze Wang, Jiahao Fan",
"author_email": "yanze039@mit.edu,jiahaofan@pku.edu.cn",
"download_url": "https://files.pythonhosted.org/packages/1f/0d/ec55b87562705c4cb8c32359a505f49393057beb495f3a63666fca7c083b/rid-kit-0.6.4.tar.gz",
"platform": null,
"description": "# Table of contents\n- [About Rid-kit](#about-rid-kit)\n- [Use Rid-kit with Bohrium k8s](#use-rid-kit-with-bohrium-k8s)\n - [Quick Start](#quick-start)\n- [Use Rid-kit with Local k8s](#use-rid-kit-with-local-k8s)\n- [Use Rid-kit without k8s environment](#use-rid-kit-without-k8s-environment)\n- [Main procedure of RiD](#main-procedure-of-rid)\n- [Preparing files in the input directory](#preparing-files-in-the-input-directory)\n- [Configure simulations](#configure-simulations)\n- [Configure machine resources](#configure-machine-resources)\n- [Download files](#download-files-from-the-workflow)\n- [Configure MCMC dimension reduction](#configure-mcmc)\n- [Installation of environment on Slurm](#installation-of-environment-on-slurm)\n- [Installation with DeepMD potential support](#installation-with-deepmd-potential-support)\n- [Troubleshooting](#troubleshooting)\n\n# About Rid-kit\nRid-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.\n\nRid-kit is based on [dflow](https://github.com/deepmodeling/dflow), 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. \n\nFor more information, check the [documentation](https://rid-kit-dflow.readthedocs.io/en/latest/).\n\n# Use Rid-kit with Bohrium k8s\n## Quick start\nThe dflow team provide a community version of k8s [deepmodeling k8s](https://workflows.deepmodeling.com/), making the use of Rid-kit very convenient. To use the community version of k8s, one first need to register a Bohrium account in [Bohrium](https://bohrium.dp.tech/login) and learn a few concepts (job, jobgroup, project id) in the Bohrium website documents. Then the use of rid-kit is very easy.\n\n### Set the environment variables\nJust set the environment variables based on your personal Bohrium account information by\n\n```\nexport DFLOW_HOST=https://workflows.deepmodeling.com\nexport DFLOW_K8S_API_SERVER=https://workflows.deepmodeling.com\nexport DFLOW_S3_REPO_KEY=oss-bohrium\nexport DFLOW_S3_STORAGE_CLIENT=dflow.plugins.bohrium.TiefblueClient\nexport BOHRIUM_USERNAME=\"<bohrium-email>\"\nexport BOHRIUM_PASSWORD=\"<bohrium-password>\"\nexport BOHRIUM_PROJECT_ID=\"<bohrium-project-id>\"\n```\n\n**Note** that the \"bohrium-project-id\" is the specific ID related to your own Bohrium account, which can be created in [Bohrium Project](https://bohrium.dp.tech/projects) after login into your own account. You can create multiple project IDs for your account.\n\n### Install Rid-kit\nInstall the latest rid-kit\n\n```bash\npip install setuptools_scm\npip install -U rid-kit\n```\n\n### Run an example\nChange to the rid-kit directory\n\n```bash\ncd rid-kit\n```\n\nRun a example of Ala-dipeptide on Bohrium using dihedral as CVs:\n\nIn \"machine_bohrium_k8s.json\" file, set \"email\", \"password\" and \"program_id\" to your own **Bohrium account** information. \n**Note** that the **program_id** information in machine.json file should be **int** type rather than **string** type.\n\nThen run this command to submit the jobs\n```bash\nrid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_bohrium_k8s.json\n```\nAfter successful submission you can login into your Bohrium account at [deepmodeling k8s](https://workflows.deepmodeling.com/) to monitor your job status, where the workflow is displayed using the `Argo` UI.\n\nIf you want to run Rid-kit using your own customized CVs, an example is given (see [configure simulations](docs/source/rid_configuration.md) for more details):\n\n**Note** that the length of **angular_mask**, **weights** and **kappas** keys in rid.json should all be equal to the length of your defined CV number.\n```bash\nrid submit -i ./tests/data/001 -c ./rid/template/rid_gmx_custom.json -m ./rid/template/machine_bohrium_k8s.json\n```\n\nYou can also run the example on a Slurm machine (But you need to configure a conda environment on the slurm, see [Installation](docs/source/install.md))\n\n```bash\nrid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_slurm_k8s.json\n```\n\nYou can specify the workflow name by providing WORKFLOW_ID after \"-d\", for example:\n\n```bash\nrid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_bohrium_k8s.json -d ala-dipeptide-1\n```\n\n**Note that the defined workflow-id should only contain lower case alphanumeric character, and specifal character \"-\".**\n\nYou can also specify other types of CVs such as distance or any customized CVs, for detailed explanation you can check \n- [configure simulations](docs/source/rid_configuration.md)\n\n### Continue from an old workflow\n\nUsing `resubmit` to continue from an old workflow\n\n```bash\n# suppose the original workflow id is OLD_ID\nrid resubmit -i ./tests/data/000 -c ./rid/template/rid_gmx_dis.json -m ./rid/template/machine_bohrium_k8s.json OLD_ID -d NEW_ID \n```\n\nIf you want to resubmit from a particular `iteration` and `step`:\n\n```bash\nrid resubmit -i your_dir -c path_to_rid.json -m path_to_machine.json OLD_ID -t ITERATION-ID -p STEP-KEY -d NEW_ID\n```\n\n The `ITERATION-ID`(start from 1) is just `n`th iteration the workflow has been executed. The `STEP-KEY` in 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`.\n\n### Download files from the workflow\n\n```bash\nrid download WORKFLOW_ID -p STEP-KEY -f FILE_NAME -a ITERATION_START -e ITERATION_END -o OUTPUT_DIR\n```\n\ntypically we want the trajectories information from each exploration step, suppose we run a workflow for 20 iterations.\n\n```bash\nrid download WORKFLOW_ID -p run-exploration -f trajectory -a 1 -e 20 -o my_protein_out\n```\n\nDetained explanation for other files in the Rid run can be found as follows:\n- [Download files](docs/source/rid_download.md)\n\n### Reduce the dimension of free energy model\nAfter 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:\n```bash\nrid redim -i ./test/data/models -c ./rid/template/rid_mcmc_cv_dih.json -m ./rid/template/machine_bohrium_k8s_mcmc.json\n```\nThen you will get the projected free energy surface for ala-dipeptide\n | \n---|---\n\nYou can also include .out file representing the CV output information inside the directory specified by `-i` parameter, this will plot the CV output upon the free energy surface.\n\n# Use Rid-kit with Local k8s\n\nA tutorial on using Rid-kit with k8s environment configured by your own can be found as follows:\n\n- [Tutorial](docs/source/tutorial.md)\n\n# Use Rid-kit without k8s environment\nTo run the workflow without k8s environment, one can use the `Debug` mode of `Dflow`. In this mode however, one can not monitor the workflow in the `Argo` UI.\n## Install the computation environment\nIf you want to run Rid-kit on a local machine or server, without `k8s` enviroment, you need to configure a conda environment on your machine, see [Installation](docs/source/install.md))\n## Install the latest rid-kit\n```bash\npip install setuptools_scm\npip install -U rid-kit\n```\n## Run an example\nIf one wants to run the workflow on the `Slurm` machine locally, change to the rid-kit directory and type (change to your slurm configuration)\n\n```bash\nDFLOW_DEBUG=1 rid submit -i ./tests/data/000 -c ./rid/template/rid_gmx_dih.json -m ./rid/template/machine_slurm_local.json -d ala-dipeptide-1\n```\n\n# Main procedure of RiD\n\nRiD will run in iterations. Every iteration contains tasks below:\n\n1. Biased MD;\n2. Restrained/Constrained MD;\n3. Training neural network.\n\n## Biased MD\n\nJust 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.\n\n## Restrained/Constrained MD\n\nThis procedure will calculate the mean force based on the sampling results of restrained MD or constrained MD, which can generate data set for training. \n\n## Neural network training\n\nA fully connected NN will be trained via sampling data. This network will generate a map from selected CV to free energy.\n\nA more detailed description of RiD is published now, please see:\n\n> [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.\n> \n> [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.\n\n# Preparing files in the input directory\nRules for preparing files in the input directory can be found in\n- [Preparing files](docs/source/prepare_files.md)\n\n# Configure simulations\n- [configure simulations](docs/source/rid_configuration.md)\n\n# Configure machine resources\n- [configure machines](docs/source/rid_machine.md)\n\n# Configure mcmc \n- [configure mcmc dimension reduction](docs/source/mcmc_configuration.md)\n\n# Installation of environment on Slurm\nIf 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 in\n- [Installation](docs/source/install.md)\n\n# Installation with DeepMD potential support\nInstallation of the computation environment with DeepMD potential support on slurm machines can be found in\n- [Installation of dp](docs/source/install_dp.md)\n\n# Workflow Synopsis\n\n- \n\n# Troubleshooting\n- [Installation](docs/source/troubleshooting/installation.md)\n- [Minikube](docs/source/troubleshooting/minikube.md)\n- [Submit](docs/source/troubleshooting/submit.md)\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "RiD package for enhanced sampling",
"version": "0.6.4",
"project_urls": {
"Homepage": "https://github.com/deepmodeling/rid-kit"
},
"split_keywords": [
"enhanced",
"sampling",
"reinforced",
"dynamics",
"rid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3ef8f908f1af1944eaf9fd87c73fd822a3f89e8bd6e5bcf5758154c99dbd6a8",
"md5": "56d2fa727eb6cd29eba499d4c6c8595c",
"sha256": "d5b306909f6d2237ae37ddbf2d8ccd868889456dd79b8d322dd8858f773651c2"
},
"downloads": -1,
"filename": "rid_kit-0.6.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56d2fa727eb6cd29eba499d4c6c8595c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 119769,
"upload_time": "2024-05-13T08:54:40",
"upload_time_iso_8601": "2024-05-13T08:54:40.263366Z",
"url": "https://files.pythonhosted.org/packages/a3/ef/8f908f1af1944eaf9fd87c73fd822a3f89e8bd6e5bcf5758154c99dbd6a8/rid_kit-0.6.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f0dec55b87562705c4cb8c32359a505f49393057beb495f3a63666fca7c083b",
"md5": "c02e07baba2f683e736a45203baf30c0",
"sha256": "967f582e64fa92bef694e1b0a86f43b9fee671f359f9e34751f07c5b13c35f4a"
},
"downloads": -1,
"filename": "rid-kit-0.6.4.tar.gz",
"has_sig": false,
"md5_digest": "c02e07baba2f683e736a45203baf30c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 3914120,
"upload_time": "2024-05-13T08:54:42",
"upload_time_iso_8601": "2024-05-13T08:54:42.067128Z",
"url": "https://files.pythonhosted.org/packages/1f/0d/ec55b87562705c4cb8c32359a505f49393057beb495f3a63666fca7c083b/rid-kit-0.6.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 08:54:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepmodeling",
"github_project": "rid-kit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "protobuf",
"specs": [
[
"==",
"3.20.1"
]
]
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "pydflow",
"specs": []
},
{
"name": "tensorflow",
"specs": [
[
"==",
"2.6.2"
]
]
},
{
"name": "typeguard",
"specs": [
[
"==",
"2.10.0"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"1.4.4"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.10.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.6.3"
]
]
},
{
"name": "dargs",
"specs": [
[
"==",
"0.3.5"
]
]
},
{
"name": "dpdispatcher",
"specs": [
[
"==",
"0.6.0"
]
]
},
{
"name": "google",
"specs": []
},
{
"name": "mdtraj",
"specs": []
},
{
"name": "dpdata",
"specs": []
},
{
"name": "parmed",
"specs": []
},
{
"name": "dpdispatcher",
"specs": []
},
{
"name": "lbg",
"specs": []
},
{
"name": "matplotlib",
"specs": []
}
],
"lcname": "rid-kit"
}
JSON
