This folder contains data and code which can be used to recreate results from the paper 
"Can root systems redistribute soil water to mitigate the effects of drought".
Written and created by Andrew Mair (adm13@hw.ac.uk).

A - Code Contents:
   Apart from the last item, these are all found within the first level of the file structure within the DOI folder.
1. "data_converter_and_individual_mesh_generator.py"
   A FEniCS script that converts the root system data from CRootBox into a 
   format that allows the creation of density functions and flow-anisotropy matrices.
   It also creates a finite element-mesh of the domain defined by the extremal points
   of the root system.
2. "global_mesh_generator.py"
   A FEniCS script that builds a mesh of a soil domain into which all the 
   root systems studied in the paper can fit.
3. "density_and_matrix_constructor.py"
   A FEniCS script for constructing the density functions and flow-anisotropy
   matrix that correspond to a particular root system.
4. "benchmark_simulator.py"
   A FEniCS script for simulating presure head profiles from the benchmark model.			 	
5. "model_calibrator.py"
   A FEniCS script that runs a Bayesian optimisation scheme to estimate the
   facilitation constant value with which to parametrise the model in the paper
   so that numerical pressure head profiles most accurately match those of the benchmark
   model.
6. "model_simulator.py"
   A FEniCS script that generates numerical solutions to the model from the paper
   in order to gather data on the impact of preferential flow strength, and contrasting
   root architectural traits on soil water lifetime and root water uptake.
7. "post_processor.py"
   A Python script that uses the data from simulations to reproduce the results in Figures
   2b, 2c, 3, 5 and Table 1 from the paper. This code can be run without having FEniCS 
   installed, so you should go straight here if all you want to do is reproduce the results.
8. 18 Matlab scripts used to obtain the images in Figures 2a, 4a, 4b and 4c.
   These are within the "data" folder in the DOI since they need to be on the same file level
   as the data they call.
   The script "text_to_graphic" was developed as part of this work, but the other 17 
   were developed by L.Dupuy, T.Fourcaud, A.Stokes and F.Danjon in the 2005 work 
   "A density-based approach for the modelling of root architecture: application to maritime pine
   (pinus pinaster ait.) root systems" published in the Journal of Theoretical Biology 236(6), 323-334.
 
B - Data Contents:
   All found within the "data" folder of the DOI folder.
1. xml.gz files: 
	Files for the finite element meshes defined over the global soil domain and also
        the soil domains defined by the extremal points of each studied root system.
2. H5 files: 
	Files involved in storing data for density functions, flow-anisotropy matrices
        and solution profiles, so that they can be read into finite element scripts
        or visualised in Paraview.
3. .txt files:
	subset 1: Files containing root system data. These include the direct output from CRootBox
                  for a given root system, the converted version of the CRootBox data, the biomass
                  of a given root system, the dimensions of the soil domain occupied by a root system.
	
        subset 2: Files containing data on (a) laterally averaged pressure head profiles from the benchmark model
                  (b) the output of the calibration scheme (optimum value identified, observation points, 
                  cost function evaluations, laterally averaged profile from the calibrated model), 
                  (c) the results on water losses and uptake from simulating the model in the paper 
                  (File name guidance: ev-evaporation, fd-free drainage, ro-runoff, up-uptake).
4 .XDMF files:
	Data for visualising root density functions and simulations from the calibrated model for
        different root systems. This requires the Paraview software 
        (File name guidance: h-pressure head, theta-water content, q-water flux, len-root length density,
                             nlen-normalised root length density, vol-volumetric root density.	
   
C - Implementation Instructions:
1. One .txt file for guidance on FEniCS setup
2. One .txt file describing the required implementation procedure of the codes above, in order to obtain the results of the paper.