Basic-TDGL-Simulation.md

@@ -18,7 +18,7 @@ git pull
 ```
 This will move you to the folder where the code is located (note if you have this repository saved somewhere other than your home folder the path to it will need to be included), activate the conda environment which will allow python to know about the relevant software packages we need, and then pull any changes from the git that have been made by other users since the last time you worked on the code.
 
-There are two main scripts which will need to be changed in order to run a simulation, `runTests.py` (in the main folder) and `SolveProblem.py` (in the src folder). `runTests.py` is a script where we choose the relevant options for submitting the simulation as a job for the supercomputer, and input some of the parameters for solving, having these parameters at this step allows us to submit multiple jobs at once in cases where we want to run different combinations of solve parameters. There's a lot of options to toggle at the beginning, here's a walkthrough of what to do with each of them:
+There are two main scripts which will need to be changed in order to run a simulation, `runTests.py` (in the main folder) and `SolveProblem.py` (in the src folder). We will start with `runTests.py`. This a script where we choose the relevant options for submitting the simulation as a job for the supercomputer, and input some of the parameters for solving, having these parameters at this step allows us to submit multiple jobs at once in cases where we want to run different combinations of solve parameters. There's a lot of options to toggle at the beginning, here's a walkthrough of what to do with each of them:
 
 `fieldValues` - a list of what applied fields we wish to run at, we just want to run one simulation at Ha = 0.5, so just make sure this is set to `list(np.around(np.linspace(0.5,0.5,1),decimals=3))`
 
@@ -38,3 +38,59 @@ There are two main scripts which will need to be changed in order to run a simul
 
 `runPostProcessing` - Setting this to True will run the post processing script after the solving is completed. Set this to `False` for now
 
+`checkParamFileOveride`, `skipCompletedTest`, `makeParamFileOnly` - These options all deal with how to handle the json files that are created to pass the parameters to the next solving step. You can pretty much just set them to `True`, `False`,`False` respectively and then forget about them. 
+
+`mainTestFolder` - This is the folder where you want to save any outputs of your simulation, if the folder does not exist, it will create it, so simply put the location where you want things to be saved. We recommend you do NOT save things to any of the folders of this repository, the supercomputer has a place dedicated to saving large amounts of data, you should be able to save there using something like `/lustre/scratch/usr/[your_supercomputer_username]`. We recommend making yourself a file hierarchy there for saving data from your simulations. Note that by default your supercomputer home folder will have a symbolic link called 'compute' that will take you to the aforementioned directory.
+
+Now we just need to make sure some of the run parameters are right and then we are done with this file. See the actual script for some brief descriptions of what all of these things are but you should make sure the following lines are present under the 'Run Parameters' section header:
+```
+params["run_time"] = 10 
+params["time_step"] = 0.2 
+params["kappa"] = 4 
+params["u"] = 1 
+params["order"] = 1 
+params["periodic"] = True 
+```
+The only other thing to note is that under the 'Expression Parameters' section header you should make sure that `params['use_material_specific_expressions']` is set to False, you can otherwise ignore the rest of this script for now, it should all be set up!
+
+Now go and look at `SolveProblem.py`. We will start under the `Set Up Mesh` section header. As the name suggests, this is where we set up the mesh we will use for our problem. We are going to use one of the preset mesh options, `RectMesh`. To learn more about other mesh options, look at [Mesh Presets](Mesh Presets) and the MeshFactory section in [Base Classes](Base Classes). `RectMesh` creates a rectangular mesh for 2D or a rectangular cuboid mesh for 3D. We are going to run a 2D mesh, so we need to specify the range the rectangle covers in the x and y directions, as well as the number of mesh points along each direction, and whether or not the mesh is periodic. Put the following lines under the 'Set Up Mesh' header:
+```
+    periodic = params["periodic"]
+    xmin = -2.5
+    xmax = 2.5
+    ymin = -5.0
+    ymax = 0.0
+    mesh_factory = RectMesh([[xmin,xmax],[ymin,ymax]], [50,50], periodic = periodic)
+    params["mesh_width"] = xmax - xmin
+```
+This will create a 5x5 rectangular mesh with 2500 evenly spaced points. Note that the final line is necessary since the problem needs the "mesh_width" parameter to set up periodic boundary conditions. 
+
+The next step is simply, under the 'Set Up Problem' banner, make sure that `problem` is assigned to `TDGL_2D(params, mesh_factory)` and you're done, all the parameters we have added and the mesh we just set up will be loaded into the TDGL_2D object. 
+
+Now go to the 'Attach Observers' header. Here we just need to pick what observers we want to act on our problem. Let's save the solution data, and also plot the square of the order parameter. To do this, make sure the following is under the 'Attach Observers' header:
+```
+observers = [
+    DataSaver(problem, params),
+    PlotFsqr(problem, params)
+    ]
+```
+We now need to make sure these observers have access to the proper parameters, look at the 'Observer Parameters' header just above. Make sure the following are present in this section:
+```
+params["save_every"] = 1
+params["figure_save_location"] = params["save_location"] + "figs/"
+params["video_save_location"] = params["save_location"]
+params["dpi"] = 300
+```
+This will make the observers save/plot every time step (you could set "save_every" to 2 to save every other time step for example), give the plotting observer the location to save figures to, as well as a location to save the video to, and also what the dpi of the pictures it saves should be.
+
+If you have completed all these steps, you're done setting everything up, all that's left is to run the code. Go to the ssh terminal you use to connect to the supercomputer and run:
+```
+python3 runTests.py
+```
+If everything was done correctly, the simulation will run for a few minutes and then you can go to the folder where you saved everything and look for the video of the order parameter, the data saved to the .hdf5 format, and some outputs from the various print statements that occurred during solving.
+
+Congratulations! You have successfully ran your first TDGL simulation. The process may have seemed rather long and tedious for such a basic result, but many of the options we looked at here do not need to be changed very much at all. For example, go back to `runTests.py` and change `fieldValues` to be 0.9 instead of 0.5 and run the code again, and you'll see we now get vortex entry in our simulation, and making changes to the simulation like that are very quick and simple. This code was designed with the idea in mind that all the components of it should be easy to swap in and out without needing to change anything (or at least not very much) at other places in the code. If you want a different mesh, just go swap out the code in the "Set Up Mesh" section, if you want different observers, just go put in different observers in the "Attach Observers" section and then go make sure the relevant observer parameters are in the "Observer Parameters" section. 
+
+This concludes the Basic TDGL Simulation tutorial, we hope you have found it useful. There's still plenty of features in the code not covered here, this wiki should be relatively well documented at least as far as completed features are concerned, so feel free to browse it to see what our code has to offer, though we recommend playing with the code yourself and using it more as reference material.
+
+*This tutorial was last updated as of 8/26/2021, if some of it seems outdated by the time you are reading this, talk to a more senior group member about getting it updated, as well as having them explain what parts of this may be outdated now.*