Document changes in the README

README.md

@@ -11,22 +11,22 @@ Solver for reaction-diffusion systems in multiple compartments
  * Neumann flux at the interface of compartments for variables with
    the same name on the two compartments
  * Easy to modify configuration file
- * Initial conditions might be either TIFF file or a math expression.
- * Solved using the finite element method
+ * Initial conditions can be a TIFF file or a math expression
+ * Solved using the finite element or finite volume method
  * Output in the VTK format
  * Currently it only supports 2D simulations
 
-This project is made under the umbrella of the 
+This project is made under the umbrella of the
 [*Distributed and Unified Numerics Environment* `DUNE`](https://www.dune-project.org/) and the
-[*Biochemical System Simulator* `COPASI`](http://copasi.org/). 
-Altought the rationale of the design is always driven by biochemical process (e.g. cell biology), 
+[*Biochemical System Simulator* `COPASI`](http://copasi.org/).
+Altought the rationale of the design is always driven by biochemical process (e.g. cell biology),
 this software is not limited to this scope and can be used for other processes involving reaction-diffusion systems.
 
-## Graphical User Interface for SMBL files
+## Graphical User Interface for SBML files
 
-For those working in bio-informatics there exist a grafical user interface for SMBL files!
-The GUI is able to convert non-spatial SBML models of bio-chemical reactions into 
-2d spatial models, and to simulate them with `dune-copasi`.
+For those working in bio-informatics there exist a grafical user interface for [`SBML`](https://en.wikipedia.org/wiki/SBML) files!
+The GUI is able to convert non-spatial SBML models of bio-chemical reactions into
+2D spatial models, and to simulate them with `dune-copasi`:
 
 https://github.com/lkeegan/spatial-model-editor
 
@@ -37,7 +37,7 @@ This requires that you have installed the following packages before the actual i
 | Software | Version/Branch | Comments |
 | ---------| -------------- | -------- |
 | [CMake](https://cmake.org/) | 3.1 |
-| C++ compiler | [C++17](https://en.wikipedia.org/wiki/List_of_compilers#C++_compilers) | 
+| C++ compiler | [C++17](https://en.wikipedia.org/wiki/List_of_compilers#C++_compilers) |
 | [libTIFF](http://www.libtiff.org/) | 3.6.1 |
 | [muParser](https://beltoforion.de/article.php?a=muparser) | 2.2.5 |
 | [dune-common](https://gitlab.dune-project.org/copasi/dune-common) | releases/2.7 | https://gitlab.dune-project.org/core/dune-common
@@ -65,7 +65,7 @@ brew update
 brew install cmake gcc libtiff muparser git
 ```
 
-Now, the dune modules (including `dune-copasi`) can be all checkout in a same folder and be installed in one go. 
+Now, the dune modules (including `dune-copasi`) can be all checkout in a same folder and be installed in one go.
 
 ```bash
 # prepare a folder to download and build dune modules
@@ -99,22 +99,22 @@ git clone -b master https://gitlab.dune-project.org/copasi/dune-copasi
 cd .. && rm -r ~/dune-modules
 ```
 
-For further info on dune module installation process, please check out 
+For further info on dune module installation process, please check out
 the [dune-project web page](https://www.dune-project.org/doc/installation/)
 
-## Usage 
+## Usage
 
 If you installed `dune-copasi` system-wide, you should be able to call the program
-`dune_copasi` from your command line accompained with a configuration file.
+`dune_copasi_md` from your command line accompained with a configuration file.
 
 ```bash
-dune_copasi config.ini
+dune_copasi_md config.ini
 ```
 
 ### Configuration File
 
 The configuration file follows [INI file format](https://en.wikipedia.org/wiki/INI_file).
-It should contain at least two sections: `grid`, and `model`, whereas a third section 
+It should contain at least two sections: `grid`, and `model`, whereas a third section
 `logging` is optional.
 
 #### Grid
@@ -128,10 +128,19 @@ file = my_gmsh_file.msh
 initial_level = 1
 ```
 
+The grid should be formed by 2D traingles and squares where each *physical group* can only
+only be formed by one of these type. That is, each *physical group* can have different types of
+geometries, but whithin each *physical group* there cannot be more than one type. The GMSH file
+should be v2 and it should not contain the *physical group* identifiers at the begining of the file
+(this is a bug in the `dune-grid` reader).
+
 #### Model
 
-The model section starts with the definitions of the simulation time interval 
-and the polynomal order of the finite element method (currently only supports `1` and `2`).
+The model section starts with the definitions of the simulation time interval
+and the polynomal order of the local finite element (currently only supports `0`, `1` and `2`),
+where `0` refers for finite volume and higher for continuous galerking methods. This order refers
+to the domains composed with triangles. Domains compose with squares are always solved with the
+finite volume method.
 
 ```ini
 [model]
@@ -141,13 +150,13 @@ time_step = 0.1
 order = 1
 ```
 
-The following is the definition of the compartments of the model. 
+The following is the definition of the compartments of the model.
 Each compartment corresponds to a *physical group* in the gmsh jargon.
-Although the gmsh format allows you to name such physical groups, 
+Although the gmsh format allows you to name such physical groups,
 we still need to assign them to a `dune-copasi` compartmet and for that
-we use the *physical group* index. Notice that uses 0-based indices while 
-`gmsh` uses 1-based indices. In other words, 
-`<gmsh_physical_group> = <dune_copasi_compartment> - 1`. 
+we use the *physical group* index. Notice that `dune-copasi` uses 0-based
+ indices while `gmsh` uses 1-based indices. In other words,
+`<gmsh_physical_group> = <dune_copasi_compartment> + 1`.
 Let's say for example that there is two *physical groups* in our gmsh file
 and we are going to use them as `nucleous` and `cytoplasm` compartments:
 
@@ -162,25 +171,25 @@ cytoplasm = 0
 Now, each of these compartments will define its own initial conditions,
 its diffusion-reaction system, and its vtk writter. For that, you have to expand
 the `model` section with the defined compartments, e.g. `model.nucleous` or `model.cytoplasm`.
-The subsection `initial`, `reaction`, `diffusion` and `operator` define the system variables 
-and its properties. You can put as many variables as desired as long as they are the same 
-in this three subsections. Notice that each variable defines a new diffusion-reaction partial 
-differential equation associated with it. 
+The subsection `initial`, `reaction`, `diffusion` and `operator` define the system variables
+and its properties. You can put as many variables as desired as long as they are the same
+in this three subsections. Notice that each variable defines a new diffusion-reaction partial
+differential equation associated with it.
 
-  * The `initial` subsection allow the initialization of each of the variables. 
-  * The `diffusion` subsection defines the diffusion coefficient math 
+  * The `initial` subsection allow the initialization of each of the variables.
+  * The `diffusion` subsection defines the diffusion coefficient math
   expression associated with each variable. It may only depend on the grid coordinates `x` and `y`.
-  * The `reaction` subsection defines the reaction part of each equation in the PDE. 
+  * The `reaction` subsection defines the reaction part of each equation in the PDE.
   Since this is the souce of non-linearities, it allows to be dependent on other defined variables
   within the compartment. This section has to include yet another subsection called `jacobian`.
-  * The `reaction.jacobian` subsection must describe the 
+  * The `reaction.jacobian` subsection must describe the
   [jacobian matrix](https://en.wikipedia.org/wiki/Jacobian_matrix_and_determinant)
-  of the `reaction` part. It must follow the syntax of `d<var_i>_d<var_j>`, which 
-  reads as the *partial derivate of `<var_i>` with respect to `<var_j>`*. 
-  * The `operator` subsection is an experimental feature and we recommend to set all variables to the 
-  same index, e.g. 0. 
-  * Finally, the subsection `writer` will define the file name for the vtk output. 
-  
+  of the `reaction` part. It must follow the syntax of `d<var_i>_d<var_j>`, which
+  reads as the *partial derivate of `<var_i>` with respect to `<var_j>`*.
+  * The `operator` subsection is an experimental feature and we recommend to set all variables to the
+  same index, e.g. 0.
+  * Finally, the subsection `writer` will define the file name for the vtk output.
+
 For example, the following `mode.nucleous` section defines a [Gray-Scott
 model with `F=0.0420` and `k=0.0610`](http://mrob.com/pub/comp/xmorphia/F420/F420-k610.html):
 
@@ -210,15 +219,15 @@ v = 0
 [model.nucleous.writer]
 file_name = nucleous_output
 ```
-The `model.cytoplasm` would have to be defined in similar way. An important aspect when working 
-with different compartments is the interface fluxes. In `dune-copasi` thex fluxes are set 
+The `model.cytoplasm` would have to be defined in similar way. An important aspect when working
+with different compartments is the interface fluxes. In `dune-copasi` thex fluxes are set
 automatically to [dirichlet-dirichlet](https://en.wikipedia.org/wiki/Dirichlet_boundary_condition)
-boundary conditions iff the variable is shared between the two intersecting domains. Further 
+boundary conditions iff the variable is shared between the two intersecting domains. Further
 improvements will come for interface treatment.
 
 #### Logging
 
-The logging settings are directly forwarded to the `dune-logging` module. Please check 
+The logging settings are directly forwarded to the `dune-logging` module. Please check
 its doxygen documentation for detailed information. A simple configuration is the following:
 
 ```ini