diff --git a/LDDsimulation/README.md b/LDDsimulation/README.md
index 2a914909ddcbc1942fba91a5741436dbd14c76a0..680e6d0b0945bbac6c09914fb91ab1b99dc51961 100644
--- a/LDDsimulation/README.md
+++ b/LDDsimulation/README.md
@@ -1,6 +1,8 @@
-# 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`
+
+##
diff --git a/Usecases/README.md b/Usecases/README.md
index 56ea5802b40ba67f298892baed9b5b4d425021b1..22f600752027d8c8c4f250c29d2921958903c488 100644
--- a/Usecases/README.md
+++ b/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)
+~~~