diff --git a/doc/src/JPG/bow_tutorial_01.png b/doc/src/JPG/bow_tutorial_01.png new file mode 100755 index 0000000000000000000000000000000000000000..2060927250e2107c3d3de0052468e734e80d01c4 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_01.png differ diff --git a/doc/src/JPG/bow_tutorial_01_small.png b/doc/src/JPG/bow_tutorial_01_small.png new file mode 100755 index 0000000000000000000000000000000000000000..a31ad22501f2f77c091a2851ddf9b13f6ff9bf87 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_01_small.png differ diff --git a/doc/src/JPG/bow_tutorial_02.png b/doc/src/JPG/bow_tutorial_02.png new file mode 100755 index 0000000000000000000000000000000000000000..166a0d1a3c9dc2ac853dd7a7b5b8f4356ee35294 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_02.png differ diff --git a/doc/src/JPG/bow_tutorial_02_small.png b/doc/src/JPG/bow_tutorial_02_small.png new file mode 100755 index 0000000000000000000000000000000000000000..a8fa24957a7db709b7633211c16420da5a95aeac Binary files /dev/null and b/doc/src/JPG/bow_tutorial_02_small.png differ diff --git a/doc/src/JPG/bow_tutorial_03.png b/doc/src/JPG/bow_tutorial_03.png new file mode 100755 index 0000000000000000000000000000000000000000..4058a4577cdf331ddebe61fe9e1b653545d0c471 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_03.png differ diff --git a/doc/src/JPG/bow_tutorial_03_small.png b/doc/src/JPG/bow_tutorial_03_small.png new file mode 100755 index 0000000000000000000000000000000000000000..e440c8948303cdf820c7350df9a277047cfb2ce3 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_03_small.png differ diff --git a/doc/src/JPG/bow_tutorial_04.png b/doc/src/JPG/bow_tutorial_04.png new file mode 100755 index 0000000000000000000000000000000000000000..d0c454ef06cc0487c35b67d05b8d16792d9105d1 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_04.png differ diff --git a/doc/src/JPG/bow_tutorial_04_small.png b/doc/src/JPG/bow_tutorial_04_small.png new file mode 100755 index 0000000000000000000000000000000000000000..fae576a7bb72d7af3d5c3afdd5f7a7f507e3a265 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_04_small.png differ diff --git a/doc/src/JPG/bow_tutorial_05.png b/doc/src/JPG/bow_tutorial_05.png new file mode 100755 index 0000000000000000000000000000000000000000..8d1dcc581d75c84d59a97bfb1ea3409f52d607a9 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_05.png differ diff --git a/doc/src/JPG/bow_tutorial_06.png b/doc/src/JPG/bow_tutorial_06.png new file mode 100755 index 0000000000000000000000000000000000000000..00c3947b1d12678d95a96bc2ded8d7e1053ba4f5 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_06.png differ diff --git a/doc/src/JPG/bow_tutorial_07.png b/doc/src/JPG/bow_tutorial_07.png new file mode 100755 index 0000000000000000000000000000000000000000..aad4e5eaae27866ee4ce2abf26b951c2c2b6a848 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_07.png differ diff --git a/doc/src/JPG/bow_tutorial_08.png b/doc/src/JPG/bow_tutorial_08.png new file mode 100755 index 0000000000000000000000000000000000000000..beb1bcff28748f92867809f0b59541760020ab8e Binary files /dev/null and b/doc/src/JPG/bow_tutorial_08.png differ diff --git a/doc/src/JPG/bow_tutorial_09.png b/doc/src/JPG/bow_tutorial_09.png new file mode 100755 index 0000000000000000000000000000000000000000..187f4bbdb2a325044559921fef95c3cb0fb58fc0 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_09.png differ diff --git a/doc/src/JPG/bow_tutorial_10.png b/doc/src/JPG/bow_tutorial_10.png new file mode 100755 index 0000000000000000000000000000000000000000..4603a46637b1e315f26ef8c77c3155e46dbf7d15 Binary files /dev/null and b/doc/src/JPG/bow_tutorial_10.png differ diff --git a/doc/src/tutorial_bash_on_windows.txt b/doc/src/tutorial_bash_on_windows.txt new file mode 100755 index 0000000000000000000000000000000000000000..66712bdffafc8173bef83e5883bae8d3e0843ec0 --- /dev/null +++ b/doc/src/tutorial_bash_on_windows.txt @@ -0,0 +1,203 @@ +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +Using LAMMPS with Bash on Windows :h3 +[written by Richard Berger] + +:line +Starting with Windows 10 you can install Linux tools directly in Windows. This +allows you to compile LAMMPS following the same procedure as on a real Ubuntu +Linux installation. Software can be easily installed using the package manager +via apt-get and all files are accessible in both the Windows Explorer and your +Linux shell (bash). This avoids switching to a different operating system or +installing a virtual machine. Everything runs on Windows. + +Installing Bash on Windows :h4 + +Prerequisites :h5 + +Windows 10 (64bit only) +Latest updates installed :ul + +Enable developer mode :h5 +You enable this feature by first opening Windows Settings and enabling +Developer mode. Go to the Windows settings and search for "developer". This +will allow you to install software which comes from outside of the Windows +Store. You might be prompted to reboot your compute. Please do so. + +:image(JPG/bow_tutorial_01_small.png,JPG/bow_tutorial_01.png) +:image(JPG/bow_tutorial_02_small.png,JPG/bow_tutorial_02.png) +:image(JPG/bow_tutorial_03_small.png,JPG/bow_tutorial_03.png) + +Install Windows Subsystem for Linux :h5 + +Next you must ensure that the Window Subsystem for Linux is installed. Again, +search for "enable windows features" in the Settings dialog. This opens a +dialog with a list of features you can install. Add a checkmark to Windows +Subsystem for Linux (Beta) and press OK. + +:image(JPG/bow_tutorial_04_small.png,JPG/bow_tutorial_04.png) +:image(JPG/bow_tutorial_05.png,JPG/bow_tutorial_05.png) + +Install Bash for Windows :h5 + +After installation completes, type "bash" in the Windows Start menu search. +Select the first found option. This will launch a command-line window which +will prompt you about installing Ubuntu on Windows. Confirm with "y" and press +enter. This will then download Ubuntu for Windows. + +:image(JPG/bow_tutorial_06.png) +:image(JPG/bow_tutorial_07.png) + +During installation, you will be asked for a new password. This will be used +for installing new software and running commands with sudo. + +:image(JPG/bow_tutorial_08.png) + +Type exit to close the command-line window. + +Go to the Start menu and type "bash" again. This time you will see a "Bash on +Ubuntu on Windows" Icon. Start this program. + +:image(JPG/bow_tutorial_09.png) + +Congratulations, you have installed [Bash on Ubuntu on Windows]. + +:image(JPG/bow_tutorial_10.png) + +:line + +Compiling LAMMPS in Bash on Windows :h4 + +The installation of LAMMPS in this environment is identical to working inside +of a real Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04. + +Installing prerequisite packages :h5 + +First upgrade all existing packages using + +sudo apt update +sudo apt upgrade -y :pre + +Next install the following packages, which include compilers and libraries +needed for various LAMMPS features: + +sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng12-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools :pre + +Files in Ubuntu on Windows :h5 + +When you launch "Bash on Ubuntu on Windows" you will start out in your Linux +user home directory /home/[username]. You can access your Windows user directory +using the /mnt/c/Users/[username] folder. + + +Download LAMMPS :h5 + +Obtain a copy of the LAMMPS code and go into it using "cd" + +Option 1: Downloading LAMMPS tarball using wget :h6 + +wget http://lammps.sandia.gov/tars/lammps-stable.tar.gz +tar xvzf lammps-stable.tar.gz +cd lammps-31Mar17 :pre + +Option 2: Obtaining LAMMPS code from GitHub :h6 + +git clone https://github.com/lammps/lammps.git +cd lammps :pre + +Compiling LAMMPS :h5 + +At this point you can compile LAMMPS like on Ubuntu Linux. + +Compiling serial version :h6 + +cd src/ +make -j 4 serial :pre + +This will create an executable called lmp_serial in the src/ directory + +Compiling MPI version :h6 + +cd src/ +make -j 4 mpi :pre + +This will create an executable called lmp_mpi in the src/ directory + +:line + +Finally, please note the absolute path of your src folder. You can get this using + +pwd :pre + +or + +echo $PWD :pre + +To run any examples you need the location of the executable. For now, let us +save this location in a temporary variable + +LAMMPS_DIR=$PWD :pre + +:line + +Running an example script :h5 + +Once compiled you can execute some of the LAMMPS examples. Switch into the +examples/melt folder + +cd ../examples/melt :pre + +The full path of the serial executable is $LAMMPS_DIR/lmp_serial, while the mpi +version is $LAMMPS_DIR/lmp_mpi. You can run the melt example with either +version as follows: + +$LAMMPS_DIR/lmp_serial -in in.melt :pre + +or + +mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt :pre + +Note the use of our variable $LAMMPS_DIR, which expands into the full path of +the LAMMPS src folder we saved earlier. + +Adding your executable directory to your PATH :h6 + +You can avoid having to type the full path of your LAMMPS binary by adding its +parent folder to the PATH environment variable as follows: + +export PATH=$LAMMPS_DIR:$PATH :pre + +Input scripts can then be run like this: + +lmp_serial -in in.melt :pre + +or + +mpirun -np 4 lmp_mpi -in in.melt :pre + +However, this PATH variable will not persist if you close your bash window. +To persist this setting edit the $HOME/.bashrc file using your favorite editor +and add this line + +export PATH=/full/path/to/your/lammps/src:$PATH :pre + +[Example:] + +For an executable lmp_serial with a full path + +/home/richard/lammps/src/lmp_serial :pre + +the PATH variable should be + +export PATH=/home/richard/lammps/src:$PATH :pre + +NOTE: This should give you a jump start when trying to run LAMMPS on Windows. +To become effective in this environment I encourage you to look into Linux +tutorials explaining Bash and Basic Unix commands (e.g., "Linux +Journey"_https://linuxjourney.com)