first commit

README.md

@@ -0,0 +1,76 @@
+## M-SPARC Usage  
+### (1) Brief:  
+Matlab-Simulation Package for Ab-initio Real-space Calculations (M-SPARC) is a real-space code for performing electronic structure calculations based on Kohn-Sham Density Functional Theory (DFT). Its primary purpose is the rapid development and testing of new algorithms and methods within DFT. The main features of M-SPARC 1.0 include  
+
+* Boundary conditions for crystals, surfaces, wires, and molecules.  
+* Calculation of ground state energy, atomic forces, and stress tensor.  
+* Unconstrained collinear magnetization via spin polarized calculations.  
+* Structural relaxation and molecular dynamics (MD).  
+* LDA and GGA exchange correlation functionals.  
+* ONCV and TM pseudopotentials in psp8 (ABINIT) format.  
+
+### (2) Input files:  
+The required input files to run a simulation with M-SPARC are (with shared names)  
+(a) ".inpt" -- User options and parameters.  
+(b) ".ion"  -- Atomic information.  
+A more detailed description of the input options can be found in the user manual loated in M-SPARC/docs. Examples of input files can be found in the directory M-SPARC/tests. In addition, M-SPARC requires pseudopotential files of psp8 format which can be generated by D. R. Hamann's open-source pseudopotential code [ONCVPSP](http://www.mat-simresearch.com/). Pseudopotential files are specified in the ".ion" file.  
+
+### (3) Execution:  
+M-SPARC can be executed in matlab by calling the `msparc` function (which is located under src/ directory). It is required that the ".inpt" and ".ion" files are located in the same directory and share the same name. For example, to run a simulation with input files as "filename.inpt" and "filename.ion" in the src/ directory, use the following command:  
+```
+S = msparc('filename');
+```
+In many cases, we would not want to put the input files inside the src/ directory. In such cases, we need to provide the path to the input file name, without any extension. As an example, one can run a test located in M-SPARC/tests/MeshConvergence as follows. First go to src/ directory. Run a DC silicon system with mesh = 0.4 bohr by:  
+
+```
+S = msparc('../tests/MeshConvergence/Si8-ONCV-0.4');
+```
+The result is printed to an output file named "Si8-ONCV-0.4.out", located in the same directory as the input files. If the file "Si8-ONCV-0.4.out" is already present, the result will be printed to "Si8-ONCV-0.4.out_1" instead. The max number of ".out" files allowed with the same name is 100. Once this number is reached, the result will instead overwrite the "Si8-ONCV-0.4.out" file. One can compare the result with the reference out file named "Si8-ONCV-0.4.refout".  
+
+In the examples/ directory, we also provide a sample script file `run_examples.m`, which launches four example tests one by one. To run these examples, simply change directory to examples/ directory, and run 
+```
+run_examples
+```
+Note that in this case, we're trying to call the `msparc` function from a different directory. This is achieved by using the MATLAB function `addpath` to add the src/ directory to search path.
+
+One can also run M-SPARC using the MATLAB parallel pool to parallelize over k-points and spin by providing a second argument, `parallel_switch`, when running M-SPARC:  
+```
+S = msparc('filename',parallel_switch);
+```
+If `parallel_switch = 1`, M-SPARC will start using the parallel pool, and if `parallel_switch = 0`, M-SPARC will not use the parallel pool, which is the default. Only turn on parallel pool if k-points or spin are present.
+
+### (4) Output:
+
+Upon successful execution of the  
+```
+S = msparc(fname);
+```
+command, an output structure is returned and stored in `S`. The structure `S` contains detailed information that can be useful for post-processing and debugging. Information such as the input parameters, densities, wavefunctions, eigenvalues, and all electronic ground-state properties calculated are stored in the output structure.
+
+Apart from the output structure returned, depending on the calculations performed, some output files will be created in the same location as the input files too. 
+
+**Single point calculations**
+
+- `.out` file  
+The `.out` file contains general information about the test, including input parameters, SCF convergence progress, ground state properties and timing information.
+- `.static` file  
+The `.static` file contains the atomic positions and atomic forces if the user chooses to print these information.
+
+**Structrual relaxation calculations**
+- `.out` file  
+See above.
+- `.geopt` file  
+The `.geopt` file contains the atomic positions and atomic forces for each relaxation step. This file is created only when the unit cell is fixed. For cell relaxation a `.cellopt` file is created instead.
+- `.cellopt` file  
+The `.cellopt` file contains the cell information (lattice vectors, cell lengths, volume) and stresses for each relaxation step. Only created for cell relaxation.
+- `.restart` file  
+The `.restart` file contains information necessary to perform a restarted structural relaxation calculation. 
+
+**Molecular dynamics (MD) calculations**
+
+- `.out` file  
+See above.
+- `.aimd` file  
+The `.aimd` file contains the atomic positions, atomic velocities, atomic forces, electronic temperature, ionic temperature and total energy for each MD step.
+- `.restart` file  
+The `.restart` file contains information necessary to perform a restarted MD calculation.