Skip to content

Commit

Permalink
#646 split up instructions and make clearer what is optional
Browse files Browse the repository at this point in the history
  • Loading branch information
@valentinsulzer
valentinsulzer committed Oct 28, 2019
1 parent 102436d commit 6f00fc8
Show file tree
Hide file tree
Showing 27 changed files with 333 additions and 236 deletions.
186 changes: 4 additions & 182 deletions INSTALL-LINUX-MAC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,195 +97,17 @@ pip uninstall pybamm

## Optional dependencies

### [scikits.odes](https://github.com/bmcage/odes)

Users can install [scikits.odes](https://github.com/bmcage/odes) in order to use the
wrapped SUNDIALS ODE and DAE
[solvers](https://pybamm.readthedocs.io/en/latest/source/solvers/scikits_solvers.html).
The Sundials DAE solver is required to solve the DFN battery model in PyBaMM.

Before installing scikits.odes, you need to have installed:

- Python header files (`python-dev/python3-dev` on Debian/Ubuntu-based distributions, comes with python3 by default in brew)
- C compiler
- Fortran compiler (e.g. gfortran, comes with gcc in brew)
- BLAS/LAPACK install (OpenBLAS is recommended by the scikits.odes developers)
- CMake (for building Sundials)
- Sundials 3.1.1 (see instructions below)

You can install these on Ubuntu or Debian using apt-get:

```bash
sudo apt-get install python3-dev gfortran gcc cmake libopenblas-dev
```

or on a Mac OS distribution using brew:

```bash
brew install gcc cmake openblas
```

To install Sundials 3.1.1, on the command-line type:

```bash
INSTALL_DIR=`pwd`/sundials
wget https://computation.llnl.gov/projects/sundials/download/sundials-3.1.1.tar.gz
tar -xvf sundials-3.1.1.tar.gz
mkdir build-sundials-3.1.1
cd build-sundials-3.1.1/
cmake -DLAPACK_ENABLE=ON -DSUNDIALS_INDEX_TYPE=int32_t -DBUILD_ARKODE:BOOL=OFF -DEXAMPLES_ENABLE:BOOL=OFF -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR ../sundials-3.1.1/
make install
rm -r ../sundials-3.1.1
```

Then install [scikits.odes](https://github.com/bmcage/odes), letting it know the sundials install location:

```bash
SUNDIALS_INST=$INSTALL_DIR pip install scikits.odes
```

After this, you will need to set your `LD_LIBRARY_PATH` (for Linux) or `DYLD_LIBRARY_PATH` (for Mac) to point to the sundials
library - for Linux:

```bash
export LD_LIBRARY_PATH=$INSTALL_DIR/lib:$LD_LIBRARY_PATH
```

or for Mac:

```bash
export DYLD_LIBRARY_PATH=$INSTALL_DIR/lib:$DYLD_LIBRARY_PATH
```
Two DAE solvers (`scikits.odes` and `KLU`) can be optionally installed in PyBaMM. At least one of these is required to solve DAE models, such as the DFN, but you can install both if you like.

You may wish to put one of these lines in your `.bashrc` or virtualenv `activate` script,
which will save you needing to set your `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` every time you log in. For
example, to add this line to your `.bashrc` you can type:

```bash
echo "export LD_LIBRARY_PATH=$INSTALL_DIR/lib:\$LD_LIBRARY_PATH" >> ~/.bashrc
```
### [scikits.odes](https://github.com/bmcage/odes)

Please see the [scikits.odes
documentation](https://scikits-odes.readthedocs.io/en/latest/installation.html) for more
detailed installation instructions.
A python wrapper for the SUNDIALS ODE and DAE integrators. [Installation instructions](INSTALL-SCIKITS.md).

### Sundials with KLU sparse solver

If you wish so simulate large systems such as the 2+1D models, we recommend employing a
sparse solver. PyBaMM currently offers a direct interface to the sparse KLU solver within Sundials.
If you are on a linux based distribution, a bash script has been provided which should
install everything for you correctly. Please note you will require the python header files, openblas,
a c compiler (e.g. gcc), cmake, and suitesparse all of which you should be able to install, either on ubuntu using

```bash
apt install python3-dev libopenblas-dev cmake gcc libsuitesparse-dev
```

or on a Mac OS distribution using brew (`python3-dev` is installed by `python3`):

```bash
brew install gcc cmake openblas suitesparse
```

You will likely need to prepend `sudo` to the above command.

To install sundials with KLU, from within the main PyBaMM directory type

```bash
./scripts/install_sundials_4.1.0.sh
```

Note that this script has only been tested on Ubuntu 18.04.3 LTS. If this script does not work for you, you can try following the step-by-step instructions below:

#### Download and build Sundials 4.1.0

The KLU solver is interfaced using an updated version of Sundials so even if you have installed Sundials for use with Scikits.odes, you still need to install sundials here. If you want more information on the sundials installation please refer to the the ida_guide.pdf available at on the [sundials site](https://computing.llnl.gov/projects/sundials/sundials-software)

First, download Sundials 4.1.0 using

```bash
wget https://computing.llnl.gov/projects/sundials/download/sundials-4.1.0.tar.gz -O sundials-4.1.0.tar.gz
tar -xvf sundials-4.1.0.tar.gz
rm sundials-4.1.0.tar.gz
```

The cmake instructions provided with Sundials have trouble linking the required libraries related to the KLU solver, therefore we have provided a modified `CMakeLists.txt` file which fixes this. Copy this across into the sundials-4.1.0 folder, overwriting the old file, using

```bash
cp scripts/replace-cmake/CMakeLists.txt sundials-4.1.0/CMakeLists.txt
```

Now create a directory to build sundials in and set the install directory for sundials:

```bash
mkdir build-sundials-4.1.0
INSTALL_DIR=`pwd`/sundials4
```

Now enter the build directory, use cmake to generate the appropriate make files, and then build sundials and install sundials into the install directory using make:

```bash
cd build-sundials-4.1.0
cmake -DBLAS_ENABLE=ON\
-DLAPACK_ENABLE=ON\
-DSUNDIALS_INDEX_SIZE=32\
-DBUILD_ARKODE=OFF\
-DBUILD_CVODE=OFF\
-DBUILD_CVODES=OFF\
-DBUILD_IDAS=OFF\
-DBUILD_KINSOL=OFF\
-DEXAMPLES_ENABLE:BOOL=OFF\
-DCMAKE_INSTALL_PREFIX=$INSTALL_DIR\
-DKLU_ENABLE=ON\
../sundials-4.1.0
make install
```

Now return to your PyBaMM home directory and remove the build-sundials-4.1.0 folder and the download folder:

```bash
cd ..
rm -rf build-sundials-4.1.0
rm -rf sundials-4.1.0
```

#### Install pybind11
To interface with Sundials which is written in C, we require pybind11. Clone the pybind11 repository whilst within a folder the third-party folder:

```bash
mkdir third-party
cd third-party
git clone https://github.com/pybind/pybind11.git
cd ..
```

You will also require pybind11 to be pip installed so from within your virtual enviroment (if you are using one) type:

```bash
pip install pybind11
```

#### Build the KLU wrapper
We now have all the tools to build a shared library to interface to the KLU solver. Within your PyBaMM home directory build the required Makefile using

```bash
cmake .
```

This will automatically find the headers for the latest version of python installed on your machine. If you are using an older version (e.g python3.6) within your virtual environment, then you instead can use `cmake -DPYBIND11_PYTHON_VERSION=3.6 .`.

You can now simply run make to build the library (you can just run this command if you make some changes to klu.cpp)

```bash
make
```

To clean up you directory you can now remove the automatically generated cmake files:
```
rm -rf CMakeFiles
rm CMakeCache.txt
rm cmake_install.cmake
```
[Installation instructions](INSTALL-KLU.md).

## Troubleshooting

Expand Down
106 changes: 106 additions & 0 deletions INSTALL-SCIKITS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Install scikits.odes

---
**Note**

This file provides installation instructions for either Ubuntu-based distributions or Mac OS distributions. Please read carefully which lines to run in each case.

---


Users can install [scikits.odes](https://github.com/bmcage/odes) in order to use the
wrapped SUNDIALS ODE and DAE
[solvers](https://pybamm.readthedocs.io/en/latest/source/solvers/scikits_solvers.html).
The Sundials DAE solver is required to solve the DFN battery model in PyBaMM.

Before installing scikits.odes, you need to have installed:

- Python header files (`python-dev/python3-dev` on Debian/Ubuntu-based distributions, comes with python3 by default in brew)
- C compiler
- Fortran compiler (e.g. gfortran, comes with gcc in brew)
- BLAS/LAPACK install (OpenBLAS is recommended by the scikits.odes developers)
- CMake (for building Sundials)
- Sundials 3.1.1 (see instructions below)

You can install these on Ubuntu or Debian using apt-get:

```bash
sudo apt-get install python3-dev gfortran gcc cmake libopenblas-dev
```

or on a Mac OS distribution using brew:

```bash
brew install wget gcc cmake openblas
```

## Installing SUNDIALS and scikits.odes

### Option 1: install with script

We recommend that you first try to install SUNDIALS and scikits together by running the script

```bash
source scripts/install_scikits_odes.sh
```

If this works, skip to [the final section](#setting-library-path). Otherwise, try Option 2 below.

## Option 2: install manually


To install SUNDIALS 3.1.1 manually, on the command-line type:

```bash
INSTALL_DIR=`pwd`/sundials
wget https://computation.llnl.gov/projects/sundials/download/sundials-3.1.1.tar.gz
tar -xvf sundials-3.1.1.tar.gz
mkdir build-sundials-3.1.1
cd build-sundials-3.1.1/
cmake -DLAPACK_ENABLE=ON -DSUNDIALS_INDEX_TYPE=int32_t -DBUILD_ARKODE:BOOL=OFF -DEXAMPLES_ENABLE:BOOL=OFF -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR ../sundials-3.1.1/
make install
rm -r ../sundials-3.1.1
```

Then install [scikits.odes](https://github.com/bmcage/odes), letting it know the sundials install location:

```bash
SUNDIALS_INST=$INSTALL_DIR pip install scikits.odes
```

## Setting library path

After this, you will need to set your `LD_LIBRARY_PATH` (for Linux) or `DYLD_LIBRARY_PATH` (for Mac) to point to the sundials
library - for Linux:

```bash
export LD_LIBRARY_PATH=$INSTALL_DIR/lib:$LD_LIBRARY_PATH
```

or for Mac:

```bash
export DYLD_LIBRARY_PATH=$INSTALL_DIR/lib:$DYLD_LIBRARY_PATH
```

You may wish to put one of these lines in your `.bashrc` or virtualenv `activate` script,
which will save you needing to set your `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` every time you log in. For
example, to add this line to your virtual environment `env` you can type:

```bash
echo "export LD_LIBRARY_PATH=$INSTALL_DIR/lib:\$LD_LIBRARY_PATH" >> env/bin/activate
```

for Linux or

```bash
echo "export DYLD_LIBRARY_PATH=$INSTALL_DIR/lib:\$DYLD_LIBRARY_PATH" >> env/bin/activate
```

for Mac.

Please see the [scikits.odes
documentation](https://scikits-odes.readthedocs.io/en/latest/installation.html) for more
detailed installation instructions.

You can also try installing the [KLU solver](INSTALL-KLU.md) if you haven't already done so, but you only need one DAE solver.
6 changes: 3 additions & 3 deletions INSTALL-WINDOWS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,20 +18,20 @@ To download the PyBaMM source code, you first need to install git, which you can
typing

```bash
$ sudo apt install git-core
sudo apt install git-core
```

Now use git to clone the PyBaMM repository:

```bash
$ git clone https://github.com/pybamm-team/PyBaMM.git
git clone https://github.com/pybamm-team/PyBaMM.git
```

This will create a new directly called `PyBaMM`, you can move to this directory in bash
using the `cd` command:

```bash
$ cd PyBaMM
cd PyBaMM
```

If you are unfamiliar with the linux command line, you might find it useful to work through this
Expand Down
Loading

0 comments on commit 6f00fc8

Please sign in to comment.