add MAIN to README and continue explaining code

LDDsimulation/README.md

-# The
+# The LDDsimulation Code
 
 This folder contains the actual LDD simulation code. To facilitate development,
 we give a briefe description of the files.
 
 ## `LDDsimulation.py`
+
+##

Usecases/README.md

@@ -26,6 +26,30 @@ simulation datat based on the older scripts have been used.
 If you want to revive some of these examples, copy one of the official examples
 and update that copy with information in the obsolete scripts.
 >>>
+
+## How to run a simulation
+
+In each usecase folder you should see a script `run_simulation` wich takes one
+mandatory and one optional parameter. Say we want to run the script
+`./Two-Phase-Richards/two-patch/TP-R-two-patch-test-case/TP-R-2-patch-realistic.py`
+we would start the `LDD-TPR` docker container (see `../Setup`), navigate into
+the directory
+~~~bash
+cd ~/share/Two-Phase-Richards/two-patch/TP-R-two-patch-test-case/
+~~~
+and then run the simulation by issuing
+~~~bash
+./run_simulation TP-R-2-patch-realistic.py
+~~~
+This will run the simulation and save the output of `stdout` in a logfile called
+`TP-R-2-patch-realistic.log`. Optionally, you can specify the name of the logfile
+like so
+~~~bash
+./run_simulation TP-R-2-patch-realistic.py <my-fancy-log-file-name>
+~~~
+This will run the simulation and save the output of `stdout` to a file named
+`my-fancy-log-file-name`.
+
 ## How to create your own usecases
 
 In order to create a new usecase, either modify one of the existing ones, or
@@ -470,4 +494,106 @@ dirichletBC = hlp.generate_exact_DirichletBC(
 ~~~
 This block defines the boundary condition from the exact solution expression.
 Again, if no exact solution is assumed, `dirichletBC` needs to be specified
-manually, similar as explained above. 
+manually, similar as explained above.
+
+## LOG FILE OUTPUT
+~~~python
+# LOG FILE OUTPUT #############################################################
+# read this file and print it to std out. This way the simulation can produce a
+# log file with ./TP-R-layered_soil.py | tee simulation.log
+f = open(thisfile, 'r')
+print(f.read())
+f.close()
+~~~
+This block does not need to be touched by the developer. It reads in the file
+given in the `thisfile` variable, which is supposed to be the very simulation
+file itself and prints it to `stdout`. When the simulation file is run at the
+aid of one of the `run_simulation` script, this output gets piped into a logfile
+for later reference. It is not beatiful, bit it works.
+
+## MAIN
+The main most likely will not have to be changed to run a new usecase unless
+you want to change something in the parallelisation or add new parameters.
+
+This function saves all the parameters into a dictionary `simulation_parameters`
+and then passes that to the helper function `hlp.run_simulation(**kwrgs)`,
+see `../LDDsimulation/helpers.py`, which in turn sets up the simulation object
+and runs the simulation.
+In case a mesh study is run the script `  hlp.merge_spacetime_errornorms(**kwrgs)`
+is run to merge the space time error norms for each mesh size, that have been
+saved in seperate files to allow parallel processing of the different mesh sizes. 
+~~~python
+# MAIN ########################################################################
+if __name__ == '__main__':
+    # dictionary of simualation parameters to pass to the run function.
+    # mesh_resolution and starttime are excluded, as they get passed explicitly
+    # to achieve parallelisation in these parameters in these parameters for
+    # mesh studies etc.
+    simulation_parameter = {
+        "tol": 1E-14,
+        "debugflag": debugflag,
+        "max_iter_num": max_iter_num,
+        "FEM_Lagrange_degree": FEM_Lagrange_degree,
+        "mesh_study": mesh_study,
+        "use_case": use_case,
+        "output_string": output_string,
+        "subdomain_def_points": subdomain_def_points,
+        "isRichards": isRichards,
+        "interface_def_points": interface_def_points,
+        "outer_boundary_def_points": outer_boundary_def_points,
+        "adjacent_subdomains": adjacent_subdomains,
+        # "mesh_resolution": mesh_resolution,
+        "viscosity": viscosity,
+        "porosity": porosity,
+        "L": L,
+        "lambda_param": lambda_param,
+        "relative_permeability": relative_permeability,
+        "intrinsic_permeability": intrinsic_permeability,
+        "sat_pressure_relationship": sat_pressure_relationship,
+        # "starttime": starttime,
+        "number_of_timesteps": number_of_timesteps,
+        "number_of_timesteps_to_analyse": number_of_timesteps_to_analyse,
+        "plot_timestep_every": plot_timestep_every,
+        "timestep_size": timestep_size,
+        "source_expression": source_expression,
+        "initial_condition": initial_condition,
+        "dirichletBC": dirichletBC,
+        "exact_solution": exact_solution,
+        "densities": densities,
+        "include_gravity": include_gravity,
+        "gravity_acceleration": gravity_acceleration,
+        "write_to_file": write_to_file,
+        "analyse_condition": analyse_condition
+    }
+    for number_shift, starttime in starttimes.items():
+        simulation_parameter.update(
+            {"starttime_timestep_number_shift": number_shift}
+        )
+        for mesh_resolution, solver_tol in resolutions.items():
+            simulation_parameter.update({"solver_tol": solver_tol})
+            hlp.info(simulation_parameter["use_case"])
+            processQueue = mp.Queue()
+            LDDsim = mp.Process(
+                        target=hlp.run_simulation,
+                        args=(
+                            simulation_parameter,
+                            processQueue,
+                            starttime,
+                            mesh_resolution
+                            )
+                        )
+            LDDsim.start()
+            # LDDsim.join()
+            # hlp.run_simulation(
+            #     mesh_resolution=mesh_resolution,
+            #     starttime=starttime,
+            #     parameter=simulation_parameter
+            #     )
+
+        LDDsim.join()
+        if mesh_study:
+            simulation_output_dir = processQueue.get()
+            hlp.merge_spacetime_errornorms(isRichards=isRichards,
+                                           resolutions=resolutions,
+                                           output_dir=simulation_output_dir)
+~~~