Numerical project I - MD simulation (NVE)
Contents
Numerical project I - MD simulation (NVE)¶
Congratulations! You have mastered important concepts in classical and statistical mechanics, and learned about the nuts and bolts of MD simulations. You are now ready for your first project - writing your very own MD code. How exciting! The project will be written in Python, a highly popular coding language, extremely relevant for both scientific research and the current job market. To start, we need to set up our development environment. Please follow the instructions below.
Installing the Anaconda Python distribution¶
Anaconda is a very popular Python distribution, aimed for scientific computing. It bundles several useful packages, such as Numpy, SciPy, and Pandas. If you need to refresh your knowledge in Python, please see the SciPy lecture notes.
Installing Anaconda is free, just follow these instructions for Linux, Mac, or Windows operating systems. Anaconda also includes a light Integrated Development Environment (IDE) called Spyder. If you already know and like PyCharm or Vistual Studio code instead, go ahead and use whatever IDE you like. I cannot, however, help you debug your setup unless you use Spyder and Anaconda. You can also use any text editor and just run your code through the terminal. But an IDE gives convenient access to powerful tools for modern programming including debugging, profiling, syntax highlighting and editing, etc.
The Linux terminal¶
If you have never used it, I highly recommend getting familiar with it. It was designed for programming. You can see for example this basic tutorial by Ubuntu, one of the most popular Linux distributions. The operating system of your computer does not have to be Linux to use the Linux terminal. Mac OS has a terminal, and so does Windows. On Mac, just open the terminal. To enable the Windows Subsystem for Linux (WSL), see the following instructions. You do not have to use the Linux terminal if you do not want to. All that is required to complete the project is an Anaconda installation and GitHub Desktop (see below).
GitHub basics¶
GitHub is a code hosting platform for software development. It relies on an open-source version control system called Git. De facto, all software development projects today use some kind of version control. It allows us to develop the code together as a team, keep track of changes, suggest new features, and merge everything in a simple workflow.
The basic object is a repository (“repo”), which stores all of the source code for the project. You can create your repo, or clone (GitHub jargon for copying) an existing repo. You can also fork a repo, which is similar to cloning, but you typically do it when you want to contribute your changes back to the original repo, and not just develop your version of it.
Each repository can have several branches. The default one is called main. When you want to implement a new feature, the typical workflow is to clone the repository and create a new branch dedicated to your feature. In this way, you will not change the main version of the code while you work. Next, you develop the new feature by adding or editing the source code. Every time you would like to save a checkpoint that you could return to if needed, you should commit your changes and push them to update the remote repository. When you want to discuss your changes and consult with your team, you can create a pull request on GitHub. Once you are done with all changes, you need to merge your branch back with the original main branch. This is done by closing the pull request and merging.
The first “assignment” is an exercise, developed by GitHub, to let you practice this workflow. It will explain everything I mentioned in brief and more. To do it, first choose whether you will be working with the terminal or graphical user interface (GUI).
Prerequisites for all:
Create a free account on GitHub.
Prerequisites for GUI users:
Install GitHub Desktop to clone, commit and push to repo.
Install Anaconda and work with Spyder to edit files.
Prerequisites for terminal users:
Windows: Install WSL. Follow these instructions.
All OS: Install Anaconda with Spyder through the terminal, see instructions here. You can use the following command to fetch the installer for Linux directly from the terminal:
wget https://repo.anaconda.com/archive/Anaconda3-2021.11-Linux-x86_64.sh
Both:
Click the invitation link from GitHub Classroom. This creates your personal Git & GitHub Fundamentals repo. Currently, it only has one text file
README.mdwhich explains the GitHub workflow. Read it carefully, follow the links as needed, and make sure your understand before proceeding.Clone the repo locally to your computer. The changes you will make on your local copy will not affect the remote one until you push your changes (see the last step below).
git clone https://github.com/Molecular-Simulations-Course/git-github-fundamentals-YOURNAME.git
Create your branch and switch to working in it using the command
git checkout -b feature
Create a new Markdown file
Hello_world.mdusing Spyder and add to it some text.Commit your changes.
git commit Hello_world.md
Push your changes to the remote repo.
git push
Go back to GitHub to your repo and open a pull request, assign Barak as a reviewer. I will give you feedback and make comments. If you are done, I will close the pull request and merge your branch feature into your main branch. Then, I will also delete the feature branch, which is no longer needed.
All of the steps above can also be done using the GUI of GitHub desktop instead.
The project¶
Your first real assignment (i.e., one that will be graded) is now also available on the GitHub Classroom.
Use the link to create your own repository. You do not need to edit the Ar_init_super.xyz, LICENSE, or README.md files. You will only need to edit the run.py and sim.py files. They both have very detailed instructions inside. For example, sim.py reads:
#sim.py
WELCOME TO YOU FIRST PROJECT! THIS BIT OF TEXT IS CALLED A DOCSTRING.
BELOW, I HAVE CREATED A CLASS CALLED "SIMULATION" FOR YOUR CONVENIENCE.
I HAVE ALSO IMPLEMENTED A CONSTRUCTOR, WHICH IS A METHOD THAT IS CALLED
EVERY TIME YOU CREATE AN OBJECT OF THE CLASS USING, FOR EXAMPLE,
>>> mysim = Simulation( dt=0.1E-15, L=11.3E-10, ftype="LJ" )
I HAVE ALSO IMPLEMENTED SEVERAL USEFUL METHODS THAT YOU CAN CALL AND USE,
BUT DO NOT EDIT THEM. THEY ARE: evalForce, dumpXYZ, dumpThermo and readXYZ.
YOU DO NOT NEED TO EDIT THE CLASS ITSELF.
YOUR JOB IS TO IMPLEMENT THE LIST OF CLASS METHODS DEFINED BELOW.
ENTER YOUR COE WHERE YOU WILL SEE THE FOLLOWING TEXT:
################################################################
####################### YOUR CODE GOES HERE ####################
################################################################
YOU ARE, HOWEVER, EXPECTED TO UNDERSTAND WHAT ARE THE MEMBERS OF THE CLASS
AND USE THEM IN YOUR IMPLEMENTATION. THEY ARE ALL EXPLAINED IN THE
DOCSTRING OF THE CONSTRUCTOR BELOW. FOR EXAMPLE, WHENEVER YOU WISH
TO USE/UPDATE THE MOMENTA OF THE PARTICLES IN ONE OF YOUR METHODS, YOU CAN
ACCESS IT BY USING self.p.
>>> self.p = np.zeros( (self.Natoms,3) )
FINALLY, YOU WILL NEED TO EDIT THE run.py FILE WHICH RUNS THE SIMULATION.
SEE MORE INSTRUCTIONS THERE.
And the instructions in run.py are:
HERE, TO RUN THE SIMULATION, YOU WILL NEED TO DO THE FOLLOWING THINGS:
1. CREATE AN OBJECT OF THE SIMULATION CLASS. A MINIMAL EXAMPLE IS
>>> mysim = Simulation( dt=0.1E-15, L=11.3E-10, ftype="LJ" )
2. DEFINE THE PARAMETERS FOR THE POTENTIAL.
USE A DICTIONARY, FOR EXAMPLE FOR LJ MODEL OF ARGON, IN SI UNITS
>>> params = { "eps": 1.656778224E-21, "sig": 3.4E-10 }
THEN, CALLING THE METHODS YOU IMPLEMENTED IN sim.py, YOU NEED TO
3. READ THE INITIAL XYZ FILE PROVIDED OR SAMPLE INITIAL COORDINATES.
4. SAMPLE INITIAL MOMENTA FROM MB DISTRIBUTION.
5. REMOVE COM MOTION.
6. RUN THE SIMULATION, INCLUDING PRINTING XYZ AND ENERGIES TO FILES.
NOTE THAT TO CALL A METHOD OF A CLASS FOR A SPECIFIC OBJECT, THE SYNTAX IS
>>> mysim.funcName( args )
FINALLY, YOU SHOULD
7. ANALYZE YOUR RESULTS. PLOT THE KINETIC AND POTENTIAL ENERGIES,
AND SEPARATE FIGURE WITH THE CHANGE IN % OF THE TOTAL ENERGY
WITH RESPECT TO t=0.
NOTE: THE INPUT FILE GIVEN HAS THE COORDINATES IN ANGSTROM.
*YOUR OUTPUT XYZ FILE SHOULD BE PRINTED IN ANGSTROM TOO*, BUT YOU CAN USE
ANY UNITS YOU WANT IN BETWEEN, I SUGGEST USING SI UNITS.
As you can see, most of your coding will be done in the sim.py file.
I have created a class called Simulation which defines the methods and data members that you can use in your implementation. Your job is twofold:
Implement the methods for class Simulation, based on the material we have covered.
Implement a several short scripts
run.pyto call the methods you have implemented and run a simulation.
The methods you will have to implement include, for example, sampleMB() which samples initial positions from the Maxwell-Boltzmann distribution. How do I know? Because in sim.py you will see its definition, with a description of what needs to be implemented and the place to write your code:
def sampleMB( self, temp, removeCM=True ):
"""
THIS FUNCTIONS SAMPLES INITIAL MOMENTA FROM THE MB DISTRIBUTION.
IT ALSO REMOVES THE COM MOMENTA, IF REQUESTED.
Parameters
----------
temp : float
The temperature to sample from.
removeCM : bool, optional
Remove COM velocity or not. The default is True.
Returns
-------
None. Sets the value of self.p.
"""
################################################################
####################### YOUR CODE GOES HERE ####################
################################################################
I highly recommend implementing one method at a time and testing that it works by running run.py that calls it, before moving on to the next method. Do not forget to commit and push along the way to create checkpoints you can go back to if something goes wrong.
The repo also has a file called ReportProjI.ipynb. This is a Jupyter Notebook which you can open by running JupyterLab or Jupyter Notebook from Anaconda. In it, you will find the definitions and details of the specific simulations you have to run. It also contains questions that you need to answer and figures you need to plot. Create a separate run script for each one of the sections in the notebook (run_harmonic.py and run_Ar.py), run the simulations, and answer the questions. Submit your report by commiting and pushing the file to your repo.