mindspore/model_zoo/research/hpc/sponge/README.md

# SPONGE Example

- [Description](#Description)
- [Dataset](#Dataset)
- [Environment Requirements](#Environment-Requirements)
- [Quick Start](#Quick-Start)
- [Script Description](#Script-Description)
    - [Script and Sample Code](#Script-and-Sample-Code)
    - [Training Process](#Training-Process)
- [Model Description](#Model-Description)
    - [Evaluation Performance](#Evaluation-Performance)
- [Result](#Result)
- [ModelZoo Homepage](#ModelZoo-Homepage)

## Description

SPONGE in MindSpore is a molecular dynamics simulation library, featuring high performance and modularization. It is developed by the `Yiqin Gao` group (`Peking University` and `Shenzhen Bay Laboratory`) and `Huawei MindSpore` team. It can efficiently simulate traditional molecular dynamics tasks based on the "graph-kernel-fusion" and "automatic parallelization" features of MindSpore. In addition, it utilizes the automatic differentiation feature of MindSpore, and introduces machine learning methods, such as neural network, into traditional molecular simulation, achieving methodological inventions.

The following example demonstrates how to perform high-performance molecular dynamics simulations with the built-in MindSpore SPONGE module on a `GPU`.

## Dataset

There are three inputs in the example, the property file `NVT_290_10ns.in`, the topology file `WATER_ALA.parm7` and the coordinates file `WATER_ALA_350_cool_290.rst7`, respectivelly.

![ALA Aqueous System](https://images.gitee.com/uploads/images/2021/0323/184453_4bd9b1a6_8142020.png "图片1.png")

The topology file and coordinates file can be generated by `tleap` in `AmberTools` ([link](<http://ambermd.org/GetAmber.php>)). For more details, please refer to:

- [SPONGE Tutorial](https://gitee.com/mindspore/docs/blob/master/tutorials/training/source_zh_cn/advanced_use/hpc_sponge.md)

## Environment Requirements

- Hardware: `GPU`
    - Prepare a hardware environment with `GPU`.
- Framework
    - [MindSpore](https://www.mindspore.cn/install/en)
- For more information, visit the resources below:
    - [MindSpore Tutorials](https://www.mindspore.cn/tutorial/training/en/master/index.html)
    - [MindSpore Python API](https://www.mindspore.cn/doc/api_python/en/master/index.html)

## Quick Start

After installing MindSpore, run the following command:

```shell
python main.py --i /path/NVT_290_10ns.in \
               --amber_parm /path/WATER_ALA.parm7 \
               --c /path/WATER_ALA_350_cool_290.rst7 \
               --o /path/ala_NVT_290_10ns.out
```

`path` is the path which stores input files.

## Script Description

### Script and Sample Code

```shell
├── sponge
    ├── README.md
    ├── main.py                                  # launch Simulation for SPONGE
    ├── src
        ├── bond.py                              # bond module in SPONGE
        ├── angle.py                             # angle module in SPONGE
        ├── dihedral.py                          # dihedral module in SPONGE
        ├── nb14.py                              # nb14 module in SPONGE
        ├── Langevin_Liujian_md.py               # Langevin_Liujian_md module in SPONGE
        ├── lennard_jones.py                     # lennard_jones module in SPONGE
        ├── md_information.py                    # save md information module in SPONGE
        ├── neighbor_list.py                     # neighbor_list module in SPONGE
        ├── particle_mesh_ewald.py               # particle_mesh_ewald module in SPONGE
        ├── simulation.py                # SPONGE simulation
```

### Training Process

```shell
python main.py --i /path/NVT_290_10ns.in \
               --amber_parm /path/WATER_ALA.parm7 \
               --c /path/WATER_ALA_350_cool_290.rst7 \
               --o /path/ala_NVT_290_10ns.out
```

Training result will be stored in the specified .out file.

## Result

After training, the following results are stored in `ala_NVT_290_10ns.out`:

```text
_steps_ _TEMP_ _TOT_POT_ENE_ _BOND_ENE_ _ANGLE_ENE_ _DIHEDRAL_ENE_ _14LJ_ENE_ _14CF_ENE_ _LJ_ENE_ _CF_PME_ENE_
      1 293.105   -6117.709   1204.406       7.096          4.491      3.456     44.018 1372.488    -8753.664
   ...
```

There are sorts of energy in the output, steps (_steps_), temperature (_TEMP_), total energy (_TOT_POT_E_), bond energy (_BOND_ENE_), angle energy (_ANGLE_ENE_), dihedral energy (_DIHEDRAL_ENE_), non-bond energy, includes Coulomb force (_14CF_ENE_) and Lennard-Jones energy (_14LJ_ENE_), Van der Waals energy (_LJ_ENE_) and Coulomb force in PME (_CF_PME_ENE_).

## Model Description

### Evaluation Performance

| Parameter                 |   GPU |
| -------------------------- |---------------------------------- |
| Resource                   | GPU (Tesla V100 SXM2); memory 16 GB
| Upload date              |
| MindSpore version          | 1.2
| Training parameter        | step=1
| Output                    | numpy file
| Speed                      | 16.7 ms/step
| Total time                 | 10.7 s
| Script                    | [Link](https://gitee.com/mindspore/mindspore/tree/master/model_zoo/research/hpc/sponge)

## ModelZoo Homepage

 Visit [ModelZoo](https://gitee.com/mindspore/mindspore/tree/master/model_zoo).