Installation

 

Part 1: Platform-specific steps

 

Microsoft® Windows®

  1. Install Matlab 7.1 or higher (www.mathworks.com) on MS Windows 32 or 64 bit. PottersWheel is prepared for the 32 bit version of Matlab (independent on MS Windows being 32 or 64 bit). If you intend to use PottersWheel with Matlab 64 bit, please use the CVODES integrator. Turn off Aero on Vista or Windows 7 by using the windows classic theme if you have trouble to install an old Matlab version like R2006a.
  2. Configuration of the mex compiler
    Start MATLAB and type mex –setup. At the question prompt, type y to allow MATLAB to locate installed C compilers. With 32 bit Matlab 32 bit select the ‘lcc’ C compiler which is already included in Matlab. For 64 bit Matlab, you have to install a C compiler, e.g. the freely available Microsoft® Visual C++ 2008 Express Edition. A list of compatible compilers can be found here. If you are using a Microsoft Visual C++ compiler, please uncomment line 25 of the file asa_usr_asa.h: #include <float.h>
  3. Continue with the platform-independent steps.

 

Linux

  1. Open a shell terminal window and type 'g++ --version'. If a 'command not found' error appears, please install g++, e.g. using the command 'sudo apt-get install g++'. Do the same with the command 'gfortran'. Please compare the version of the g++ compiler with the supported compilers by Matlab. (Note: *.so files are runtime-libraries. Since PottersWheel compiles dynamically generated C files, also the developer-libraries (*.a) are required. When installing gcc/g++ make sure to select the developer version, often denoted by *-dev.)
  2. Install Matlab 7.1 or higher as a 32 or 64 bit version.
  3. Start Matlab and type 'mex -setup' into the command window in order to select gcc as the MEX compiler. A file 'mexopts.sh' will be created e.g. in /home/username/.matlab/R2008a/mexopts.sh.
  4. Set the current folder of Matlab to the PottersWheel toolbox folder, e.g. using 'cd /home/username/PottersWheelToolbox'.
  5. Type 'mex pwMexTest.c' and afterwards 'pwMexTest'. If a warning or error is issued, type 'help pwCompileFortranIntegrators' to receive further information on MEX compilation using Matlab.
  6. Type 'pwIntegratorMex1'. This should produce the message: "Invalid number of arguments". If not, type 'pwCompileFortranIntegrators'.
  7. Continue with the platform-independent steps.

 

Macintosh®

Though the core of Mac OS X is a POSIX compliant operating system, usually no C or Fortran compiler is included. While a Fortran compiler is required by PottersWheel only to use the Fortran integrators, a C compiler must be available. It is recommended to use the C compiler available together with XCode. Concerning Fortran, the free gfortran compiler can be used.

  1. Install Matlab 7.1 or higher as a 32 or 64 bit version
  2. Install XCode which requires registration as an Apple developer. Please make sure that you download a version of XCode which is supported by your Mac OS X version. Older XCode versions are available under Deverloper Downloads | Developer Tools. For Mac OS X 10.5 (Leopard) please install XCode 3.0, for Mac OS X 10.4 (Tiger) install version XCode 2.4.1. See the troubleshooting section below if you encounter problems like "gcc-4.2: command not found" on Mac OS X Lion.
  3. Recommended: Install gfortran from the CRAN archive or from GCC Wiki GFortranBinaries. The latter currently doesn't work for Mac Leopard. If you want to uninstall gfortran, run "sudo rm -r /usr/local/gfortran /usr/local/bin/gfortran". Important: Matlab is started by default in a different shell environment (SHLVL = 3) than the normal Mac command line. Therefore, the PATH variable of the terminal (SHLVL=1) is not available to Matlab and the gfortran compiler will not be found. To resolve this, change the first line of the file /Applications/MATLAB_2010a.app/bin/matlab from "#!/bin/sh" to "#!/bin/bash -l".
  4. Start Matlab and type 'mex -setup'. Select the gcc compiler (usually option 1). A file 'mexopts.sh' will be created e.g. in /home/username/.matlab/R2008a/mexopts.sh.
  5. Type 'pwIntegratorMex1'. This should produce the message: "Invalid number of arguments". If not, change into the PottersWheel installation folder and type 'pwCompileFortranIntegrators'.
  6. Continue with the platform-independent steps.

 

Part 2: Platform-independent steps

 

  1. Download and unzip the PottersWheel toolbox to a folder where you have write-access without needing administrator privileges, e.g. C:\Users\username\PottersWheel\PottersWheelToolbox. Blanks " " and brackets "(", ")" are not allowed in the path. The programs folder 'C:\Program Files' should not be used.
  2. Open Matlab (if possible with administrator priviliges) and change the Matlab current directory by clicking the triple dot icon on the MATLAB toolbar. Select the folder where all extracted PottersWheel files are stored. Click OK to continue.
  3. Type pwInstall at the Matlab command prompt and press the enter key to install PottersWheel. Essentially, the Matlab path is configured and the PottersWheel C MEX files are compiled for your system. If Matlab can't find the function pwInstall, make sure that you are in the right folder, e.g. by typing ls. When you have trouble to save the modified Matlab path, either start Matlab using administrator priviliges or save the pathdef.m file to the location where Matlab is started (which is the result of the pwd command when you start Matlab). On Windows 7 it is C:\Users\username\Documents\MATLAB. When you start Matlab from command line, e.g. on Linux systems, save the pathdef.m file into the corresponding working folder from where you start Matlab in your shell or DOS or terminal window. If you are not successful in saving the path, any PottersWheel command won't be available in Matlab (unless you are still in the PottersWheel toolbox folder).
  4. Now PottersWheel has been installed. It is recommended to create a project folder at a location of your choice using e.g. the Windows file explorer, for example C:\Modeling\Project01. Create subfolders Data, Models, WorkingFolder. Set the Matlab current directory to WorkingFolder:
    Set working folder


  5. Type pw to start PottersWheel. Follow the tutorials and the videos in the documentation section, e.g. First Steps.
  6. If PottersWheel is not working correctly, please check the installation by typing pwCheckSystem. If you cannot resolve the problem, send the output of pwCheckSystem and the error message to support at potterswheel de.
  7. Type warning('off', 'MATLAB:oldPfileVersion') to avoid warnings about old pcode files in PW prior to 2.0.55.

 

Part 3: Optional tools

 

  1. SSm GO Toolbox
    Go to http://www.iim.csic.es/~gingproc/ssmGO.html and download the scatter search for global optimization toolbox, which is required to use all ssm based optimization strategies in PottersWheel. Before installation, request the password to unzip the toolbox by emailing the authors as described on the SSm GO download page. Please replace the file ssm_localsolver.p (<= Matlab 7.4, >= Matlab 7.5).
  2. Latex
    Install a Latex distribution like MikTex (http://www.miktex.org/) for Latex based pdf documentation.
  3. R
    Install the statistics program R (www.r-project.org), if you do not have the splines toolbox from MATLAB and want to use splined driving inputs or spline based error bar estimation.
  4. asamin
    The adaptive simulated annealing algorithm asamin may need configuration of a header .h file for successful compilation. If compilation fails, the error message 'attempting to run SCRIPT asamin as a function' will show up. In this case, please include the <float.h> header: Change the file asa_usr_asa.h by removing all comment signs in the line #include <float.h> and run pwInstall again. If you still receive the same error message, please run 'which asamin -all'. If compilation was successful, you should receive '.../asamin.mexw32' and '.../asamin.m % Shadowed'. Otherwise try to compile asamin.c manually using 'mex asamin.c asa.c -DUSER_ACCEPTANCE_TEST#TRUE -DUSER_ASA_OUT#TRUE'.
  5. Graphviz
    Install Graphviz from http://www.graphviz.org. Graphviz is used for automatic species positioning in the PottersWheel Model Designer.
  6. SBML toolbox
    If you often import SBML models, you can install the SBML toolbox from http://sbml.org/software/sbmltoolbox. Alternatively, use the PottersWheel web service to convert SBML files, since the SBML toolbox installation might not be straightforward on your system, especially for Matlab R2006b and below due to incompatible mex libraries.
  7. CVODES
    Install the Sundials Matlab toolbox in order to apply the CVODES integrator. Please follow the description given in pwInstallSundialsTB. Call pwSetIntegrator(14) after starting PottersWheel to set the used integrator to CVODES. Attention: The sundialsTB toolbox uses a Matlab C function named "mxCreateScalarDouble". Instead it should be written as "mxCreateDoubleScalar". The old spelling is not supported in recent Matlab versions since R2011a. You have to correct the spelling manually in sundialsTB\cvodes\cvm\src\cvm.c and sundialsTB\cvodes\cvm\src\cvmWrap.c, e.g. using the Matlab editor.
  8. Fast integration
    In order to use fast numerical integration, platform-dependent external C and Fortran compiler are required. For MS Windows 32 or 64 bit, please download lcc-win32.exe from http://www.cs.virginia.edu/~lcc-win32/ and install it in C:\lcc if possible. Download fortran.exe from http://gd.tuwien.ac.at/languages/c/lcc/ or http://www.filewatcher.com/m/fortran.exe.453574.0.0.html and install it into the same folder C:\lcc. (On Windows 7 you might receive an error for creating a registry key. Then use the compatibility mode for Windows XP SP 2; see context menu by right-clicking on lcc-win32.exe and fortran.exe). The folder C:\lcc\bin has to be added to the Windows PATH variable: Select Start > My Computer, then right click and select Properties > Advanced > Environmental Variables > System Variables > PATH. Here you will see a list of program folders separated by semicolon (;). Just append ';C:\lcc\bin'. (Matlab has to be restarted after changing the Windows path variable.)

    In order to activate fast integration use the setting:
    config = pwGetConfig;
    config.integration.useFastIntegration = true;
    pwSetConfig(config);

    This can also be achieved in the configuration dialog under Fields | integration | useFastIntegration.

 

Troubleshooting

 

Microsoft® Windows®

  1. If pwCheckSystem cannot find one of the installed external programs Graphviz, R or Latex, open a Windows command window (in Windows XP, select Start and then Run. Type cmd to call the DOS prompt).
    • Type ‘dot –V’, ‘R’, or ‘latex –version’, respectively.
    • If the program is not available, you must change the system PATH variable.
    • To access the PATH variable, select Start > My Computer, then right click and select Properties > Advanced > Environmental Variables > System Variables > PATH. Here you will see a list of program folders separated by semicolon (;).
    • Just append the missing program, e.g. ‘;C:\Program Files\R\R-2.2.0\bin’ for R, or ‘;C:\Program Files\ATT\Graphviz\bin’ for Graphviz.
    • Close and reopen the Windows command window and check whether Windows finds the programs now.
    • If Rterm, instead of R is available, go to the R installation folder and copy Rterm.exe to R.exe.
    • Restart MATLAB after a change to the PATH variable is instituted
  2. Please contact support at potterswheel de and provide the error message and the output of pwCheckSystem.

Linux and Mac

  1. Please contact support at potterswheel de and provide the error message, the output of pwCheckSystem and if possible the mexopts.sh file located in /Users/<name>/.matlab/<Matlab version>/mexopts.sh.

Mac OS X Lion

Some users encounter error messages as following when trying to install PottersWheel on a Mac OS X Lion computer:

Installing../Applications/MATLAB_R2011b.app/bin/mex: line 305: gcc-4.2: command not found
/Applications/MATLAB_R2011b.app/bin/mex: line 1285: gcc-4.2: command not found
 mex: compile of ' "Mex_Adler32.c"' failed.

or

Installing../Applications/MATLAB_R2010b.app/bin/mex: line 305: gcc-4.0: command not found
/Applications/MATLAB_R2010b.app/bin/mex: line 1041: gcc-4.0: command not found

In this case, please proceed as follows (exemplified for gcc-4.2):

1) Install the Xcode Command Line Tools
Open Xcode,
Go to Xcode->Preferences
Open the downloads tab. Install the "Command Line Tools". You'll have to register your apple.com login as a developer
(which should be free).

2) Configure mexopts.sh

The path to developer tools/gcc may need to be changed in the mexopts.sh. Lion may put these tools in a different location than expteced. Go down to the maci64 section and set the following.

CC='llvm-gcc-4.2'

SDKROOT='/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk'