Basic-TDGL-Simulation.md

+[Home](Home)
+# Tutorial 1 - Basic TDGL Simulation
+
+Hello, welcome to the tutorial for the Transtrum group's TDGL code! If you are using this, in all likelihood you are either a new member to the group, or a collaborator making use of our code. The goal of this tutorial is to get you started with some basic TDGL simulations, and to familiarize you with some of the most commonly used features of the code. If you haven't done so already, make sure you set up your supercomputer account and download all the code, instructions for doing so can be found in the readme on the front page of the repository. This tutorial will assume you already have some knowledge of coding in python, and have at least a basic idea of how to use FEniCS to solve finite element problems. If you know little to nothing about how FEniCS works, we recommend you read through chapters 1 and 2 of the [FEniCS tutorial](https://fenicsproject.org/pub/tutorial/pdf/fenics-tutorial-vol1.pdf). Pay attention primarily to the basic ideas of how the solving process works, as our software is built on top of FEniCS functionalities. This tutorial as well as the documentation in general is primarily focused on how to use the actual code and enumerating what capabilities it has, for the science behind it, you should go look at the wiki on the Microsoft Teams page, or consult other group members for useful reading materials.
+
+## How the Code Works
+
+The core design pattern behind our code is called Subject-Observer. The basic idea of this pattern is that you have a class called a subject, which performs various tasks, and observers which 'observe' the subject and periodically perform tasks based on what the subject does. If you would like to learn more you can read more about it on page 293 in [this book](https://search.lib.byu.edu/byu/search?q=Design%20Patterns:%20Elements%20of%20Reusable%20Object-Oriented%20Software) (if you have a BYU login you can access a free online copy). In the case of our code, we call our subjects "problems" as they are what actually have all the equations, solutions, meshes, boundary conditions, etc. which are necessary to solve a finite element problem. Our observers can do things like saving data, plotting solutions, printing useful info, etc. The basic workflow is that once you have set everything up, the problem will solve the equations it has been given, then call `update()` on all it's observers which will go and do their saving and plotting and such. Once all the time steps have been completed, `problem.finish_run()` is called and the observers will do whatever they need to finish up their tasks (for example, the data saving observer will close the file that it's saving to). 
+
+For this first tutorial, we will cover how to simply run a basic TDGL simulation, to learn how to add new features to the code you should read the [Adding Features](Adding Features) tutorial.
+
+## Running Your First Simulation
+Okay, we are done with all the exposition now, thanks for bearing with us, now for some practical coding. Whenever you boot up the supercomputer to run some code there's a few lines of code you should run every time:
+```
+cd tdgl-refactored
+source loadFEniCS.sh
+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:
+
+`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))`
+
+`variableParams1`/`variableParams2` - These let you vary other parameters if you want to. We don't, so make sure they are both `[0]`
+
+`memoryPerRun` - The memory on each core the supercomputer is given for each job, given in Mb, enter `'2000'` to give each core 2 gigs of ram
+
+`timePerRun` - The maximum time each job is allowed to run for, formatted like "HH:MM:SS", enter `'00:30:00'` to run for 30 minutes. If the job is still running after this time has passed, it will terminate the job. 
+
+`numCores` - The number of cores we want to run with, enter `4` to use four cores.
+
+`numNodes` - Each node on the supercomputer has 24 cores (or 48 in the case of our group's dedicated nodes), this will normally be set to `1`, as it will be in this case, but if you want more cores than exist on one node, you should choose the proper number of nodes to accommodate the cores you want.
+
+`qosQueue` - Setting this to True will make use of the testing queue, which is meant for jobs which will take under an hour, in our case we will set it to `True` as our simulation will not take more than a few minutes. 
+
+`qosmkt24` - Setting this to True will use our group's dedicated nodes, we have priority for using them, so they are good for running large jobs which may take time to be submitted to the general queues, just coordinate with other group members so we aren't competing for use of these nodes. For this tutorial set it to `False`
+
+`runPostProcessing` - Setting this to True will run the post processing script after the solving is completed. Set this to `False` for now
+