From b4633bc2b2271dd890c6c55568c638aefcc1b0de Mon Sep 17 00:00:00 2001
From: Richard Berger <richard.berger@temple.edu>
Date: Tue, 16 Mar 2021 11:33:56 -0400
Subject: [PATCH] Update PyLammps examples README

---
 python/examples/pylammps/README    | 28 ----------
 python/examples/pylammps/README.md | 89 ++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 28 deletions(-)
 delete mode 100644 python/examples/pylammps/README
 create mode 100644 python/examples/pylammps/README.md

diff --git a/python/examples/pylammps/README b/python/examples/pylammps/README
deleted file mode 100644
index ac69622287..0000000000
--- a/python/examples/pylammps/README
+++ /dev/null
@@ -1,28 +0,0 @@
-# Compile LAMMPS as shared library
-
-git clone https://github.com/lammps/lammps.git
-cd lammps/src
-python Make.py -m mpi -png -s ffmpeg exceptions -a file
-
-make -j 4 mode=shlib auto
-cd ../..
-
-# Install Python package
-
-virtualenv testing
-source testing/bin/activate
-
-(testing) cd lammps/python
-(testing) python install.py
-(testing) pip install jupyter matplotlib mpi4py
-
-(testing) cd ../../examples
-
-# Launch jupter and work inside browser
-
-(testing) jupyter notebook
-
-# Use Ctrl+c to stop jupyter
-
-# finally exit the virtualenv
-(testing) deactivate
diff --git a/python/examples/pylammps/README.md b/python/examples/pylammps/README.md
new file mode 100644
index 0000000000..fb0eafad14
--- /dev/null
+++ b/python/examples/pylammps/README.md
@@ -0,0 +1,89 @@
+# PyLammps and Jupyter Notebooks
+
+This folder contains examples showcasing the usage of the PyLammps Python
+interface and Jupyter notebooks. To use this you will need LAMMPS compiled as
+a shared library and the LAMMPS Python package installed.
+
+An extensive guide on how to achieve this is documented in the [LAMMPS manual](https://lammps.sandia.gov/doc/Python_install.html). There is also a [PyLammps tutorial](https://lammps.sandia.gov/doc/Howto_pylammps.html).
+
+The following will show one way of creating a Python virtual environment
+which has both LAMMPS and its Python package installed:
+
+1. Clone the LAMMPS source code
+
+   ```shell
+   $ git clone https://github.com/lammps/lammps.git
+   $ cd lammps
+   ```
+
+2. Create a build folder
+
+   ```shell
+   $ mkdir build
+   $ cd build
+   ```
+
+3. Create a virtual environment for Python
+
+   ```shell
+   $ python3 -m venv myenv
+   ```
+
+4. Extend `LD_LIBRARY_PATH` (Unix/Linux) or `DYLD_LIBRARY_PATH` (MacOS)
+
+   On Unix/Linux:
+   ```shell
+   $ echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> myenv/bin/activate
+   ```
+
+   On MacOS:
+   ```shell
+   echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> myenv/bin/activate
+   ```
+
+5. Activate the virtual environment
+
+   ```shell
+   $ source myenv/bin/activate
+   (myenv)$
+   ```
+
+6. Configure LAMMPS compilation (CMake)
+
+   ```shell
+   (myenv)$ cmake -C ../cmake/presets/minimal.cmake \
+                  -D BUILD_SHARED_LIBS=on \
+                  -D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on \
+                  -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV \
+                  ../cmake
+   ```
+
+7. Compile LAMMPS
+
+   ```shell
+   (myenv)$ cmake --build .
+   ```
+
+8. Install LAMMPS and Python package into virtual environment
+
+   ```shell
+   (myenv)$ cmake --install .
+   ```
+
+9. Install other Python packages into virtual environment
+
+   ```shell
+   (myenv)$ pip install jupyter matplotlib mpi4py
+   ```
+
+10. Navigate to pylammps examples folder
+
+    ```shell
+    (myenv)$ cd ../python/examples/pylammmps
+    ```
+
+11. Launch Jupyter and work inside browser
+
+    ```shell
+    (myenv)$ jupyter notebook
+    ```