README.md updated to match the new version

Author: ZocoLini

README.md

@@ -11,7 +11,7 @@ defined in this [paper](https://zenodo.org/records/13838652).
 - [Building the project](#building-the-project)
 - [Using the CLI](#using-the-cli)
 - [Input files](#input-files)
-- [Dev container](#dev-container)
+- [Defining a new model](#defining-a-new-model)
 
 ## Project Structure
 
@@ -25,6 +25,7 @@ The project is structured as follows:
     - `dotmat-introspector/`: Console app to introspect the contents of a .mat file.
     - `sacess/`: [External proyect](https://bitbucket.org/DavidPenas/sacess-library) adapted to enable the
       use of eSS in C.
+    - `mexpreval/`: Rust crate. Parses the model from the XML file to evaluate it.
 - `tests/`: Constains the tests of the cuqdyn-c library.
 - `CUQDyn/`: Contains the original Matlab project.
 
@@ -47,28 +48,29 @@ When running this software, there is a chance of generating an inf or NaN value.
 </ode_expr>
 ```
 
-If the value of `p2` generated by the eSS solver is 0, the ODE will generate an inf value. To avoid this, when the
-evaluation of the ODE generates an inf or NaN value, the software will set the value of the variable to 0. If you
-want to change this behavior, you can set the value you want the variable to take when an inf or NaN value is
-generated by setting the environment variable `CUQDYN_DEF_YDOT` to the value you want.
+If the value of `p2` generated by the eSS solver is 0, the model eval produces an inf value. To avoid this, when the
+evaluation of the ODE generates a non finite value, the software will set the value of the variable to 0. If you
+want to change this behavior, you can set the value you want the variable to take when an invalid value is
+generated by setting the environment variable `CUQDYN_DEF_YDOT` to the desired value.
 
 ### SACESS_SEED
 
-Set this variable if you want to set the seed used por the eSS solver instead of 
-picking a random one.
+Set this variable if you want to set the seed used by the eSS solver instead of 
+generating a random one.
 
 ## Building the project
 
 **GCC and GFortran v14 aren't supported by the project, so you need to use GCC v13 or lower.**
 
-The project has a `build.sh`.
+The project has a `build.sh` script.
 `build-[variant]/` directories will be created, each one representing a variant
 off the project they build. If you call the script without arguments, it will build
 all the variants, but you can also specify the variant you want, passing it as the
 first argument. The available variants are:
 
 - `serial`: Builds the project to only execute serial methods.
-- `mpi`: Builds the project to execute parallel methods using MPI and OpenMP.
+- `mpi`: Builds the project to execute the sequential solver in parallel using MPI.
+- `mpi2`: Builds the project to only include the MPI and OpenMP defined in sacess-library.
   After this, running `test.sh` is a good way to know if the cuqdyn library works as expected.
 
 ## Using the CLI
@@ -138,15 +140,18 @@ There are three types of input files needed to run the cli:
   this [link](https://bitbucket.org/DavidPenas/sacess-library/src/main/doc/manual/DOCUMENTATION_SACESS_SOFTWARE.pdf).
 - **cuqdyn config xml:**
   This file contains the configuration of the cuqdyn solver used in the cuqdyn-c library.
-  Right now, this file is just needed to define the rtol and atol used by the cvodes library.
+  This file defines the rtol and atol used by the cvodes library inside the tolerances block
+  and the ode model inside the ode_expr block. In the following example we define the Lotka Volterra model.
+  There is an option to accelerate the process of evaluating the ODE by defining it inside the 
+  mevalexpr module. We will talk about this later.
   ```xml
   <?xml version="1.0" encoding="UTF-8" ?>
 
   <cuqdyn-config>
       <tolerances>
           <rtol>1e-8</rtol>
-      <atol>1e-9, 1e-10</atol>
-          </tolerances>
+          <atol>1e-9, 1e-10</atol>
+      </tolerances>
       <ode_expr y_count="2" p_count="4">
           y1 * (p1 - p2 * y2)
           -y2 * (p3 - p4 * y1)
@@ -168,10 +173,54 @@ There are three types of input files needed to run the cli:
   30 1e1 5e1
   ```
 
-## Dev container
+## Defining a new model
 
-There is a definition file for a singularity container + a `dev_container.sh`
-script that builds a dev container with all the dependencies needed to build
-the project.
-The container doesn't contain a valid python installation
-to use the plot.py script, so this step should be done from the host.
+Using strings en evaluate them is slow compared to compiled instructions, so, to make this
+possible we designed a way to define the models in Rust and compile them to machine code.
+
+Lets going to dig into it with an example of the Lotka Volterra model:
+
+First of all, we need to write some Rust code. We will me using the following file
+`modules/mexpreval/src/models.rs`. Inside, we will create a new unit struct and implement 
+the Model trait like this:
+```Rust
+#[derive(Default)]
+struct LotkaVolterra;
+
+impl Model for LotkaVolterra {
+    fn eval(&self, _t: f64, y: &[f64], ydot: &mut [f64], p: &[f64]) {
+        ydot[0] = y[0] * (p[0] - p[1] * y[1]);
+        ydot[1] = - y[1] * (p[2] - p[3] * y[0]);
+    }
+}
+```
+
+Once the model is defined, we should give it an identifier:
+```Rust
+pub fn eval_model_fun(model: &str, ode_expr: &OdeExpr) -> Box<dyn Model> {
+    match model {
+        "lotka-volterra" => Box::new(LotkaVolterra::default()),
+        "alpha-pinene" | "α-pinene" => Box::new(AlphaPinene::default()),
+        _ => Box::new(GenericModel::new(ode_expr))
+    }
+}
+```
+
+After you establish an identifier in the match, at the bottom of the file, them model can be 
+used indicating the identifier in the XML config file like this:
+
+  ```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+
+  <cuqdyn-config>
+      <tolerances>
+          <rtol>1e-8</rtol>
+          <atol>1e-9, 1e-10</atol>
+      </tolerances>
+      <ode_expr y_count="2" p_count="4">
+          lotka-volterra
+      </ode_expr>
+  </cuqdyn-config>
+  ```
+
+Note that y_count and p_count are still present.