Skip to content

Commit d57b95f

Browse files
authored
Refactor README.md for improved clarity
Removed unnecessary line breaks and fixed formatting issues for better readability.
1 parent c71b799 commit d57b95f

File tree

1 file changed

+14
-39
lines changed

1 file changed

+14
-39
lines changed

README.md

Lines changed: 14 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# Uncertainty Quantification in Dynamic Models of Biological Systems Using Conformal Prediction
22

3-
This project is a transpilation of the Matlab project
4-
defined in this [paper](https://zenodo.org/records/13838652).
3+
This project is a transpilation of the Matlab project defined in this [paper](https://zenodo.org/records/13838652).
54

65
## Index
76

@@ -46,10 +45,7 @@ When running this software, there is a chance of generating an inf or NaN value.
4645
</ode_expr>
4746
```
4847

49-
If the value of `p1` generated by the eSS solver is 0, the model eval produces an inf value. To avoid this, when the
50-
evaluation of the ODE generates a non-finite value, the software will set it to 0. If you
51-
want to change this behavior, you can set the value you want the variable to take when an invalid value is
52-
generated by setting the environment variable `CUQDYN_DEF_YDOT` to the desired value.
48+
If the value of `p1` 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 it 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.
5349

5450
### SACESS_SEED
5551

@@ -70,11 +66,7 @@ the default value.
7066

7167
**GCC and GFortran v14 aren't supported by the project, so you need to use GCC v13 or lower.**
7268

73-
The project has a `scripts/build.sh` script.
74-
`build-[variant]/` directories will be created, each one representing a variant
75-
off the project builded. If you call the script without arguments, it will build
76-
all the variants, but you can also specify the variant you want, passing it as the
77-
first argument. The available variants are:
69+
The project has a `scripts/build.sh` script. `build-[variant]/` directories will be created, each one representing a variant off the project builded. 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:
7870

7971
- `serial`: Builds the project to only execute serial methods.
8072
- `mpi`: Builds the project to execute the sequential solver in parallel using MPI.
@@ -90,8 +82,7 @@ docker compose up
9082

9183
## Using the CLI
9284

93-
After building using the `scripts/build.sh` script, you can execute this command to run the CLI
94-
with example config and data files like this:
85+
After building using the `scripts/build.sh` script, you can execute this command to run the CLI with example config and data files like this:
9586

9687
```bash
9788
mkdir output
@@ -123,19 +114,15 @@ VARIANT=serial
123114
-o output/
124115
```
125116

126-
After this, the file `output/cuqdyn-results.txt` contains the results of the
127-
algorithm but reading it as a plain text is not very useful.
128-
To fix this, you can run: (Needs python3 and matplotlib installed)
117+
After this, the file `output/cuqdyn-results.txt` contains the results of the algorithm but reading it as a plain text is not very useful. To fix this, you can run: (Needs python3 and matplotlib installed)
129118

130119
```bash
131120
python3 plot.py output/cuqdyn-results.txt
132121
```
133122

134-
Note: Be carefull when executing with `mpirun`, the number of precesses must be divisor
135-
of m - 1, where m is the number of rows in the input data matrix.
123+
Note: Be carefull when executing with `mpirun`, the number of precesses must be divisor of m - 1, where m is the number of rows in the input data matrix.
136124

137-
This will save a graphic representation for each y(t) in different png files
138-
inside the directory where the results are (output folder in this example).
125+
This will save a graphic representation for each y(t) in different png files inside the directory where the results are (output folder in this example).
139126

140127
To get information about all the options the cli supports, you can run the following command:
141128

@@ -156,22 +143,15 @@ to get the version of the cuqdyn-c lib, sacess lib and cli you are using.
156143
There are three types of input files that must be provided:
157144

158145
- **eSS Solver config xml:**
159-
This file contains the configuration of the eSS solver used in the sacess library.
160-
The specifications of this xml and how to build it are in
161-
this [link](https://bitbucket.org/DavidPenas/sacess-library/src/main/doc/manual/DOCUMENTATION_SACESS_SOFTWARE.pdf).
146+
This file contains the configuration of the eSS solver used in the sacess library. The specifications of this xml and how to build it are in this [link](https://bitbucket.org/DavidPenas/sacess-library/src/main/doc/manual/DOCUMENTATION_SACESS_SOFTWARE.pdf).
162147

163148
- **cuqdyn config xml:**
164149
This file contains the configuration of the cuqdyn solver used in the cuqdyn-c library.
165150
- **tolerances:** rtol and atol used by the cvodes library.
166151
- **ode_expr:** ODE model expression or identifier.
167-
- **time_scaling:** Scaling factor for time. Using lower than 1 helps cvodes speed. You may have to
168-
increase the number of sacess maxevals. The sacess lb, up, and point constraints also get scaled.
169-
The same for the params median written in the output file. Params that are dividing shouldn't be scaled
170-
as the testing shows but they get scaled as well. This helps the solver converge faster but hasn't
171-
been proved to be valid for all cases. This has been made with testing purposes, not recommended to use it.
152+
- **time_scaling:** Scaling factor for time. Using lower than 1 helps cvodes speed. You may have to increase the number of sacess maxevals. The sacess lb, up, and point constraints also get scaled. The same for the params median written in the output file. Params that are dividing shouldn't be scaled as the testing shows but they get scaled as well. This helps the solver converge faster but hasn't been proved to be valid for all cases. This has been made with testing purposes, not recommended to use it.
172153
- **y0:** Initial conditions of the ODE.
173-
- **states_transformer:** Transformations expressions or identidier applied to the different states in case of the
174-
observed data being a combination of the different states.
154+
- **states_transformer:** Transformations expressions or identidier applied to the different states in case of the observed data being a combination of the different states.
175155

176156
There is an option to accelerate the process of evaluating the ODE by defining it and the states transformer inside the mevalexpr module. We will talk about this later.
177157

@@ -216,8 +196,7 @@ There are three types of input files that must be provided:
216196
```
217197

218198
- **Data file:**
219-
The data file containing a mtrix of observed data and the initial value
220-
needed to solve the ODE. The data file should be a txt file written with the following format:
199+
The data file containing a mtrix of observed data and the initial value needed to solve the ODE. The data file should be a txt file written with the following format:
221200

222201
```
223202
# The first row is gonna be used as the initial condition if y0 is not present in the config file
@@ -231,14 +210,11 @@ There are three types of input files that must be provided:
231210

232211
## Defining a new model
233212

234-
Using strings and evaluate them is slow compared to compiled instructions, so, to make this
235-
possible, we designed a way to define the models in Rust and compile them to machine code.
213+
Using strings and 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.
236214

237215
Let's dig into it with an example of the Lotka Volterra model:
238216

239-
First of all, we need to write some Rust code. We will be using the following file
240-
`modules/cuqdyn-rs/src/models.rs`. Inside, we create a new unit struct and implement
241-
the Model trait like this:
217+
First of all, we need to write some Rust code. We will be using the following file `modules/cuqdyn-rs/src/models.rs`. Inside, we create a new unit struct and implement the Model trait like this:
242218

243219
```Rust
244220
#[derive(Default)]
@@ -264,8 +240,7 @@ pub fn eval_model_fun(model: &str, ode_expr: &OdeExpr) -> Box<dyn Model> {
264240
}
265241
```
266242

267-
After you establish an identifier in the match at the bottom of the file, the model can be
268-
used indicating the identifier in the XML config file like this:
243+
After you establish an identifier in the match at the bottom of the file, the model can be used indicating the identifier in the XML config file like this:
269244

270245
```xml
271246
<?xml version="1.0" encoding="UTF-8" ?>

0 commit comments

Comments
 (0)