Merge pull request #17 from samwaseda/copy_files

Copy files that I created for joss

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing to mamonca
+
+Welcome to mamonca! We appreciate your interest in contributing.
+
+## How to Contribute
+
+1. Fork the repository to your GitHub account.
+2. Clone the forked repository to your local machine:
+
+   ```bash
+   git clone https://github.com/samwaseda/mamonca.git
+   ```
+
+Feel free to submit any changes.

README.md

@@ -26,7 +26,7 @@ python setup.py build_ext --user
 
 ## First steps:
 
-In the following simple (but complete) example, we create a bcc Fe system using [pyiron](http://github.com/pyiron/pyiron) and launch a Metropolis Monte Carlo simulation with a Heisenberg coefficient `J=0.1` (eV) for the first nearest neighbor pairs:
+In the following simple (but complete) example, we create a bcc Fe system using [pyiron](http://github.com/pyiron/pyiron) (install via `conda install pyiron`) and launch a Metropolis Monte Carlo simulation with a Heisenberg coefficient `J=0.1` (eV) for the first nearest neighbor pairs:
 
 ```python
 from pyiron_atomistics import Project
@@ -49,10 +49,13 @@ mc.set_heisenberg_coeff(J * first_shell_tensor)
 mc.run(temperature=300, number_of_iterations=1000)
 ```
 
+More complete list of examples can be found in `notebooks/first_steps.ipynb`
+
 ## How to set inputs and get outputs
 
-As a rule of thumb, you can set all input parameters via functions starting with `set_`. Similarly, output values can be obtained via functions whose names start with `get_`. Most notably, you can get all basic output via `get_output()` in a dictionary. Take a look at the list of auto-complete and see their docstrings
+As a rule of thumb, you can set all input parameters via functions starting with `set_`. Similarly, output values can be obtained via functions whose names start with `get_`. Most notably, you can get all basic output values via `get_output()` in a dictionary. Otherwise, take a look at the list of auto-complete and see their docstrings
 
 ## Notes
 
 - Currently only Linux installation is supported
+- You can run tests located in the `tests` folder

mamonca/cMC.cpp

@@ -527,26 +527,30 @@ void cMC::run_mc(double kBT){
         id_rand = selectable_id.at(rand()%selectable_id.size());
         atom[id_rand].propose_new_state();
         double dEE = atom[id_rand].dE();
+        // Append metadynamics energy if defined
         if (meta.initialized)
             dEE += meta.get_biased_energy(
                 m_norm(magnetization+atom[id_rand].delta_m()/(double)n_tot),
                 sqrt((magnetization*magnetization).sum()));
+        // Suggest a new state
         update_magnetization(id_rand);
         if(thermodynamic_integration())
             dEE = (1-lambda)*dEE+lambda*atom[id_rand].dE(1);
-        if(metropolis(kBT, dEE))
+        // Metropolis step
+        if(metropolis(kBT, dEE)) // Accepted
         {
-            acc++;
+            acc++; // Acceptance ratio
             dEE_tot.at(0) += atom[id_rand].dE();
             if(thermodynamic_integration())
                 dEE_tot.at(1) += atom[id_rand].dE(1);
         }
-        else
+        else /* Rejected */
         {
             update_magnetization(id_rand, true);
             atom[id_rand].revoke();
         }
     }
+    // Energy consistency only for debugging
     for(int i=0; debug_mode && i<2; i++)
     {
         EE_tot[i] += get_energy(i);

mamonca/cMC.h

@@ -42,8 +42,13 @@ struct Magnitude;;
 
 class Atom{
     private:
+        /* Some variables have two values for the two potentials of the      */
+        /* thermodynamic integration. When thermodynamic integration is not  */
+        /* activated, only the first value is used.                          */
         double mabs, mabs_tmp, E_current[2], dE_current[2], dm, dphi, mmax;
         valarray<double> gradient;
+        /* Heisenberg coefficients (i.e. pairwise interactions) and Landau   */
+        /* coefficients (i.e. on-site coefficients)                          */
         vector<double> heisen_coeff[2], landau_coeff[2];
         vector<Magnitude*> landau_func[2];
         vector<Product*> heisen_func[2];
@@ -78,8 +83,13 @@ class Atom{
         void clear_heisenberg_coeff(int);
         void activate_debug();
         void propose_new_state();
+        /* This is the function that defines the maximum magnitude of the    */
+        /* magnetic moment length and the angle change at each step. These   */
+        /* values should be adjusted to have a good acceptance ratio (around */
+        /* 0.33?)                                                            */
         void rescale_magnitude(double, double);
         void set_magnitude(double, double, bool flip_in=true);
+        // Consistency check only in the debugging mode
         void check_consistency();
 };