Automatic-interpolations.md

-**VERSION>22.02.2021**
+**VERSION>=22.02.2021**
+# Introduction
+The number of self-consistent iterations till convergence strongly depends on the quality of starting point: the closer the initial state to the solution - the fewer iterations to converge. W-SLDA Toolkit implements a mechanism supporting the derivation of good quality initial states. Namely, one can use lattice of lower resolution to generate an approximation of the solution and next interpolate to larger/target lattice and use it as starting point. The idea is presented on the figure below. The same mechanism can be used for testing the stability of results with respect to the lattice resolution. 
 
-The number of self-consistent iterations till convergence strongly depends on the quality of starting point: the closer the initial state to the solution - the fewer iterations to converge. **TODO**
+![automatic-interpolation](uploads/d24e5124cfc0bd36df87937f9ac3d3c8/automatic-interpolation.png)
 
-![automatic-interpolation](uploads/d24e5124cfc0bd36df87937f9ac3d3c8/automatic-interpolation.png)
\ No newline at end of file
+# Automatic interpolations
+_Step 1_: Generate solution with initial lattice. For example:  
+`predefines.h`
+```c
+/**
+ * Define lattice size and lattice spacing
+ * */
+#define NX 32
+#define NY 32
+#define NZ 32
+
+#define DX (32./NX)
+#define DY (32./NY)
+#define DZ (32./NZ)
+```  
+`input.txt`
+```bash
+outprefix               l-32    
+checkpoint              1       # do checkpoints after each iteration
+```
+
+_Step 2_: Run the code compiled for the lattice with larger resolution:  
+`predefines.h`
+```c
+/**
+ * Define lattice size and lattice spacing
+ * */
+#define NX 40
+#define NY 40
+#define NZ 40
+
+#define DX (32./NX)
+#define DY (32./NY)
+#define DZ (32./NZ)
+```  
+`input.txt`
+```bash
+inittype                5       # 5 - start from st-wslda checkpoint, inprefix points to folder with checkpoint binary file
+outprefix               l-40    
+inprefix                l-32    # start with solution from smaller lattice 
+checkpoint              1       # do checkpoints after each iteration
+```
+
+Once running the code you should see  this type of message on `stdout`:
+```
+# INSPECTING CHECKPOINT FILE `l-32/checkpoint.dat`
+# CHECKPOINT FOR 3D LATTICE: [NX,NY,NZ]=[32,32,32], [DX,DY,DZ]=[1.000,1.000,1.000], [LX,LY,LZ]=[32.000,32.000,32.000]
+# !!! --- WARNING --- WARNING --- WARNING --- WARNING --- WARNING --- WARNING --- !!!
+#        Resolution of the lattice has changed!
+#        The code will interpolate given checkpoint data to the new resolution.
+# !!! --- ------- --- ------- --- ------- --- ------- --- ------- --- ------- --- !!!
+# LOADING CHECKPOINT FILE `l-32/checkpoint.dat`
+# CONVERTING CHECKPOINT WITH RESOLUTION [DX,DY,DZ]=[1.000,1.000,1.000] TO NEW RESOLUTION [0.800,0.800,0.800]
+```
+
+# Restrictions
+Automatic interpolations will be applied only if the spatial extent has not changed. It means that `[LX,LY,LZ]` is the same for input lattice and target lattice. If this criteria is not satisfied, the code will return error `WSLDA_ERR_INCOMPATIBLE_CHECKPOINT_FILE`. 
\ No newline at end of file