# What can it do?
This Test Driver is used to test lattice invariance shear in a cubic crystal based on cb-kim code. It works together with Test. 

# How to create an input file?
You can define several input arguments, which will be transfered to test driver as input. All the input arguments must be defined in 'pipeline.stdin.tpl' file in Test directory. 

The input argument must be written line by line in the right order. The order is like the following:

(1)@< path("test driver name") >@ ! This argues the name of test dirver.

(2)@< MODELNAME >@ ! modelname, just leave it like this.

(3)Lattice type ! e.g. fcc, bcc, diamond, b2.

(4)Species      ! e.g. Cu, Si etc.

(5)Initial guess of lattice parameter ! This is just a initial guess of lattice parameter for your chosen lattice type and species. The code will calculate the real lattice parameter by lattice optimazition based on your input. Don't choose it bigger than the cutoff radius. Otherwise the code will return error.

(6)# of period of lattice invariance shear. ! The deformation gradient can be defined as F = I + gamma*s(*)n, where I is identity, gamma is shear parameter, s is shear direction vector, n is shear plane normal. (*) denotes tensor product. The shear parameter to make one period lattice parameter shear is different as you choose different shear direction and shear plane normal. Here, you need to enter how many period of lattice invariance shear you want to make. The code can calculate the shear parameter 'gamma' for you.

(7)shear direction vector s. 

(8)shear plane normal vector n. ! s and n must be perpendicular with each other. Otherwise, the code will return error.

(9)shuffle relaxation flag. ! You need to write either "nrlx", which means do not apply shuffle relaxation, or "relx", which means apply shuffle relaxation. For simple lattice such fcc, bcc, etc. You must write "nrlx" here. However, for multilattice, such as diamond, b2, you can choose either apply shuffle relaxation or not.

Please look at an example input file 'pipeline.stdin.tpl' in Test directory for more details.

# How to use it?
If you have install openkim-repository and 'cb-kim' code well, you can type the follow command anywhere in the terminal:
~ pipeline_runpair 'TEST DRIVER NAME' 'MODEL NAME'
e.g. ~ pipeline_runpair cb_kim__TD_747488889888 Three_Body_Stillinger_Weber_Si__MO_405512056662_001 

# How it works?
The engine of this test driver is cb-kim code. Given any deformation gradient, model, species, and lattice type. cb-kim code will calculate the cohesive energy, 1st P-K stress, and stiffness matrix for you. In this case, I separate any given deformation gradient into 100 sub-steps. For each sub-steps, we have the shear parameter and cohesive energy, such that we can generate a shear parameter vs cohesive energy plot.

cb-kim code need a input, which is 'cbkim.in' in result directory. What this test driver do is like the following:

(1)Read the input argument from 'pipeline.stdin.tpl', and feed the 'cbkim.in.template' in test driver direcotry, and generate a 'cbkim.in' for cb-kim code.

(2)Run cbkim.in in cb-kim code, and generate 'cbkim.out' file.

(3)Scan 'cbkim.out' file and feed 'results.edn.template' to generate 'results.edn' file, which is the output file of this test dirver. 

(4)All the files generated in processing will be copied to 'tr' directory, such as cbkim.in cbkim.out and some log files and checking files.

# What will it give us back?
As I mentioned before, all the output files will be copied to 'tr' directory. But the main output file is 'results.edn'. The 'results.edn' file is written in 'edn' format. It provides every properties mentioned in the propertie files of this test, which is "cohesive-energy-lattice-invariant-shear-unrelaxed-path-cubic-crystal" and "cohesive-energy-lattice-invariant-shear-path-cubic-crystal"

In the results file, the shear parameter is an array including 100 values, cohesive energy is also an array inclucing 100 values. We can use these to generate a shear parameter vs cohesive energy plot. If the cohesive energy in the end go back its initial value, that means the lattice reproduce. We can also see how the energy changes as the shear processing. For the points that have a sudden change of energy, that can be considered a phase transformation happening.

# How to play with the code?
If you want to make any modification of this test driver. You can modify the 'runner' in test driver directiory, which is written by python. For example, you can add species in the code, because my initial runner doesn't support all species. You can also modify the cb-kim.in.template, to change the # of sub-steps (my initial setting is 100 sub-steps, you can change it to any values you like).
But please keep in mind, if you make any change of the code, you probably need to modify the 'descriptor.kim' file in test directory.