Merge pull request #1 from marouenbg/check-precision

v 0.2.1

Author: marouenbg

README.md

@@ -19,6 +19,7 @@ Add the project folder to your MATLAB path and save it.
 For the comparison with fastFVA (FFVA), you can install FFVA [here](http://wwwen.uni.lu/lcsb/research/mol_systems_physiology/fastfva).
 
 ### Quick installation
+This is a standard installation recipe, if this does not work, please install each dependency separately as specified in the [documentation](https://vffva.readthedocs.io/en/latest/).
 ```
 cd lib     
 source ./install.sh

data/comRes.mat

@@ -8,7 +8,7 @@ After installing the dependencies of `VFFVA`, you can build the binaries at the
 
 Then call `VFFVA` as follows:
 
-`mpirun -np nCores --bind-to none -x OMP_NUM_THREADS=nThreads veryfastFVA model.mps SCAIND`
+`mpirun -np nCores --bind-to none -x OMP_NUM_THREADS=nThreads veryfastFVA model.mps OPTPERC SCAIND`
 
 Replace the following variables with your own parameters:
 
@@ -18,6 +18,10 @@ Replace the following variables with your own parameters:
 
 + model.mps: the metabolic model in `.mps` format. To convert a model in `.mat` format to `.mps`, you can use the provided converter `convertProblem.m`
 
++ OPTPERC: Optimization percentage of the objective value (0-100). The default is 90, where VFFVa will be computed with the objective value set to 90% of the optimal
+objective.
+
+
 + SCAIND: (optional) corresponds to the scaling CPLEX parameter SCAIND and can take the values 0 (equilibration scaling: default), 1(aggressive scaling), -1 (no scaling).
 scaling is usually desactivated with tightly constrained metabolic model such as coupled models to avoid numerical instabilities and large solution times.
 
@@ -51,6 +55,8 @@ Then VFFVA.m can be called from MATLAB using the following function description:
     scaling:          CPLEX parameter. It corresponds to SCAIND parameter (Default = 0).
                       -1: no scaling; 0: equilibration scaling; 1: more aggressive scaling.
                       more information here: https://www.ibm.com/support/knowledgecenter/SSSA5P_12.7.0/ilog.odms.cplex.help/CPLEX/Parameters/topics/ScaInd.html.
+    optPerc:          Percentage of the optimal objective used in FVA. Float between 0 and 100. For example, when set to 90
+		      FVA will be computed on 90% of the optimal objective. 
     memAff:           none, core, or socket. (Default = none). This an OpenMPI parameter, more 
                       information here: https://www.open-mpi.org/faq/?category=tuning#using-paffinity-v1.4.
     schedule:         Dynamic, static, or guided. (Default = dynamic). This is an OpenMP parameter, more

docs/guide/index.md

@@ -8,16 +8,17 @@ The C implementation is a hybrid MPI/OpenMP code that has two levels of parallel
 and non-shared memory systems.
 
 ### Requirements
-+ Linux-based system.
++ Linux-based system (tested on Ubuntu 16.04 and 18.04).
 
-+ IBM CPLEX 12.6.3. and above [Free academic version.](http://www-03.ibm.com/software/products/fr/ibmilogcpleoptistud)
++ IBM CPLEX 12.6.3. (tested on 12.6.3 and 12.10) and above [Free academic version.](http://www.ibm.com/academic)
 
-+ OpenMP comes be default in the latest gcc version.
++ OpenMP comes be default in the latest gcc version (For macOs, OpenMp has to be installed separately)
 
 + MPI through the OpenMPI 1.10.3 implementation.
 
 ### Quick install
 
+This will install OpenMPI, IBM ILOG CPLEX 12.10 (Make sure you register at IBM Academic Initiative), and will set the environment variables.
 ```
 cd lib
 source ./install.sh
@@ -55,7 +56,7 @@ You might also need to add MPI path
 ```
 export PATH=$HOME/open-mpi/bin:$PATH
 ```
-+ IBM CPLEX: The recommended approach is to download [IBM CPLEX](http://www-03.ibm.com/software/products/fr/ibmilogcpleoptistud) and register for the free academic version.
++ IBM CPLEX: The recommended approach is to download [IBM CPLEX](http://www.ibm.com/academic) and register for the free academic version.
 
 Make sure that the CPLEXDIR path in `lib/Makefile` corresponds to the installation folder of CPLEX.
 
@@ -72,7 +73,7 @@ VFFVA.m is the MATLAB implementation that consists of a wrapper around the C ver
 
 + MATLAB
 
-+ IBM CPLEX 12.6.3. and above [Free academic version.](http://www-03.ibm.com/software/products/fr/ibmilogcpleoptistud)
++ IBM CPLEX 12.6.3. and above [Free academic version.](http://www.ibm.com/academic)
 
 + OpenMP comes be default in the latest gcc version.
 

docs/install/index.md

@@ -53,10 +53,23 @@ ecoli=model;
 + Compare the results
 
 ```
-plot(minFluxVFFVA,minFluxFVA,'o')
+%Using a log-log scale 
+figure;
+loglog(abs([minFluxVFFVA;maxFluxVFFVA]),abs([minFluxFVA;maxFluxFVA]),'o')
 hold on;
-plot([-40 100],[-40 100])
+loglog([0.1 1000],[0.1 1000])
 ```
 
 As we can see the results lie perfectly on the identity line.
 ![](images/VFFVAbenchmark.png)
+
+We can further check the largest difference in precision between the two results.
+Since we are using the same solver, the results are nearly identical.
+
+```
+max([minFluxVFFVA;maxFluxVFFVA]-[minFluxFVA;maxFluxFVA])
+
+ans =
+
+   4.9314e-07
+```

docs/tutos/images/VFFVAbenchmark.png

@@ -11,7 +11,7 @@ LIBFORMAT  = static_pic
 
 ifndef TRAVIS
 	#Please define CPLEX path here
-	CPLEXDIR      = $(HOME)/CPLEX_Studio12.7.1/cplex
+	CPLEXDIR      = $(HOME)/CPLEX_Studio1210/cplex
 	#CPLEXDIR      = /work/projects/cplex/soft/cplex/12.6.3/cplex/
 else
 	CPLEXDIR       = /home/travis/travis/cplex
@@ -45,7 +45,7 @@ CPLEXLIBDIR   = $(CPLEXDIR)/lib/$(SYSTEM)/$(LIBFORMAT)
 
 CLNDIRS   = -L$(CPLEXLIBDIR)
 CCLNFLAGS = -lconcert -lilocplex -lcplex -lm -lpthread
-CLNFLAGS  = -lcplex -lm -lpthread -lrt
+CLNFLAGS  = -lcplex -lm -lpthread -lrt -ldl
 
 
 

docs/tutos/index.md

@@ -1,4 +1,4 @@
-function [minFlux,maxFlux]=VFFVA(nCores, nThreads, model, scaling, memAff, schedule, nChunk)
+function [minFlux,maxFlux]=VFFVA(nCores, nThreads, model, scaling, memAff, schedule, nChunk, optPerc)
 % performs Very Fast Flux Variability Analysis (VFFVA). VFFVA is a parallel implementation of FVA that
 % allows dynamically assigning reactions to each worker depending on their computational load
 % Guebila, Marouen Ben. "Dynamic load balancing enables large-scale flux variability analysis." bioRxiv (2018): 440701.
@@ -18,6 +18,8 @@
 %    scaling:          CPLEX parameter. It corresponds to SCAIND parameter (Default = 0).
 %                      -1: no scaling; 0: equilibration scaling; 1: more aggressive scaling.
 %                      more information here: https://www.ibm.com/support/knowledgecenter/SSSA5P_12.7.0/ilog.odms.cplex.help/CPLEX/Parameters/topics/ScaInd.html.
+%    optPerc:          Percentage of the optimal objective used in FVA. Float between 0 and 100. For example, when set to 90
+%                      FVA will be computed on 90% of the optimal objective.
 %    memAff:           none, core, or socket. (Default = none). This an OpenMPI parameter, more 
 %                      information here: https://www.open-mpi.org/faq/?category=tuning#using-paffinity-v1.4.
 %    schedule:         Dynamic, static, or guided. (Default = dynamic). This is an OpenMP parameter, more
@@ -45,7 +47,9 @@
 if nargin<7
     nChunk=50;
 end
-
+if nargin<8
+   optPerc=90;
+end
 
 %Set install folder of MPI
 setenv('PATH', [getenv('PATH') ':' getenv('HOME') '/open-mpi/bin'])
@@ -76,7 +80,7 @@
 
 %Call VFFVA
 [status,cmdout]=system(['mpirun -np ' num2str(nCores) ' --bind-to ' num2str(memAff) ' -x OMP_NUM_THREADS=' num2str(nThreads)...
-    ' ./veryfastFVA ' model ' ' num2str(scaling)]);
+    ' ./veryfastFVA ' model ' ' num2str(optPerc)  ' ' num2str(scaling)]);
 
 %Fetch results
 resultFile=[model(1:end-4) 'output.csv'];

lib/Makefile

@@ -26,8 +26,8 @@ make install
 export PATH=$HOME/open-mpi/bin:$PATH
 
 #2. install IBM CPLEX
-VERSION_CPLEX=12.7.1
-wget "https://ak-dsw-mul.dhe.ibm.com/sdfdl/v2/fulfill/CNI55ML/Xa.2/Xb.wzt5iJcvdsf_6y3jnv4KVpeZrR1ITpFqw_nGoUyO9WgOsMy3zfirXa-luwtfb9Wxyg/Xc.CNI55ML/cplex_studio12.7.1.linux-x86-64.bin/Xd./Xf.lPr.D1VC/Xg.15048651/Xi.kivuto/XY.scholars/XZ.Kt3-euG55mrPls29B3kHipq8x0U/cplex_studio12.7.1.linux-x86-64.bin"
+VERSION_CPLEX=1210
+wget "https://ak-dsw-mul.dhe.ibm.com/sdfdl/v2/fulfill/CC439ML/Xa.2/Xb.XwdHXGddWvrm/Xc.CC439ML/cplex_studio1210.linux-x86-64.bin/Xd./Xf.lPr.D1VC/Xg.10615575/Xi./XY.scholars/XZ.unQjp7Yeq28Xo4Z12DgJGXx--L4/cplex_studio1210.linux-x86-64.bin#anchor"
 chmod +x cplex_studio$VERSION_CPLEX.linux-x86-64.bin
 
 #specify install options

lib/VFFVA.m

@@ -123,10 +123,10 @@ int main (int argc, char **argv){
 
 	/*Check arg number*/
 	if (rank==0){
-		if(( argc == 2 ) | ( argc == 3 )){
+		if(( argc == 2 ) | ( argc == 3 ) | (argc == 4)){
 			printf("\nThe model supplied is %s\n", argv[1]);
 			strcpy(modelName,argv[1]);
-		}else if( argc > 3 ) {
+		}else if( argc > 4) {
 			printf("Too many arguments supplied.\n");
 			goto TERMINATE;
 		}else {
@@ -182,16 +182,21 @@ int main (int argc, char **argv){
 	status = CPXsetintparam (env, CPX_PARAM_AUXROOTTHREADS, 2);
 
 	/*Scaling parameter if coupled model*/
-	if ( argc == 3 ) {
-		if (atoi(argv[2])==-1){
+	if ( argc == 4 ) {
+		if (atoi(argv[3])==-1){
 		/*Change of scaling parameter*/
 		scaling = 1;
 		status = CPXsetintparam (env, CPX_PARAM_SCAIND, -1);//1034 is index scaling parameter
 		status = CPXgetintparam (env, CPX_PARAM_SCAIND, &curpreind);
 		printf("SCAIND parameter is %d\n",curpreind);
 		}
 	}
-	
+
+	/*Read OptPercentage*/
+	if (argc > 2) {
+		optPerc=atoi(argv[2])/100.0;
+	}
+
 	/* Optimize the problem and obtain solution. */
 	clock_gettime(CLOCK_REALTIME, &tmstart);
 	status = CPXlpopt (env, lp);

lib/install.sh

@@ -52,8 +52,8 @@ case "$os" in
 esac
 
 #install IBM CPLEX
-VERSION_CPLEX=12.7.1
-wget "https://ak-dsw-mul.dhe.ibm.com/sdfdl/v2/fulfill/CNI55ML/Xa.2/Xb.wzt5iJcvdsf_6y3jnv4KVpeZrR1ITpFqw_nGoUyO9WgOsMy3zfirXa-luwtfb9Wxyg/Xc.CNI55ML/cplex_studio12.7.1.linux-x86-64.bin/Xd./Xf.lPr.D1VC/Xg.15048651/Xi.kivuto/XY.scholars/XZ.Kt3-euG55mrPls29B3kHipq8x0U/cplex_studio12.7.1.linux-x86-64.bin"
+VERSION_CPLEX=1210
+wget "https://ak-dsw-mul.dhe.ibm.com/sdfdl/v2/fulfill/CC439ML/Xa.2/Xb.XwdHXGddWvrm/Xc.CC439ML/cplex_studio1210.linux-x86-64.bin/Xd./Xf.lPr.D1VC/Xg.10615575/Xi./XY.scholars/XZ.unQjp7Yeq28Xo4Z12DgJGXx--L4/cplex_studio1210.linux-x86-64.bin#anchor"
 chmod +x cplex_studio$VERSION_CPLEX.linux-x86-64.bin
 
 #specify install options