Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Paddle Backend] Deprecate old paddle branch #3130

Merged
merged 2 commits into from
Jan 12, 2024
Merged

[Paddle Backend] Deprecate old paddle branch #3130

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
608b868
deprecated old paddle branch
HydrogenSulfate Jan 11, 2024
2dc9ce9
update paddle2 url
HydrogenSulfate Jan 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 51 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,71 @@
<span style="font-size:larger;">DeePMD-kit Manual</span>
========
# DeePMD-kit Manual

[![GitHub release](https://img.shields.io/github/release/deepmodeling/deepmd-kit.svg?maxAge=86400)](https://github.com/deepmodeling/deepmd-kit/releases)
[![Documentation Status](https://readthedocs.org/projects/deepmd/badge/?version=latest)](https://deepmd.readthedocs.io/en/latest/?badge=latest)

> [!Caution]
> ⚠️⚠️⚠️
>
> **The current branch is no longer maintained due to the outdated Paddle version it adapts to and the significant differences from the DeePMD-kit main branch.**
>
> **The new paddle backend branch is [DeePMD-kit(paddle branch)](https://github.com/deepmodeling/deepmd-kit/tree/paddle)**

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't the branch be paddle2?

Copy link
Contributor Author

@HydrogenSulfate HydrogenSulfate Jan 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't the branch be paddle2?

I guess paddle2 is not suitable name in the future, and code in old paddle should be removed or moved to other branch name as is not runnable, so can we add extra deprecation note, such as: "As described above, the current paddle branch will be replaced with the content in paddle2 branch after 2024.x.y".
And when arrived 2024.x.y, we replace code in paddle branch with code in paddle2 then delete paddle2 branch?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is not necessary if we want to rename the branch

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is not necessary if we want to rename the branch

URL has been updated

Copy link
Contributor Author

@HydrogenSulfate HydrogenSulfate Jan 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is not necessary if we want to rename the branch

paddle branch will not be maintain any more and the code in paddle branch is too old to run. so I guess it is necessary to remove paddle branch after certain day and move paddle2's code into paddle branch, or any user use paddle branch will not be able to run any code, that's why there is no need to preserve this branch.

Copy link
Member

@njzjz njzjz Jan 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will rename it tomorrow. I prefer keeping the old branch for the recording purposes. Even if no one uses it, people can know the history of development through the old branch.

By the way, we will focus on supporting multiple backends in the next five weeks. After we refactor several codes, it's more easier to support Paddle in the main development branch.

Copy link
Contributor Author

@HydrogenSulfate HydrogenSulfate Jan 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will rename it tomorrow. I prefer keeping the old branch for the recording purposes. Even if no one uses it, people can know the history of development through the old branch.

By the way, we will focus on supporting multiple backends in the next five weeks. After we refactor several codes, it's more easier to support Paddle in the main development branch.

  1. I agree with you much that we need to record old code and history of it even if no one use(so there indeed unnecessary to delete old code), but I guess it is important to move the old code to some "bakcup" branch but not be kept in offcial branch(paddle branch), since an official branch is important or will cause recognition error, and we always prefer showing newest runnable code for those who use DeePMD-kit with paddle backend in official branch.

  2. It is very glad to hear that a multi-backend project is released and you are working for it, willing to help to build together after multi-bakend is finished.

Thanks for your reply.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've renamed paddle to paddle-backup and paddle2 to paddle.

# Table of contents

- [About DeePMD-kit](#about-deepmd-kit)
- [Highlighted features](#highlighted-features)
- [Code structure](#code-structure)
- [License and credits](#license-and-credits)
- [Deep Potential in a nutshell](#deep-potential-in-a-nutshell)
- [Highlighted features](#highlighted-features)
- [Code structure](#code-structure)
- [License and credits](#license-and-credits)
- [Deep Potential in a nutshell](#deep-potential-in-a-nutshell)
- [Download and install](#download-and-install)
- [Use DeePMD-kit](#use-deepmd-kit)
- [Troubleshooting](#troubleshooting)

# About DeePMD-kit
DeePMD-kit is a package written in Python/C++, designed to minimize the effort required to build deep learning based model of interatomic potential energy and force field and to perform molecular dynamics (MD). This brings new hopes to addressing the accuracy-versus-efficiency dilemma in molecular simulations. Applications of DeePMD-kit span from finite molecules to extended systems and from metallic systems to chemically bonded systems.

DeePMD-kit is a package written in Python/C++, designed to minimize the effort required to build deep learning based model of interatomic potential energy and force field and to perform molecular dynamics (MD). This brings new hopes to addressing the accuracy-versus-efficiency dilemma in molecular simulations. Applications of DeePMD-kit span from finite molecules to extended systems and from metallic systems to chemically bonded systems.

For more information, check the [documentation](https://deepmd.readthedocs.io/).

## Highlighted features
* **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition Tensorboard can be used to visualize training procedure.
* **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, i.e., LAMMPS and i-PI, respectively.
* **implements the Deep Potential series models**, which have been successfully applied to finite and extended systems including organic molecules, metals, semiconductors, and insulators, etc.
* **implements MPI and GPU supports**, makes it highly efficient for high performance parallel and distributed computing.
* **highly modularized**, easy to adapt to different descriptors for deep learning based potential energy models.

- **interfaced with TensorFlow**, one of the most popular deep learning frameworks, making the training process highly automatic and efficient, in addition Tensorboard can be used to visualize training procedure.

- **interfaced with high-performance classical MD and quantum (path-integral) MD packages**, i.e., LAMMPS and i-PI, respectively.
- **implements the Deep Potential series models**, which have been successfully applied to finite and extended systems including organic molecules, metals, semiconductors, and insulators, etc.
- **implements MPI and GPU supports**, makes it highly efficient for high performance parallel and distributed computing.
- **highly modularized**, easy to adapt to different descriptors for deep learning based potential energy models.

## Code structure
The code is organized as follows:

* `data/raw`: tools manipulating the raw data files.
The code is organized as follows:

* `examples`: example json parameter files.
- `data/raw`: tools manipulating the raw data files.

* `source/3rdparty`: third-party packages used by DeePMD-kit.
- `examples`: example json parameter files.

* `source/cmake`: cmake scripts for building.
- `source/3rdparty`: third-party packages used by DeePMD-kit.

* `source/ipi`: source code of i-PI client.
- `source/cmake`: cmake scripts for building.

* `source/lib`: source code of DeePMD-kit library.
- `source/ipi`: source code of i-PI client.

* `source/lmp`: source code of Lammps module.
- `source/lib`: source code of DeePMD-kit library.

* `source/op`: tensorflow op implementation. working with library.
- `source/lmp`: source code of Lammps module.

* `source/train`: Python modules and scripts for training and testing.
- `source/op`: tensorflow op implementation. working with library.

- `source/train`: Python modules and scripts for training and testing.

## License and credits

The project DeePMD-kit is licensed under [GNU LGPLv3.0](./LICENSE).
If you use this code in any future publications, please cite this using
If you use this code in any future publications, please cite this using
``Han Wang, Linfeng Zhang, Jiequn Han, and Weinan E. "DeePMD-kit: A deep learning package for many-body potential energy representation and molecular dynamics." Computer Physics Communications 228 (2018): 178-184.``

## Deep Potential in a nutshell

The goal of Deep Potential is to employ deep learning techniques and realize an inter-atomic potential energy model that is general, accurate, computationally efficient and scalable. The key component is to respect the extensive and symmetry-invariant properties of a potential energy model by assigning a local reference frame and a local environment to each atom. Each environment contains a finite number of atoms, whose local coordinates are arranged in a symmetry preserving way. These local coordinates are then transformed, through a sub-network, to a so-called *atomic energy*. Summing up all the atomic energies gives the potential energy of the system.

The initial proof of concept is in the [Deep Potential][1] paper, which employed an approach that was devised to train the neural network model with the potential energy only. With typical *ab initio* molecular dynamics (AIMD) datasets this is insufficient to reproduce the trajectories. The Deep Potential Molecular Dynamics ([DeePMD][2]) model overcomes this limitation. In addition, the learning process in DeePMD improves significantly over the Deep Potential method thanks to the introduction of a flexible family of loss functions. The NN potential constructed in this way reproduces accurately the AIMD trajectories, both classical and quantum (path integral), in extended and finite systems, at a cost that scales linearly with system size and is always several orders of magnitude lower than that of equivalent AIMD simulations.
Expand All @@ -65,14 +78,13 @@ In addition to building up potential energy models, DeePMD-kit can also be used

Please follow our [github](https://github.com/deepmodeling/deepmd-kit) webpage to download the [latest released version](https://github.com/deepmodeling/deepmd-kit/tree/master) and [development version](https://github.com/deepmodeling/deepmd-kit/tree/devel).

DeePMD-kit offers multiple installation methods. It is recommend using easily methods like [offline packages](doc/install.md#offline-packages), [conda](doc/install.md#with-conda) and [docker](doc/install.md#with-docker).
DeePMD-kit offers multiple installation methods. It is recommend using easily methods like [offline packages](doc/install.md#offline-packages), [conda](doc/install.md#with-conda) and [docker](doc/install.md#with-docker).

One may manually install DeePMD-kit by following the instuctions on [installing the python interface](doc/install.md#install-the-python-interface) and [installing the C++ interface](doc/install.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS and i-PI.


# Use DeePMD-kit

The typical procedure of using DeePMD-kit includes 5 steps
The typical procedure of using DeePMD-kit includes 5 steps

1. [Prepare data](doc/use-deepmd-kit.md#prepare-data)
2. [Train a model](doc/use-deepmd-kit.md#train-a-model)
Expand All @@ -86,19 +98,21 @@ A quick-start on using DeePMD-kit can be found [here](doc/use-deepmd-kit.md).

A full [document](doc/train-input.rst) on options in the training input script is available.


# Troubleshooting
In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows.

In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows.
If other unexpected problems occur, you're welcome to contact us for help.

## Model compatability

When the version of DeePMD-kit used to training model is different from the that of DeePMD-kit running MDs, one has the problem of model compatability.

DeePMD-kit guarantees that the codes with the same major and minor revisions are compatible. That is to say v0.12.5 is compatible to v0.12.0, but is not compatible to v0.11.0 nor v1.0.0.
DeePMD-kit guarantees that the codes with the same major and minor revisions are compatible. That is to say v0.12.5 is compatible to v0.12.0, but is not compatible to v0.11.0 nor v1.0.0.

## Installation: inadequate versions of gcc/g++
Sometimes you may use a gcc/g++ of version <4.9. If you have a gcc/g++ of version > 4.9, say, 7.2.0, you may choose to use it by doing

Sometimes you may use a gcc/g++ of version <4.9. If you have a gcc/g++ of version > 4.9, say, 7.2.0, you may choose to use it by doing

```bash
export CC=/path/to/gcc-7.2.0/bin/gcc
export CXX=/path/to/gcc-7.2.0/bin/g++
Expand All @@ -107,25 +121,30 @@ export CXX=/path/to/gcc-7.2.0/bin/g++
If, for any reason, for example, you only have a gcc/g++ of version 4.8.5, you can still compile all the parts of TensorFlow and most of the parts of DeePMD-kit. i-Pi will be disabled automatically.

## Installation: build files left in DeePMD-kit

When you try to build a second time when installing DeePMD-kit, files produced before may contribute to failure. Thus, you may clear them by

```bash
cd build
rm -r *
```

and redo the `cmake` process.

## MD: cannot run LAMMPS after installing a new version of DeePMD-kit

This typically happens when you install a new version of DeePMD-kit and copy directly the generated `USER-DEEPMD` to a LAMMPS source code folder and re-install LAMMPS.

To solve this problem, it suffices to first remove `USER-DEEPMD` from LAMMPS source code by
To solve this problem, it suffices to first remove `USER-DEEPMD` from LAMMPS source code by

```bash
make no-user-deepmd
```

and then install the new `USER-DEEPMD`.

If this does not solve your problem, try to decompress the LAMMPS source tarball and install LAMMPS from scratch again, which typically should be very fast.


[1]: http://www.global-sci.com/galley/CiCP-2017-0213.pdf
[2]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001
[3]:https://arxiv.org/abs/1805.09003
Expand Down
Loading